Settings

Generated from agentdeck/runtime/settings.py’s LayeredSettings subclasses — this page cannot drift from the code because make check regenerates it and fails if the result differs (scripts/generate_docs_reference.py). Every variable is also settable in the shared config.yaml, under the section derived from its env-var prefix (openai:, runner:, …); an env var wins over the file.

`OpenAISettings`

OpenAI-compatible endpoint configuration.

Env var	Type	Default	Description
`OPENAI_MODEL`	`str`	required	Model name passed to the host Agents SDK runner. No default — always required.
`OPENAI_API_KEY`	`str`	`''`	API key for the endpoint. What empty does depends on `ca_bundle`: unset (the common case), the OpenAI client falls through to its own `OPENAI_API_KEY` process-env lookup and errors on the first model call if that’s empty too; with `ca_bundle` set, the empty value is passed straight through instead and just sends no Authorization header — the self-hosted/corporate-CA case doesn’t need a placeholder value the way the common path does.
`OPENAI_BASE_URL`	`str`	`''`	OpenAI-compatible endpoint base URL. Empty uses the SDK default, api.openai.com.
`OPENAI_CA_BUNDLE`	`str`	`''`	Path to a CA/certificate bundle for verifying the endpoint’s TLS certificate. Empty uses the system’s default trust store.

`RunnerSettings`

Defaults for the host-side Agents SDK runner.

Env var	Type	Default	Description
`AGENTDECK_RUNNER_WORKFLOW_NAME`	`str`	`'local-sandbox-repl'`	Name recorded on the host Agents SDK run (`RunConfig.workflow_name`) — identifies which workflow produced a run in tracing/observability.
`AGENTDECK_RUNNER_TEMPERATURE`	`float`	`1.0`	Sampling temperature for the host agent loop’s model.
`AGENTDECK_RUNNER_MAX_TURNS`	`int`	`30`	Maximum turns `Runner.run`/`run_streamed` may take before giving up.
`AGENTDECK_RUNNER_MAX_TOKENS`	`int` or `None`	`None`	Cap on tokens per response for the host agent loop’s `ModelSettings`. `None` means the model’s own default (uncapped).

`RuntimeSettings`

Knobs the Runtime itself reads.

Env var	Type	Default	Description
`AGENTDECK_RUNTIME_STALE_RUN_AFTER_SECONDS`	`float`	`3600.0`	How long, in seconds, an open run may go without writing an event before it is treated as abandoned and its session ownership is released for another worker to claim. Must be positive; set it above the longest gap a healthy turn can go quiet.

`LangfuseSettings`

Langfuse LLM-observability export config.

Env var	Type	Default	Description
`AGENTDECK_LANGFUSE_PUBLIC_KEY`	`str`	`''`	Langfuse public key. Tracing stays off unless this and `secret_key` are both set.
`AGENTDECK_LANGFUSE_SECRET_KEY`	`str`	`''`	Langfuse secret key. Tracing stays off unless this and `public_key` are both set.
`AGENTDECK_LANGFUSE_BASE_URL`	`str`	`'http://localhost:3000'`	Langfuse endpoint.
`AGENTDECK_LANGFUSE_ENVIRONMENT`	`str`	`'local'`	Langfuse `environment` tag attached to every exported span.
`AGENTDECK_LANGFUSE_DEBUG`	`bool`	`False`	Enable the Langfuse SDK’s own debug logging.
`AGENTDECK_LANGFUSE_SAMPLE_RATE`	`float`	`1.0`	Fraction of traces exported to Langfuse, from 0.0 to 1.0.
`AGENTDECK_LANGFUSE_SERVICE_NAME`	`str`	`'agentdeck'`	OpenTelemetry resource `service.name` for every exported span. Without it, spans fall back to `unknown_service` and are unattributed in the Langfuse UI.

`TavilySettings`

Tavily web-search API. One knob: TAVILY_API_KEY env var (or YAML tavily: api_key:).

Env var	Type	Default	Description
`TAVILY_API_KEY`	`str`	`''`	Tavily web-search API key. Empty makes the `web_search` tool return an `error:` string instead of raising — it degrades the same way an unavailable MCP server does, rather than disappearing.

`CheckpointSettings`

LangGraph checkpointer backend for durable=True workflows, as one scheme-shaped URL.

Env var	Type	Default	Description
`AGENTDECK_CHECKPOINT`	`str`	`'sqlite://.agentdeck/checkpoints.sqlite3'`	LangGraph checkpointer for `durable=True` workflows: `sqlite://<path>` for dev (this default), `postgresql://<dsn>` for prod, or `memory://` for tests (never persists past the process). The scheme names the backend.

`EventsSettings`

Where the Runtime’s canonical event log is written, as one scheme-shaped URL.

Env var	Type	Default	Description
`AGENTDECK_EVENTS`	`str`	`'memory://'`	Where the Runtime’s canonical event log is written: `memory://` (default, in-process, gone when the process exits), `sqlite://<path>`, `redis://<url>`/`rediss://<url>`, or `postgresql://<dsn>` (needs the `[durability]` extra). The scheme names the backend.

`ControlSettings`

Where a run’s pending control signals live — what pause and cancel are written to.

Env var	Type	Default	Description
`AGENTDECK_CONTROL`	`str`	`'memory://'`	Where a run’s pending control signals live: `memory://` (default, reachable only from this process) or `sqlite://<path>` (crosses process boundaries — required for the `agentdeck runs signal` CLI to reach a run). The scheme names the backend.

`SessionSettings`

Configuration for Redis-backed agent conversation memory.

Env var	Type	Default	Description
`AGENTDECK_SESSION`	`str` or `None`	`None`	Redis URL for `RedisSession`-backed agent conversation memory (`agentdeck.adapters.engines.openai_agents.sessions.SessionFactory`). `None` falls back to one in-process `SQLiteSession` per session key — no persistence across a restart, no sharing across workers.
`AGENTDECK_SESSION_REDIS_KEY_PREFIX`	`str`	`'agents:session'`	Key prefix under which `RedisSession` stores conversations in Redis.
`AGENTDECK_SESSION_REDIS_TTL`	`int` or `None`	`None`	Per-session TTL in seconds for Redis-backed conversations. `None` means sessions persist indefinitely.