---
title: Configuration Reference
description: Where Caracal configuration lives, which pages own each configuration surface, and the client-side schemas used by tools and SDKs.
pageType: reference
---

Caracal has three configuration surfaces:

| Surface | Owner | Use |
| --- | --- | --- |
| Service environment variables | [Environment Variables](../operations/env-vars/) | Runtime configuration for STS, API, Gateway, Coordinator, Audit, infrastructure, and optional services |
| `caracal.toml` | CLI and TUI | Local client identity, API targets, credential forwarding, and governance mode |
| SDK constructors and environment variables | SDK packages | Application integration, context propagation, and client-secret token refresh |

Use [Environment Variables](../operations/env-vars/) as the source of truth for service startup requirements and defaults. This page keeps the client-facing configuration schemas together so CLI, TUI, SDK, and agent integrations can use one reference without duplicating service tables.

---

## Service configuration

All services are configured through environment variables. Required variables fail at startup when absent. Optional variables use implementation defaults.

Read the canonical service table in [Environment Variables](../operations/env-vars/). It is grouped by service and covers:

- Shared secrets: `ZONE_KEK`, `AUDIT_HMAC_KEY`, `STREAMS_HMAC_KEY`
- Infrastructure: Postgres and Redis
- Core services: STS, API, Gateway, Audit, Coordinator
- Optional control service
- Mode: `CARACAL_MODE=dev` for development, `CARACAL_MODE=rc` for rc, `CARACAL_MODE=stable` for stable

---

## Key local ports

| Service | Local binding | Purpose |
| --- | --- | --- |
| API | `127.0.0.1:3000` | Control-plane REST and CLI target |
| STS | `127.0.0.1:8080` | Token exchange and JWKS endpoint |
| Gateway | `127.0.0.1:8081` | Reverse proxy for protected resources |
| Coordinator | `127.0.0.1:4000` | Agent lifecycle, invocations, and delegation graph |
| Audit | `127.0.0.1:9090` | Audit ingestion status, query, and export status |
| Control | `127.0.0.1:8087` | Optional automation endpoint enabled only through `caracal-cli control` or the TUI Control menu |
| PostgreSQL | `127.0.0.1:5432` | Database access from local tools |
| Redis | `127.0.0.1:6379` | Redis CLI debugging |

The reference compose stack binds every port to `127.0.0.1`. Production deployments should keep API, STS, Coordinator, Audit, Postgres, and Redis on private networks. Expose the Gateway, or a TLS-terminating load balancer in front of it, only when it is the intended public ingress.

---

## `caracal.toml`

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

1. `CARACAL_CONFIG`, when set
2. `./caracal.toml` in the current working directory
3. `$XDG_CONFIG_HOME/caracal/caracal.toml`, or `~/.config/caracal/caracal.toml` when `XDG_CONFIG_HOME` is unset

### Schema

```toml
zone_url          = "http://localhost:3000"
zone_id           = "zone-abc123"
application_id    = "app-xyz456"
app_client_secret = "secret-..."
continue_on_failure = false

[[credentials]]
env      = "DATABASE_URL"
resource = "postgres"

[[optional_credentials]]
env        = "SLACK_TOKEN"
resource   = "slack"
on_failure = "warn"

[mcp_governance]
mode = "block"
```

### Field reference

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `zone_url` | string | Yes | Control-plane API base URL used by CLI admin commands |
| `zone_id` | string | Yes | Zone this client operates in |
| `application_id` | string | Yes | Registered application identity |
| `app_client_secret` | string | Yes | Application secret used for STS token exchange |
| `continue_on_failure` | boolean | No | Continue after non-fatal command failures; default `false` |
| `credentials` | array | No | Required external credentials forwarded to named resources |
| `credentials[].env` | string | Yes, inside each item | Environment variable containing the credential value |
| `credentials[].resource` | string | Yes, inside each item | Resource identifier associated with the credential |
| `optional_credentials` | array | No | External credentials that may be absent |
| `optional_credentials[].env` | string | Yes, inside each item | Environment variable containing the credential value |
| `optional_credentials[].resource` | string | Yes, inside each item | Resource identifier associated with the credential |
| `optional_credentials[].on_failure` | `"warn" \| "error"` | Yes, inside each item | Whether absence should warn or fail |
| `mcp_governance.mode` | `"block" \| "log"` | No | Whether unauthorized MCP tool calls are blocked or only recorded |

---

## SDK environment variables

The TypeScript, Python, and Go SDKs support two authentication modes:

| Mode | Required variables | Use |
| --- | --- | --- |
| Static session mandate | `CARACAL_COORDINATOR_URL`, `CARACAL_ZONE_ID`, `CARACAL_APPLICATION_ID`, `CARACAL_SUBJECT_TOKEN` | Use when another trusted component already issued the session mandate |
| Client secret | `CARACAL_COORDINATOR_URL`, `CARACAL_ZONE_ID`, `CARACAL_APPLICATION_ID`, `CARACAL_APP_CLIENT_SECRET`, `CARACAL_STS_URL`, plus resources | Use when the SDK should exchange the application secret for a session mandate and refresh it automatically |

Client-secret mode needs at least one resource. Supply resources with `CARACAL_APP_RESOURCES`, `CARACAL_RESOURCES`, or `CARACAL_RESOURCES_FILE` depending on SDK support.

| Variable | Description |
| --- | --- |
| `CARACAL_COORDINATOR_URL` | Coordinator base URL, for example `http://localhost:4000` |
| `CARACAL_ZONE_ID` | Zone identifier |
| `CARACAL_APPLICATION_ID` | Registered application identifier |
| `CARACAL_SUBJECT_TOKEN` | Session mandate for static-token mode |
| `CARACAL_APP_CLIENT_SECRET` | Application secret for client-secret mode |
| `CARACAL_STS_URL` | STS base URL for client-secret mode |
| `CARACAL_APP_RESOURCES` | Comma-separated resource IDs used as STS audiences |
| `CARACAL_GATEWAY_URL` | Gateway base URL for resource-routed calls |
| `CARACAL_RESOURCES` | Comma-separated `resourceId=upstreamPrefix` bindings |
| `CARACAL_RESOURCES_FILE` | JSON resource-binding file supported by the Python SDK |

See the language references for exact constructors:

- [TypeScript SDK](../sdks/typescript/)
- [Python SDK](../sdks/python/)
- [Go SDK](../sdks/go/)

---

## SDK config types

### TypeScript

```typescript
import { Caracal, AgentKind } from '@caracalai/sdk';

const client = new Caracal({
  coordinator: { baseUrl: 'http://localhost:4000' },
  zoneId: 'zone-abc123',
  applicationId: 'app-xyz456',
  subjectToken: 'subject-jwt-...',
  gatewayUrl: 'http://localhost:8081',
  resources: [
    { resourceId: 'resource://inventory', upstreamPrefix: 'http://inventory:8080' },
  ],
  defaultKind: AgentKind.Instance,
  defaultTtlSeconds: 3600,
});
```

### Python

```python
from caracalai_sdk import Caracal, CaracalConfig
from caracalai_sdk.advanced import AgentKind, CoordinatorClient, ResourceBinding

client = Caracal(CaracalConfig(
    coordinator=CoordinatorClient(base_url='http://localhost:4000'),
    zone_id='zone-abc123',
    application_id='app-xyz456',
    subject_token='subject-jwt-...',
    gateway_url='http://localhost:8081',
    resources=[
        ResourceBinding(
            resource_id='resource://inventory',
            upstream_prefix='http://inventory:8080',
        ),
    ],
    default_kind=AgentKind.INSTANCE,
    default_ttl_seconds=3600,
))
```

### Go

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

client := &sdk.Caracal{
    Coordinator:       &sdk.CoordinatorClient{BaseURL: "http://localhost:4000"},
    ZoneID:            "zone-abc123",
    ApplicationID:     "app-xyz456",
    SubjectToken:      "subject-jwt-...",
    GatewayURL:        "http://localhost:8081",
    Resources: []sdk.ResourceBinding{
        {ResourceID: "resource://inventory", UpstreamPrefix: "http://inventory:8080"},
    },
    DefaultKind:       sdk.KindInstance,
    DefaultTTLSeconds: 3600,
}
```

---

## CLI environment variables

| Variable | Description |
| --- | --- |
| `CARACAL_CONFIG` | Override `caracal.toml` discovery |
| `CARACAL_HOME` | Installed runtime home (overrides, compose, secrets) |
| `CARACAL_ADMIN_TOKEN_FILE` | Explicit path to a file containing the admin token |
| `CARACAL_MODE` | Stack mode: `dev`, `rc`, or `stable` |
| `CARACAL_API_URL` | Control-plane 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` | Session mandate for SDK initialization |
| `CARACAL_GATEWAY_URL` | Gateway URL for resource routing |
| `CARACAL_RESOURCES` | Comma-separated resource bindings |
| `XDG_CONFIG_HOME` | Base directory for `caracal.toml` discovery |
| `XDG_DATA_HOME` | Base directory for runtime assets |
