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.
The Engine has roughly 25 feature flags. Each toggles a specific code
path on or off. This page groups them by what they affect, gives the
recommended defaults per environment, and notes rollout history.
For the bare reference table, see
Environment variables → Feature flags.
A reminder about values
Feature flag values are the strings "true" or "false",
case-insensitive. Never 1 / 0. Never bare true / false (those
parse as Python booleans, which the loader rejects). The Engine’s
loader is strict on purpose — typos become loud errors instead of
silent defaults.
Agent loop
These shape how the agent loop behaves on each turn.
| Flag | Default | Recommended dev | Recommended prod |
|---|
TOKEN_BUDGET_ENABLED | "false" | "false" | "false" |
STOP_HOOKS_ENABLED | "true" | "true" | "true" |
PRE_TOOL_HOOKS_ENABLED | "true" | "true" | "true" |
POST_TOOL_HOOKS_ENABLED | "true" | "true" | "true" |
HOOKS_SETTINGS_LOAD_ENABLED | "true" | "true" | "true" |
REACTIVE_COMPACT_ENABLED | "true" | "true" | "true" |
CACHE_HIT_MONITOR_ENABLED | "true" | "false" | "true" |
TOKEN_BUDGET_ENABLED. Off by default. Enables a continuation loop
that lets the agent automatically continue past MAX_TOKENS. Useful
for long-form output, but removes the natural cost ceiling. Leave off
for predictable budget; turn on when you have budget guardrails
elsewhere.
*_HOOKS_ENABLED. All on by default. Hooks let you intercept the
agent loop at specific boundaries. Disabling them turns off
customization mechanisms; rarely a good idea.
REACTIVE_COMPACT_ENABLED. On. Recovers from context overflow by
collapsing earlier turns. Off means an overflow returns
CONTEXT_OVERFLOW and the user has to restart. Always leave on.
CACHE_HIT_MONITOR_ENABLED. On in production for visibility into
cache effectiveness. Off in development to reduce log noise.
Memory and compaction
| Flag | Default | Recommended dev | Recommended prod |
|---|
USE_INMEMORY_WM | unset | unset | unset |
FEATURE_CACHED_SNIP_PREPASS | unset | unset | optionally "true" |
FEATURE_POST_COMPACT_HARDENED | "true" | "true" | "true" |
FEATURE_STRUCTURED_FILE_EXTRACTION | "true" | "true" | "true" |
USE_INMEMORY_WM. Tests and CI only. Routes working memory through
an in-memory backend rather than SQLite. Faster but loses durability.
Never enable in production.
FEATURE_CACHED_SNIP_PREPASS. When enabled, runs an extra pass to
optimize the cacheable prefix. Adds latency per turn; saves cost on
high-volume cached workloads. Pilot in staging before rolling to prod.
FEATURE_POST_COMPACT_HARDENED. On by default. Stricter
post-processing after compaction. Always leave on; the unhardened path
exists for debugging only.
FEATURE_STRUCTURED_FILE_EXTRACTION. On by default. Preserves file
contents through compaction so the agent doesn’t lose track of files
it’s already read. Always leave on.
Sandbox
| Flag | Default | Recommended dev | Recommended prod |
|---|
FEATURE_WINDOWS_PATH_EVASION | "true" | "true" | "true" |
FEATURE_DONT_ASK | unset | unset | conditional |
FEATURE_SED_VALIDATION | "1" | "1" | "1" |
FEATURE_DANGEROUS_REMOVAL | "true" | "true" | "true" |
FEATURE_TREE_KILL | "true" | "true" | "true" |
FEATURE_BG_WATCHDOG | "true" | "true" | "true" |
FEATURE_DONT_ASK. Disables permission prompts. Use only in
unattended automation where waiting on a human is worse than failing.
Don’t set in user-facing deployments — the whole point of the
permission system is to keep the user in the loop.
FEATURE_SED_VALIDATION. Note: this one is "1" / "0", not
"true" / "false". Legacy. The validator catches the worst sed
patterns; on by default.
FEATURE_DANGEROUS_REMOVAL. Detects and gates dangerous
rm/shred patterns. Disabling this is rarely a good idea.
FEATURE_TREE_KILL and FEATURE_BG_WATCHDOG. Process
hygiene. Both on by default.
| Flag | Default | Recommended dev | Recommended prod (user uploads) |
|---|
MEDIA_PRESEND_VALIDATION_ENABLED | "false" | "false" | "true" |
MEDIA_IMAGE_RESIZE_ENABLED | "false" | "false" | "true" |
MEDIA_ERROR_RECOVERY_ENABLED | "false" | "false" | "true" |
CONTENT_INGESTION_ENABLED | "false" | "false" | conditional |
CONTENT_INGESTION_ENABLED. On for deployments that handle large
documents (long PDFs, transcripts). Adds chunking + embedding cost up
front; saves context cost during retrieval. Off by default because the
infrastructure cost isn’t worth it for everyone.
Observability
| Flag | Default | Recommended dev | Recommended prod |
|---|
QUERY_CHAIN_TRACKING_ENABLED | "false" | conditional | "true" |
QUERY_CHAIN_TRACKING_ENABLED. Tracks query chains in
observability_events. Useful for production observability; adds
overhead per call. Pilot in staging.
Other
| Flag | Default | Recommended dev | Recommended prod |
|---|
ENABLE_SIGINT_INTERRUPT | "false" | depends | "false" |
ENABLE_SIGINT_INTERRUPT. Installs a SIGINT handler. Used for
TUI/CLI workflows where the user wants to interrupt with Ctrl-C. In
server mode, leave off — SIGINT is for the supervisor.
Rolling out a new flag
When the Engine adds a new flag in a release:
- The flag is introduced off by default. Existing deployments
keep their behavior.
- The release notes describe what the flag does and when to enable
it.
- After enough deployments have validated the new behavior, a future
release flips the default to on.
- Eventually, after several stable releases, the flag is removed
entirely (the new behavior becomes the only behavior).
The flag’s lifecycle is documented in the changelog.
Auditing flags in production
Periodically audit the flag values in your production environment.
Flags that were enabled experimentally tend to stay on past their
useful life, accumulating mystery.
# print the flags this Engine actually has set
docker compose exec engine env | grep -E '^(FEATURE_|MEDIA_|TOKEN_|REACTIVE_|CACHE_|USE_|PRE_|POST_|STOP_|HOOKS_|QUERY_|ENABLE_)'
See also
