Documentation Index
Fetch the complete documentation index at: https://septemberai.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
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. |
| 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.
See also
