Environment variables

This page is the authoritative reference for every environment variable the Engine reads. Variables are loaded from a .env file or the OS environment (OS takes precedence). All feature-flag values are the lowercase strings "true" or "false" — not "1" / "0", not booleans, not numbers. If a variable is marked required and is missing at startup, the Engine fails to boot.

LLM provider and models

Name	Required	Default	Purpose
`LLM_PROVIDER`	yes	`openai`	Which LLM to use: `anthropic`, `openai`, or `gemini`.
`LLM_API_KEY`	yes	—	API key for the selected provider.
`LLM_MODEL`	yes	`gpt-4o`	Model identifier (e.g. `claude-sonnet-4-20250514`).
`MAX_TOKENS`	no	`4096`	Max output tokens per call.
`GEMINI_API_KEY`	no	—	Google Gemini API key (required if provider is `gemini`).
`PLANNER_MODEL`	no	—	Model override for the planner sub-agent. Use a cheaper/faster model if set.
`LIGHT_MODEL`	no	—	Model override for lightweight tasks (compaction, summarization).
`FALLBACK_MODEL`	no	—	Model used if the primary model fails.

Embeddings

Embeddings always route to OpenAI in the current implementation, regardless of the chat-completion provider. You need an OpenAI key even if you’re using Anthropic or Gemini for chat.

Name	Required	Default	Purpose
`OPENAI_API_KEY`	yes	—	OpenAI key, used for embeddings.
`EMBEDDING_PROVIDER`	no	`openai`	Provider for embeddings. Only `openai` is supported today.
`EMBEDDING_MODEL`	no	`text-embedding-3-small`	Embedding model identifier.
`EMBEDDING_DIM`	no	`1536`	Embedding dimension. Must match the model’s output.

Web search (optional)

Name	Required	Default	Purpose
`BRAVE_API_KEY`	no	—	Brave Search API key.
`TAVILY_API_KEY`	no	—	Tavily fallback key.

Storage and catalogs

Name	Required	Default	Purpose
`SQLITE_DB_PATH`	no	`/data/brain.sqlite`	Path to the per-user brain database.
`CATALOG_DIR`	no	—	Path to the platform catalog (agents, skills, tools, core_soul.json).
`MIGRATIONS_DIR`	no	—	Path to migration files. Auto-discovered when empty.

Asset Directory (MCP)

Name	Required	Default	Purpose
`AD_ENCRYPTION_KEY`	no	—	Fernet key (base64-encoded 32 bytes) for encrypting MCP credentials at rest. Required if you use any MCP connector.
`OAUTH_REDIRECT_BASE_URL`	no	—	Base URL for OAuth redirects (e.g. `https://engine.example.com`).

Learning Centre

Name	Required	Default	Purpose
`LC_BATCH_INTERVAL_HOURS`	no	`6.0`	Hours between automated batch runs.
`LC_PROVIDER`	no	`openai`	Embedding provider for batch encoding.
`LC_MODEL`	no	`gpt-5.4-mini`	Model for batch consolidation.

Channel state and activity

These control how long execution checkpoints survive and how user activity state transitions.

Name	Required	Default	Purpose
`CHANNEL_STATE_TTL_ACTIVE`	no	`10800` (3 h)	Seconds. Lifetime of checkpoints for active sessions.
`CHANNEL_STATE_TTL_HITL`	no	`259200` (72 h)	Seconds. Lifetime of checkpoints for HITL-blocked sessions.
`ACTIVITY_IDLE_TIMEOUT_S`	no	`300` (5 m)	Seconds before active → idle.
`ACTIVITY_AWAY_TIMEOUT_S`	no	`1800` (30 m)	Seconds before idle → away.
`ACTIVITY_DISCONNECT_TIMEOUT_S`	no	`3600` (1 h)	Seconds before away → disconnected.

Permissions and sandboxing

Name	Required	Default	Purpose
`ASSET_DIRECTORY_SANDBOXED`	no	`"true"`	When `"true"`, Asset Directory tools run inside `bwrap`.
`ALLOWED_ROOTS`	no	—	Comma-separated absolute paths. Restricts file operations to these paths.
`SUBPROCESS_SCRUB_MODE`	no	`default`	Env scrub level for subprocesses: `off`, `default`, or `strict`.

Server configuration

Name	Required	Default	Purpose
`ENGINE_API_KEY`	no	—	Static API key. Use for development. Production should rotate.
`ENGINE_KEY_HASH`	no	—	SHA-256 hash of `ENGINE_API_KEY`. Validated at startup.
`ENGINE_LOG_LEVEL`	no	`INFO`	Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`.
`CORS_ORIGINS`	no	—	Comma-separated origins (e.g. `http://localhost:3000,https://app.example.com`).
`BAP_KEY_ROTATION_MIN_OVERLAP_SECONDS`	no	`0`	Minimum overlap window (seconds) when rotating API keys.
`BAP_KEY_ROTATION_MAX_OVERLAP_SECONDS`	no	`300`	Maximum overlap window (seconds) when rotating API keys.
`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`	no	`10`	Max concurrent tool calls in the streaming executor.
`INDUSTRY`	no	—	Industry scoping for catalog loading. Empty loads everything.
`PERSISTENCE_RETRY`	no	`"false"`	Retry persistent operations on transient failures.

Feature flags

All values are the strings "true" or "false" (case-insensitive).

Agent loop

Name	Default	Purpose
`TOKEN_BUDGET_ENABLED`	`"false"`	Token budget continuation loop in execution.
`STOP_HOOKS_ENABLED`	`"true"`	Run stop-hooks at turn boundaries.
`PRE_TOOL_HOOKS_ENABLED`	`"true"`	Run hooks before tool calls.
`POST_TOOL_HOOKS_ENABLED`	`"true"`	Run hooks after tool returns.
`HOOKS_SETTINGS_LOAD_ENABLED`	`"true"`	Load hooks from settings files.
`REACTIVE_COMPACT_ENABLED`	`"true"`	Recover from context overflow by compacting.
`CACHE_HIT_MONITOR_ENABLED`	`"true"`	Monitor prompt cache hit ratio.

Media handling

Name	Default	Purpose
`MEDIA_ERROR_RECOVERY_ENABLED`	`"false"`	Strip problematic media blocks and retry on errors.
`MEDIA_PRESEND_VALIDATION_ENABLED`	`"false"`	Validate media (size, content) before send.
`MEDIA_IMAGE_RESIZE_ENABLED`	`"false"`	Resize oversized images before send.
`CONTENT_INGESTION_ENABLED`	`"false"`	Chunk and store large media in `ingestion_chunks`.

Memory and compaction

Name	Default	Purpose
`USE_INMEMORY_WM`	—	Use in-memory working memory backend instead of SQLite. Test/CI only.
`FEATURE_CACHED_SNIP_PREPASS`	—	Pre-pass snip computation for caching.
`FEATURE_POST_COMPACT_HARDENED`	`"true"`	Hardened post-processing after compaction.
`FEATURE_STRUCTURED_FILE_EXTRACTION`	`"true"`	Extract structured file references during compaction.

Sandbox

Name	Default	Purpose
`FEATURE_WINDOWS_PATH_EVASION`	`"true"`	Detect Windows-style path-evasion attempts.
`FEATURE_DONT_ASK`	—	Disable permission prompts. Set only in trusted automation.
`FEATURE_SED_VALIDATION`	`"1"`	Validate `sed` commands before running.
`FEATURE_DANGEROUS_REMOVAL`	`"true"`	Detect and gate `rm` / `shred` of high-value paths.
`FEATURE_TREE_KILL`	`"true"`	Kill the entire process tree on task termination.
`FEATURE_BG_WATCHDOG`	`"true"`	Watchdog for orphaned background processes.

Other

Name	Default	Purpose
`ENABLE_SIGINT_INTERRUPT`	`"false"`	Install SIGINT handler. Disable in server mode.
`QUERY_CHAIN_TRACKING_ENABLED`	`"false"`	Trace query chains for observability.

Conventions

Booleans are strings. Always "true" or "false". Never 1 / 0, never bare true / false, never yes / no. The Engine’s loader is strict about this on purpose — typos become loud errors instead of silent defaults.
Paths are absolute. Anything that takes a path expects an absolute path inside the container.
Secrets never go in code. They go in .env, in your secret manager, or in environment variables passed at runtime.

Local development

Deploy

Configuration

Infrastructure

On-call

Incidents

SLOs

Security

Environment variables

LLM provider and models

Embeddings

Web search (optional)

Storage and catalogs

Asset Directory (MCP)

Learning Centre

Channel state and activity

Permissions and sandboxing

Server configuration

Feature flags

Agent loop

Media handling

Memory and compaction

Sandbox

Other

Conventions

See also

​LLM provider and models

​Embeddings

​Web search (optional)

​Storage and catalogs

​Asset Directory (MCP)

​Learning Centre

​Channel state and activity

​Permissions and sandboxing

​Server configuration

​Feature flags

​Agent loop

​Media handling

​Memory and compaction

​Sandbox

​Other

​Conventions

​See also

LLM provider and models

Embeddings

Web search (optional)

Storage and catalogs

Asset Directory (MCP)

Learning Centre

Channel state and activity

Permissions and sandboxing

Server configuration

Feature flags

Agent loop

Media handling

Memory and compaction

Sandbox

Other

Conventions

See also