Configuration

CAESAR is configured by environment variables. caesar/config.py is the single source of truth — every variable below maps to a field on a Pydantic model there. The structure follows ADR-0017:

• Prefix — every variable starts with CAESAR_.
• Nesting — __ (double underscore) descends one level (CAESAR_BUS__AUTH__ENABLED sets bus.auth.enabled).
• Layering — defaults → .env file → process env. Process env wins.
• Secrets — any field typed as SecretStr is redacted in repr(), logs, and audit rows.

Run caesar init to generate a starter .env with a freshly minted dashboard token and Praetor NKEY. See Quickstart for the full walkthrough.

Praetor server (server)

Variable	Default	Description
CAESAR_SERVER__HOST	127.0.0.1	Bind address. Loopback by default; set to 0.0.0.0 to expose on the LAN, but pair it with CAESAR_SERVER__API_TOKEN.
CAESAR_SERVER__PORT	8000	TCP port.
CAESAR_SERVER__API_TOKEN	—	When set, /v1/chat and /v1/devices/* require Authorization: Bearer <token> (SR-001). /v1/hook/* has its own per-trigger bearer auth (ADR-0032); /dashboard and /metrics are independent. Binding non-loopback without a token logs a startup warning.

Database (db)

Variable	Default	Description
CAESAR_DB__URL	sqlite+aiosqlite:///./var/caesar.sqlite3	SQLAlchemy URL. SQLite is the only tested backend (ADR-0019). The default lives under ./var/ so the working tree stays clean.
CAESAR_DB__ECHO	false	Echo every SQL statement to stdout. Useful for debugging; expensive otherwise.

LLM gateway (llm)

ADR-0011 sets the provider abstraction; ADR-0026 generalises it across Anthropic, OpenAI, and Ollama with optional per-task routing.

Variable	Default	Description
CAESAR_LLM__PROVIDER	anthropic	anthropic, openai, or ollama. Pair with CAESAR_LLM__MODEL.
CAESAR_LLM__MODEL	claude-haiku-4-5-20251001	Default model identifier passed to the chosen provider.
CAESAR_LLM__SYSTEM_PROMPT	"You are CAESAR, …"	Default system prompt; operators override per-session via the dashboard.
CAESAR_LLM__MAX_TOKENS	1024	Max-tokens cap on every completion.
CAESAR_LLM__ANTHROPIC__API_KEY	—	Required when provider=anthropic and no gateway is injected.
CAESAR_LLM__OPENAI__API_KEY	—	Required when provider=openai.
CAESAR_LLM__OPENAI__BASE_URL	—	Override for Azure-OpenAI / vLLM / LiteLLM-proxy / Together.
CAESAR_LLM__OLLAMA__BASE_URL	http://localhost:11434	Ollama HTTP API base.
CAESAR_LLM__TASK_ROUTING__<task>__*	empty	Optional per-task overrides. Keys: provider, model. Tasks the brain emits include chat, memory_extract, memory_summarise. Example: CAESAR_LLM__TASK_ROUTING__MEMORY_EXTRACT__PROVIDER=ollama.
CAESAR_LLM__API_KEY	—	Deprecated legacy top-level Anthropic key (pre-v1.1). Slated for removal in v2.x. Use CAESAR_LLM__ANTHROPIC__API_KEY.

See Picking a model for cost / latency / privacy trade-offs across providers.

Home Assistant bridge (ha)

Variable	Default	Description
CAESAR_HA__URL	—	Base URL of your HA instance. Bridge is not constructed when unset; device routes return 503.
CAESAR_HA__TOKEN	—	Long-lived HA access token. High-value secret.
CAESAR_HA__TIMEOUT_SECONDS	10.0	Per-request timeout.
CAESAR_HA__VERIFY_SSL	true	Disable for self-signed HA in a homelab; do not disable across the WAN.

Policy engine (policy)

Variable	Default	Description
CAESAR_POLICY__RULES_PATH	—	Path to the YAML allow-list (ADR-0013, ADR-0028). When unset CAESAR loads the deny-all stub and refuses every tool call.

Message bus (bus)

Disabled by default — Praetor runs single-process without NATS. Enable to bring up Legion workers and out-of-tree plugins.

Variable	Default	Description
CAESAR_BUS__ENABLED	false	Master switch for the bus + Legion.
CAESAR_BUS__URL	nats://127.0.0.1:4222	nats-server address.
CAESAR_BUS__CONNECT_TIMEOUT	5.0	Seconds.
CAESAR_BUS__REQUEST_TIMEOUT	5.0	Default dispatch timeout.
CAESAR_BUS__AUTH__ENABLED	false	Opt into NKEY-per-identity auth (ADR-0027).
CAESAR_BUS__AUTH__NKEY_SEED_PATH	—	Path to the seed file on disk. Pair with CAESAR_BUS__AUTH__ENABLED=true.
CAESAR_BUS__AUTH__NKEY_SEED	—	Inline seed (test-only; use the path in production).
CAESAR_BUS__AUTH__USER	—	Optional named user in nats-server.conf.

Legion workers (legion)

Variable	Default	Description
CAESAR_LEGION__INPROCESS_WORKERS	["memory_recall"]	In-process worker names Praetor starts at lifespan. Each still registers with the bus. Options shipped: memory_recall, semantic_recall, calculator, web_search, calendar_read, notify.
CAESAR_LEGION__RECALL_DEFAULT_LIMIT	10	Default limit for recall_memory calls.
CAESAR_LEGION__RECALL_MAX_LIMIT	100	Maximum limit the brain may request.

Memory (memory)

ADR-0020 covers retention; ADR-0033 covers personal facts; ADR-0034 covers per-chat episode summaries + decay.

Variable	Default	Description
CAESAR_MEMORY__RETENTION_DAYS	90	TTL for audit_log rows. The sweeper deletes anything older.
CAESAR_MEMORY__SWEEP_INTERVAL_SECONDS	3600	Sweep cadence.
CAESAR_MEMORY__AUDIT_MAX_STRING_CHARS	16384	SR-008 clamp on every string value in an audit payload. 0 disables.
CAESAR_MEMORY__FACTS_EXTRACT__ENABLED	false	Background memory.extract worker that polls chat.completed rows and writes durable facts.
CAESAR_MEMORY__FACTS_EXTRACT__INTERVAL_SECONDS	60	Extractor poll cadence.
CAESAR_MEMORY__FACTS_EXTRACT__BATCH_SIZE	8	Rows per extractor pass (1–128).
CAESAR_MEMORY__FACTS_INJECT__ENABLED	true	Inject the "What you've told me:" block into the system prompt at chat start.
CAESAR_MEMORY__FACTS_INJECT__MAX_FACTS	30	Cap on facts surfaced per turn (0–500).
CAESAR_MEMORY__FACTS_INJECT__MAX_CHARS	2048	Char cap on the inject block (0–32768).
CAESAR_MEMORY__FACTS_IMPORTANCE__HALFLIFE_DAYS	60	Freshness half-life for fact importance ranking.
CAESAR_MEMORY__FACTS_IMPORTANCE__EDIT_WEIGHT_SCALE	0.5	How much each operator edit boosts a fact's importance.
CAESAR_MEMORY__EPISODES_SUMMARISE__ENABLED	false	Background memory.summarise worker that writes per-chat episode summaries.
CAESAR_MEMORY__EPISODES_SUMMARISE__INTERVAL_SECONDS	60	Summariser poll cadence.
CAESAR_MEMORY__EPISODES_SUMMARISE__BATCH_SIZE	4	Rows per summariser pass (1–64).
CAESAR_MEMORY__EPISODES_RECALL__ENABLED	true	Auto-recall top-K episodes into the chat system prompt.
CAESAR_MEMORY__EPISODES_RECALL__TOP_K	3	Episodes injected per turn (1–20).
CAESAR_MEMORY__EPISODES_RECALL__SIMILARITY_THRESHOLD	0.45	Cosine cutoff (0.0–1.0).
CAESAR_MEMORY__EPISODES_RECALL__MAX_AGE_DAYS	90	Episodes older than this aren't surfaced (1–3650).
CAESAR_MEMORY__EPISODES_RECALL__HALFLIFE_DAYS	30	Freshness half-life for recall ranking.
CAESAR_MEMORY__EPISODES_RECALL__RECALL_WEIGHT_SCALE	0.25	How much past surfacing boosts the recall score.
CAESAR_MEMORY__EPISODES_RECALL__MAX_CHARS	2048	Char cap on the recall block.

Pair extraction/summarisation with CAESAR_LLM__TASK_ROUTING__MEMORY_EXTRACT__* and MEMORY_SUMMARISE__* to route those background calls to a cheap local model.

Semantic memory (semantic)

Disabled by default. When enabled, a background indexer embeds rows from audit_log and the semantic_recall worker can answer similarity searches.

Variable	Default	Description
CAESAR_SEMANTIC__ENABLED	false	Master switch.
CAESAR_SEMANTIC__VOYAGE_API_KEY	—	Voyage AI embedding key. Without it the indexer uses a deterministic stub useful for dev/tests but useless for real retrieval.
CAESAR_SEMANTIC__MODEL	voyage-3.5	Embedding model name.
CAESAR_SEMANTIC__EMBEDDING_DIM	1024	Must match the model's output dimension.
CAESAR_SEMANTIC__INDEXER_INTERVAL_SECONDS	60	Indexer poll cadence.
CAESAR_SEMANTIC__INDEXED_EVENT_TYPES	["chat.completed"]	JSON list of audit event types to embed.
CAESAR_SEMANTIC__TOP_K_DEFAULT	5	Default top_k for semantic_recall.
CAESAR_SEMANTIC__TOP_K_MAX	50	Max top_k the brain may request.

Dashboard (dashboard)

ADR-0021 covers the dashboard. It's opt-in: /dashboard/* returns 404 until CAESAR_DASHBOARD__TOKEN is set.

Variable	Default	Description
CAESAR_DASHBOARD__TOKEN	—	Required to enable the dashboard. High-value secret. Generated by caesar init.
CAESAR_DASHBOARD__SIGNING_KEY	derived from token	SR-006: separates session-cookie HMAC from the auth token so rotating one doesn't force the other. When unset, signing key is HMAC-SHA256(token).
CAESAR_DASHBOARD__HISTORY_LIMIT	100	Rows shown in the live audit timeline.
CAESAR_DASHBOARD__COOKIE_NAME	caesar_dashboard	Session-cookie name.
CAESAR_DASHBOARD__COOKIE_MAX_AGE_SECONDS	604800	Session TTL. Default 7 days (SR-007).

Metrics (metrics)

Variable	Default	Description
CAESAR_METRICS__TOKEN	—	When set, /metrics requires Authorization: Bearer <token>. When unset, the loopback bind is the only guard (SR-003).

Tool workers (tools)

The non-HA Legion tools ship in-tree (ADR-0028). Each gates on its own settings; the brain only advertises the tool when its worker is enabled.

Variable	Default	Description
CAESAR_TOOLS__WEB_SEARCH__SEARXNG_URL	http://localhost:8888	Operator-hosted SearXNG with JSON output enabled.
CAESAR_TOOLS__WEB_SEARCH__RESULT_LIMIT	5	Default results returned.
CAESAR_TOOLS__WEB_SEARCH__MAX_RESULT_LIMIT	25	Hard ceiling on the brain's request.
CAESAR_TOOLS__WEB_SEARCH__TIMEOUT_SECONDS	10.0	Per-query timeout.
CAESAR_TOOLS__CALENDAR__CALDAV_URL	http://localhost:5232/	Radicale / Nextcloud / iCloud CalDAV root.
CAESAR_TOOLS__CALENDAR__USERNAME	""	CalDAV username.
CAESAR_TOOLS__CALENDAR__PASSWORD	—	CalDAV password. Worker is not built when unset.
CAESAR_TOOLS__CALENDAR__CALENDAR_NAMES	[]	JSON list of calendar names to expose. Empty = all visible.
CAESAR_TOOLS__CALENDAR__DEFAULT_RANGE_DAYS	7	Default look-ahead.
CAESAR_TOOLS__CALENDAR__DEFAULT_EVENT_LIMIT	20	Default events returned.
CAESAR_TOOLS__CALENDAR__MAX_EVENT_LIMIT	200	Hard cap.
CAESAR_TOOLS__CALENDAR__MAX_RANGE_DAYS	365	Look-ahead cap.
CAESAR_TOOLS__NOTIFY__TOPIC	""	ntfy.sh topic. Worker is not built when unset.
CAESAR_TOOLS__NOTIFY__BASE_URL	https://ntfy.sh	Public ntfy.sh by default; point at a self-host if you have one.
CAESAR_TOOLS__NOTIFY__TOKEN	—	Bearer token for ntfy servers that require auth.
CAESAR_TOOLS__NOTIFY__DEFAULT_PRIORITY	3	1–5; the brain may override per call.
CAESAR_TOOLS__NOTIFY__TIMEOUT_SECONDS	10.0	Per-notification timeout.

Proactive triggers (proactive)

ADR-0030 (schedules) + ADR-0031 (HA events) + ADR-0032 (webhooks) share one triggers.yaml file. When the path is unset, CAESAR stays reactive-only.

Variable	Default	Description
CAESAR_PROACTIVE__TRIGGERS_PATH	—	Path to triggers.yaml. See Proactive CAESAR for the YAML grammar.
CAESAR_PROACTIVE__SCHEDULES_PATH	—	Deprecated alias for TRIGGERS_PATH (v1.5 name). Kept for one release per ADR-0031 §5; a startup warning logs when only this is set.

Plugins (plugins)

ADR-0035: out-of-tree Legion workers loaded via the caesar.plugins entry-point group. See Build a CAESAR plugin.

Variable	Default	Description
CAESAR_PLUGINS__ENABLED	true	Master switch for plugin discovery.
CAESAR_PLUGINS__ALLOWLIST	—	JSON list of distribution names allowed to load (e.g. ["caesar-plugin-mqtt"]). When unset, every installed caesar.plugins entry point loads.
CAESAR_PLUGINS__<WORKER_ID>__*	—	Each plugin's settings_model is populated from this prefix. The plugin's docs describe the fields.

Logging (log)

Variable	Default	Description
CAESAR_LOG__LEVEL	INFO	Standard Python log levels.
CAESAR_LOG__FORMAT	json	json (production) or console (human-readable for dev).

Operational guidance

• Keep .env out of git (caesar init writes it under your CWD; the default .gitignore covers it).
• Rotate CAESAR_HA__TOKEN after any incident or maintainer handover.
• Rotate CAESAR_DASHBOARD__TOKEN whenever you suspect a leak; pair with rotating CAESAR_DASHBOARD__SIGNING_KEY (SR-006) when you also want every existing session forced to relogin.
• For production deployments, prefer a real secret manager (docker secrets, sops, 1Password, Vault) over a flat .env file.
• Run caesar praetor migrate after every CAESAR version bump.

References

• ADR-0017 — the layered-config design.
• caesar/config.py — the authoritative schema. If something here disagrees with the source, the source wins.
• SECURITY-MODEL.md — what each secret defends.
• SECURITY-REVIEW.md — SR-NNN references above.