Configuration Reference

Caracal services are configured entirely through environment variables. There are no config files for services. Client-side tooling uses caracal.toml. SDKs accept typed config structs.

Jump to: Postgres · Redis · STS · API · Gateway · Coordinator · Audit · caracal.toml · SDK config types · CLI env vars

Postgres

All services read DATABASE_URL to connect to Postgres.

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	PostgreSQL connection string (`postgres://user:pass@host:port/db`)

Redis

All services read REDIS_URL to connect to Redis.

Variable	Required	Default	Description
`REDIS_URL`	Yes	—	Redis connection URL (`redis://:pass@host:6379`)
`REDIS_PASSWORD`	No	—	Alternative to embedding the password in `REDIS_URL`

Redis must be configured with maxmemory-policy noeviction. Stream data uses db0; rate limit data uses db1.

STS

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	Postgres connection string
`REDIS_URL`	Yes	—	Redis connection string
`ZONE_KEK`	Yes	—	32-byte hex-encoded Key Encryption Key for zone signing keys; must not be all zeros
`OPA_URL`	Yes	—	OPA REST API base URL (e.g., `http://opa:8181`)
`AUDIT_STREAM_URL`	No	`REDIS_URL`	Redis URL for audit event publishing, if separate from main Redis
`STREAMS_HMAC_KEY`	No	—	Hex-encoded key for HMAC-signing audit stream messages; if unset, messages are unsigned
`TLS_CERT_FILE`	No	—	Path to TLS certificate PEM for HTTPS; both `TLS_CERT_FILE` and `TLS_KEY_FILE` must be set together
`TLS_KEY_FILE`	No	—	Path to TLS private key PEM
`INSECURE_HTTP`	No	`false`	Allow HTTP (no TLS) in production mode; unsafe — for local development only
`LOG_LEVEL`	No	`info`	Log verbosity: `debug`, `info`, `warn`, `error`
`PORT`	No	`8080`	Listening port

Key cache: Zone signing keys are cached in-memory for 15 minutes. Changes to zone keys (e.g., after rotation) take effect within one cache TTL.

API

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	Postgres connection string
`REDIS_URL`	Yes	—	Redis connection string
`ADMIN_TOKEN`	Yes	—	Bearer token required for all `/v1/*` admin routes
`STS_URL`	Yes	—	Internal URL of the STS service (e.g., `http://sts:8080`)
`INSECURE_STS`	No	`false`	Skip TLS verification when calling STS; for internal networks with self-signed certs only
`OUTBOX_POLL_MS`	No	`250`	Milliseconds between outbox poll cycles
`OUTBOX_BATCH_SIZE`	No	`32`	Events per outbox poll batch
`OUTBOX_MAX_ATTEMPTS`	No	`100`	Maximum delivery attempts per outbox row before marking dead
`TLS_CERT_FILE`	No	—	Path to TLS certificate PEM
`TLS_KEY_FILE`	No	—	Path to TLS private key PEM
`LOG_LEVEL`	No	`info`	Log verbosity
`PORT`	No	`3000`	Listening port

Gateway

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	Postgres connection string
`REDIS_URL`	Yes	—	Redis connection string
`STS_URL`	Yes	—	Internal URL of the STS service
`BINDINGS_RELOAD_MS`	No	`30000`	How often (ms) to reload resource bindings from Postgres
`JTI_CACHE_SIZE`	No	`10000`	Maximum entries in the JTI replay cache
`TLS_CERT_FILE`	No	—	Path to TLS certificate PEM
`TLS_KEY_FILE`	No	—	Path to TLS private key PEM
`LOG_LEVEL`	No	`info`	Log verbosity
`PORT`	No	`8081`	Listening port

Coordinator

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	Postgres connection string
`REDIS_URL`	Yes	—	Redis connection string
`OUTBOX_POLL_MS`	No	`1000`	Milliseconds between outbox poll cycles
`OUTBOX_BATCH_SIZE`	No	`50`	Events per outbox poll batch
`OUTBOX_MAX_ATTEMPTS`	No	`10`	Maximum delivery attempts per outbox row before marking dead
`MAX_DEPTH`	No	`10`	Maximum agent session nesting depth
`MAX_CHILDREN`	No	`10`	Maximum child sessions per parent
`MAX_PER_ZONE`	No	`50`	Maximum concurrent agent sessions per zone
`MAX_PER_APP`	No	`200`	Maximum concurrent agent sessions per application
`DEFAULT_TTL_SECONDS`	No	`3600`	Default agent session TTL in seconds
`TLS_CERT_FILE`	No	—	Path to TLS certificate PEM
`TLS_KEY_FILE`	No	—	Path to TLS private key PEM
`LOG_LEVEL`	No	`info`	Log verbosity
`PORT`	No	`4000`	Listening port

Audit

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	Postgres connection string
`REDIS_URL`	Yes	—	Redis connection string
`AUDIT_HMAC_KEY`	Yes	—	Hex-encoded key for HMAC-SHA256 chain verification
`STREAMS_HMAC_KEY`	No	—	Hex-encoded key for verifying stream message signatures from STS
`AUDIT_RETENTION_DAYS`	No	`365`	How many days of audit events to retain; partitions older than this are dropped
`AUDIT_MAX_DELIVERIES`	No	`5`	Maximum delivery attempts per audit event before routing to DLQ
`AUDIT_EXPORT_S3_BUCKET`	No	—	S3 bucket name for Parquet export; export is disabled if unset
`AUDIT_EXPORT_S3_ENDPOINT`	No	AWS default	S3-compatible endpoint URL (use for MinIO or other non-AWS stores)
`AUDIT_EXPORT_S3_REGION`	No	`us-east-1`	S3 region
`AWS_ACCESS_KEY_ID`	No	—	AWS credentials for S3 export; uses instance profile if unset
`AWS_SECRET_ACCESS_KEY`	No	—	AWS credentials for S3 export
`TLS_CERT_FILE`	No	—	Path to TLS certificate PEM
`TLS_KEY_FILE`	No	—	Path to TLS private key PEM
`LOG_LEVEL`	No	`info`	Log verbosity
`PORT`	No	`9090`	Listening port

`caracal.toml`

caracal.toml is the client-side configuration file used by the CLI. It is discovered in this order:

Path in CARACAL_CONFIG environment variable (if set)
./caracal.toml in the current working directory
$XDG_CONFIG_HOME/caracal/caracal.toml (defaults to ~/.config/caracal/caracal.toml)

Schema

# Required fields
zone_url          = "https://your-caracal-api.example.com"
zone_id           = "zone-abc123"
application_id    = "app-xyz456"
app_client_secret = "secret-..."

# Optional fields
continue_on_failure = false   # If true, CLI continues after non-fatal errors

# Named credentials forwarded to external services
[[credentials]]
env      = "DATABASE_URL"     # Environment variable holding the credential value
resource = "postgres"         # Resource identifier this credential is for

# Optional credentials that warn or error if missing
[[optional_credentials]]
env        = "SLACK_TOKEN"
resource   = "slack"
on_failure = "warn"           # "warn" or "error"

# MCP governance mode
[mcp_governance]
mode = "block"                # "block" or "log"

Field reference

Field	Type	Required	Description
`zone_url`	string	Yes	Base URL of the Caracal API service
`zone_id`	string	Yes	Zone this client operates in
`application_id`	string	Yes	Application identity for credential exchange
`app_client_secret`	string	Yes	Client secret for application authentication
`continue_on_failure`	boolean	No	Whether to continue after non-fatal errors (default: `false`)
`credentials`	array	No	Named credentials to forward to external services
`credentials[].env`	string	Yes (in block)	Environment variable containing the credential value
`credentials[].resource`	string	Yes (in block)	Resource identifier the credential is for
`optional_credentials`	array	No	Credentials that may be absent; controls failure behavior
`optional_credentials[].on_failure`	string	Yes (in block)	`"warn"` or `"error"`
`mcp_governance.mode`	string	No	`"block"` (reject unauthorized tool calls) or `"log"` (permit but record)

SDK config types

TypeScript

import { Caracal } from '@caracal/sdk';
import { CoordinatorClient } from '@caracal/sdk';

const client = new Caracal({
  coordinator: new CoordinatorClient({ baseUrl: 'http://localhost:4000' }),
  zoneId: 'zone-abc123',
  applicationId: 'app-xyz456',
  subjectToken: 'subject-jwt-...',

  // Optional
  gatewayUrl: 'http://localhost:8081',
  resources: [
    { resourceId: 'api', upstreamPrefix: 'http://upstream:3000' }
  ],
  defaultKind: 'instance',    // AgentKind: 'instance' | 'ephemeral'
  defaultTtlSeconds: 3600,
});

CaracalConfig interface:

Field	Type	Required	Description
`coordinator`	`CoordinatorClient`	Yes	Coordinator connection
`zoneId`	`string`	Yes	Zone identifier
`applicationId`	`string`	Yes	Application identifier
`subjectToken`	`string`	Yes	Subject identity token
`gatewayUrl`	`string`	No	Gateway URL for resource routing
`resources`	`ResourceBinding[]`	No	Resource-to-upstream mappings
`defaultKind`	`AgentKind`	No	Default agent kind for spawned sessions
`defaultTtlSeconds`	`number`	No	Default TTL for spawned sessions

Python

from caracalai_sdk import Caracal, CaracalConfig, CoordinatorClient, ResourceBinding

client = Caracal(CaracalConfig(
    coordinator=CoordinatorClient(base_url='http://localhost:4000'),
    zone_id='zone-abc123',
    application_id='app-xyz456',
    subject_token='subject-jwt-...',

    # Optional
    gateway_url='http://localhost:8081',
    resources=[ResourceBinding(resource_id='api', upstream_prefix='http://upstream:3000')],
    default_kind=AgentKind.INSTANCE,
    default_ttl_seconds=3600,
))

CaracalConfig dataclass:

Field	Type	Required	Description
`coordinator`	`CoordinatorClient`	Yes	Coordinator connection
`zone_id`	`str`	Yes	Zone identifier
`application_id`	`str`	Yes	Application identifier
`subject_token`	`str`	Yes	Subject identity token
`gateway_url`	`str \| None`	No	Gateway URL for resource routing
`resources`	`list[ResourceBinding]`	No	Resource-to-upstream mappings
`default_kind`	`AgentKind`	No	Default agent kind for spawned sessions
`default_ttl_seconds`	`int \| None`	No	Default TTL for spawned sessions

Go

import (
    sdk "github.com/garudex/caracal/packages/sdk/go"
)

client := &sdk.Caracal{
    Coordinator:       coordinator,     // *CoordinatorClient
    ZoneID:            "zone-abc123",
    ApplicationID:     "app-xyz456",
    SubjectToken:      "subject-jwt-...",

    // Optional
    GatewayURL:        "http://localhost:8081",
    Resources:         []sdk.ResourceBinding{
        {ResourceID: "api", UpstreamPrefix: "http://upstream:3000"},
    },
    DefaultKind:       sdk.AgentKindInstance,
    DefaultTTLSeconds: 3600,
}

Caracal struct:

Field	Type	Required	Description
`Coordinator`	`*CoordinatorClient`	Yes	Coordinator connection
`ZoneID`	`string`	Yes	Zone identifier
`ApplicationID`	`string`	Yes	Application identifier
`SubjectToken`	`string`	Yes	Subject identity token
`GatewayURL`	`string`	No	Gateway URL for resource routing
`Resources`	`[]ResourceBinding`	No	Resource-to-upstream mappings
`DefaultKind`	`AgentKind`	No	Default agent kind for spawned sessions
`DefaultTTLSeconds`	`int`	No	Default TTL for spawned sessions

CLI environment variables

Environment variables that affect the CLI and SDK runtime when caracal.toml is not in use:

Variable	Description
`CARACAL_CONFIG`	Override path to `caracal.toml`
`CARACAL_ENV_FILE`	Override path to `.env` file loaded by the CLI
`CARACAL_API_URL`	API base URL (default: `http://localhost:3000`)
`CARACAL_COORDINATOR_URL`	Coordinator base URL (default: `http://localhost:4000`)
`CARACAL_COORDINATOR_TOKEN`	JWT with `agent:lifecycle` scope for coordinator routes
`CARACAL_ADMIN_TOKEN`	Bearer token for admin API routes
`CARACAL_ZONE_ID`	Default zone ID for admin commands
`CARACAL_APPLICATION_ID`	Application ID for SDK initialization
`CARACAL_SUBJECT_TOKEN`	Subject token for SDK initialization
`CARACAL_GATEWAY_URL`	Gateway URL for resource routing
`CARACAL_RESOURCES`	Comma-separated resource bindings: `resourceId=prefix,resourceId2=prefix2`
`XDG_CONFIG_HOME`	Base directory for `caracal.toml` discovery
`XDG_DATA_HOME`	Base directory for runtime assets