The single source of truth for what a deployment needs is the settings
inventory surfaced by cairn doctor (and cairn deploy doctor for the
compose stack). This page lists the variables a deployer actually reaches
for. Most engine variables carry the historical OBS_ prefix.
| Variable | Controls | Default |
|---|
OBS_STORAGE | run + config store backend: postgres://… or sqlite:///path | unset → per-store SQLite / in-memory |
OBS_RUNTIME | graph executor: inprocess / dbos / temporal | inprocess |
OBS_CHECKPOINTER | HITL/thread durability: memory / sqlite / postgres | memory |
OBS_CHECKPOINTER_PATH / OBS_CHECKPOINTER_DSN | sqlite path / postgres DSN for the checkpointer | ~/.cairn/checkpoints.sqlite / — |
OBS_PROFILE | active profile (name or path) | unset = no overrides |
OBS_BUS | event bus: inprocess or postgres://… (durable + replay) | inprocess |
OBS_BACKEND | LLM/telemetry backend mode: mock / openai / otel | mock |
OBS_SQLITE_DB | shared SQLite path when no Postgres | under ~/.cairn |
| Variable | Controls | Default |
|---|
OBS_TRIGGER_PORT | server port | 9090 |
OBS_ENVIRONMENT | default policy environment label | production |
OBS_JWT_SECRET | presence enables auth (HS256 signing key); unset = open server | unset |
OBS_REQUIRE_AUTH | refuse to start without a JWT secret | off |
OBS_API_USER / OBS_API_PASSWORD / OBS_API_PASSWORD_HASH | the env-admin login (hash preferred; generate with cairn remote hash-password) | admin / — / — |
OBS_ACCESS_TOKEN_EXPIRE_MINUTES | JWT TTL | 30 |
OBS_WORKSPACE | default workspace | default |
| Variable | Controls | Default |
|---|
OPENAI_API_KEY | the one key required for real inference | — |
ANTHROPIC_API_KEY / GEMINI_API_KEY | additional providers (Gemini is the default RAG embedder) | — |
OBS_MODEL_ROLES | model-roles file (fast/strong/router → provider+model) | ~/.cairn/model_roles.json |
LLM_GATEWAY | direct or proxy | direct |
LLM_GATEWAY_URL / LLM_GATEWAY_API_KEY | the proxy endpoint + key (e.g. the LiteLLM compose profile) | — |
OBS_GATEWAY + LITELLM_BASE_URL / LITELLM_MASTER_KEY | console Gateway view’s spend/metrics source (litellm / openrouter) | stub |
| Variable | Controls | Default |
|---|
OBS_TEMPORAL_ADDRESS / OBS_TEMPORAL_NAMESPACE | cluster + namespace | localhost:7233 / default |
OBS_TEMPORAL_TASK_QUEUE / OBS_TEMPORAL_REMOTE_TASK_QUEUE | worker queues (main / remote-GPU) | cairn / derived |
OBS_ACTION_HANDLER | action executor kind (durable handler needed for magic-link approvals) | in_process |
OBS_REMOTE_JOB_DURABLE / OBS_REMOTE_JOB_MAX_ATTEMPTS | durable remote-job control loop / retries | off / 2 |
| Variable | Controls | Default |
|---|
OTEL_EXPORTER_OTLP_ENDPOINT / OTEL_SERVICE_NAME | OTLP export (presence enables tracing) | — / cairn |
OBS_TRACE_CONTENT | prompt/completion export: off / redacted / raw | redacted |
OBS_AUDIT_LOG | hash-chained audit log path | ./audit.jsonl |
OBS_EVENTS_PATH | request-telemetry JSONL sink | ./events.jsonl |
LANGFUSE_BASE / GRAFANA_BASE | console deep-link bases | — |
| Variable | Controls | Default |
|---|
CAIRN_APPROVAL_TTL_HOURS / CAIRN_APPROVAL_SWEEP_MINUTES | stale-gate expiry TTL / sweep interval | 168 / 60 |
OBS_REALTIME_CONCURRENCY / OBS_BACKGROUND_CONCURRENCY | per-lane dispatch concurrency | 4 / 2 |
OBS_POLICIES_DIR | user policy overlay dir | ~/.cairn/policies |
OBS_TRIGGERS_DIR | user trigger overlay dir | ~/.cairn/triggers |
OBS_TRIGGER_DURABLE / OBS_TRIGGER_INBOX | durable trigger inbox (sqlite or nats://…) | off |
OBS_PLAYGROUND_ENV | environments the Playground treats as sandboxes | playground,sandbox |
OBS_OPS_MCP | mount the reads-first MCP surface at /mcp | off |
| Variable | Controls | Default |
|---|
OBS_SECRET_BACKEND (+ INFISICAL_HOST/TOKEN/ENV/PROJECT_ID) | secret store: local or Infisical | local |
OBS_SECRET_KEY | local secret encryption key | — |
MLFLOW_TRACKING_URI | MLflow registry for model/register (else local JSONL) | unset |
OBS_MODEL_REGISTRY | local registry path | ~/.cairn/model_registry.jsonl |
OBS_ARTIFACTS_DIR / OBS_ARTIFACT_S3_BUCKET | artifact store roots (local / S3) | operator defaults |
OBS_REGISTRY_CATALOG / OBS_REGISTRY_ALLOWLIST | pack registry catalog + install allowlist | — |
SLACK_WEBHOOK_URL / SLACK_BOT_TOKEN / SLACK_CHANNEL | Slack notifications + approval channels | — |
CADDY_DOMAIN (TLS domain), POSTGRES_PASSWORD, COMPOSE_PROFILES (which
optional services run), OBSAGENT_IMAGE (engine image override, default
cairn-engine:prod) — validated together by cairn deploy doctor, which
requires CADDY_DOMAIN, POSTGRES_PASSWORD, OBS_JWT_SECRET, and
OBS_API_PASSWORD_HASH to be present.
