Skip to main content

Environment and Config Files

AION is configured through environment variables (mostly named AION_*, stored in a .env file) and a few YAML files. This page explains where each kind of setting lives, groups the most important variables by purpose (critical, infrastructure, feature switches, observability, auth) and shows how they are set in a Docker deployment. It is for administrators and IT staff who install or tune AION; end users never need to touch these settings.

Philosophy of the configuration systemโ€‹

Why three configuration levels?โ€‹

The system uses three levels to balance security, versioning, and local flexibility:

  1. .env (Environment Secrets): Secrets, URLs, credentials. Not committable, specific to each installation.
  2. config_std/ (Standard Templates): Structured configurations, base profiles, and curated skills. It is the versioned source of truth (committable).
  3. config/ (Active Local Config): The operational directory read by the agent. It is ignored by Git and is automatically populated from config_std/ during setup.

Why this design:

  • Security: .env and config/ (which can contain sensitive data like user password hashes) are never uploaded to Git.
  • Easy Initialization: scripts/sync_config.py (integrated in setup-aion-env.sh) creates the local configuration starting from the standard templates. With --prepare-runtime, runtime_extras_setup also copies the fs_policy templates and can install Playwright for the MCP promo (see filesystem-policy-and-promo).
  • Conflict-free customization: You can modify files in config/ or add new local profiles/skills without dirtying the Git repository or having conflicts during a git pull.
  • ${VAR} Substitutions: YAML supports ${VAR} to insert .env variables into project YAML values.

Categorization of variablesโ€‹

The AION_* variables are divided into functional categories, not by priority or importance.

๐Ÿ”ด Critical Variables (System does not function without)โ€‹

These variables are essential for basic functioning:

VariableDefaultWhy it is critical
AION_API_URLhttp://...:8000/qwen3/v1LLM model URL - without LLM, no chat
AION_MODELAIONQ35-35-Q8BModel to use - different model = different behavior
AION_UNIFIED_DB1Enables the use of the unified DB aion.db (F1)
AION_API_PORT8001API port - clients must connect here

๐ŸŸก Performance and Infrastructure Variables (V2)โ€‹

These variables configure the shared state and storage:

VariableDefaultDescription
AION_REDIS_URLredis://localhost:6379/0Redis URL for rate limit, locks, and chart queue
AION_REDIS_FALLBACK_LOCAL1If 1, use in-process implementations if Redis is offline
AION_STORAGE_BACKENDlocallocal (filesystem) or s3 (AWS/MinIO/RustFS)
AION_STORAGE_LOCAL_ROOTdataRoot directory for local storage
AION_STORAGE_S3_BUCKETaion-sessionsS3 bucket to use if backend=s3
AION_SESSION_CACHE_MAX_GB5Local cache budget for files downloaded from S3 storage

๐ŸŸข Feature Gates and Hermes Variablesโ€‹

These variables enable/disable advanced features:

VariableDefaultWhen to enable
AION_APPROVAL_ENABLEDโ€”No effect today: src/security/approval_manager.py is not called by any tool, so no tool asks for approval. Plan-mode approval (draft_execution_plan) is a separate mechanism.
AION_APPROVAL_LEARNโ€”No effect today (see above).
AION_PLUGINS_ENABLED1Allows loading plugins from data/plugins/
AION_PII_REDACT1Enables redacting sensitive data from messages
AION_CONTEXT_COMPRESS_ENABLED1Auto-compact STM before agent.run (mandatory for long chats)
AION_MODEL_MAX_CONTEXT131072Align with LLM model limit
AION_CONTEXT_COMPRESS_RESERVE_OUTPUT1Reserve AION_CHAT_MAX_TOKENS to avoid 400 context length errors
AION_SKILL_DISTILL_ENABLED1Automatic generation of skills from usage patterns
AION_SKILL_DISTILL_TOOL_LOG_MAX_CHARS8000TOOLS section in the distill prompt (tool_start/end/error sequence)
AION_SKILL_VIEW_METRICS1skill_view counter in data/logs/skill_view_metrics.jsonl
AION_SKILL_VIEW_ENFORCE_PROFILE1skill_view / skill_list only for skills in profile.skills
AION_DEFAULT_PROFILEaion_stdProfile slug if the request does not specify a valid one
AION_PROFILE_VALIDATE_STRICT0API boot fails on invalid YAML profiles
AION_PROFILE_HOT_RELOAD0Reload profiles from mtime at each get_agent (dev)
AION_PROFILE_LEGACY_NAME_LOOKUP0Profile lookup by display name (legacy)
AION_MCP_POOL1Persistent stdio pool (via src/settings.py)
AION_MCP_SESSION_ENV_INJECT0Inject parent env for call_tool (legacy; prefer session-scoped pool)
AION_MCP_SESSION_SCOPED_SERVERS(CSV)Servers with pool for chat_session_id
AION_MCP_ENV_SCRUB1Environment of MCP stdio processes. Repository servers (mcp_servers/, -m src.*) inherit the backend env minus the signing secrets (AION_CHAT_AUTH_SECRET, AION_CHAT_UI_INTERNAL_SECRET, AION_ORCHESTRATION_INTERNAL_SECRET, AION_API_KEY_BOOTSTRAP, AION_SETUP_*). Third-party servers (npx, node, mcp-remote, external scripts) get only PATH/HOME/locale/proxy/CA variables plus the registry env:. 0 restores the full env for every server.
AION_MCP_ENV_ALLOWLIST(CSV)Extra variables passed to third-party MCP servers as well.
AION_MEMPALACE_NAV_ENABLED1Inject/search ERP navigation on wing_proj_{project}
AION_MEMPALACE_NAV_AUTO_LEARN0Auto-drawer post_tool (disabled: agent tools only)
AION_MEMPALACE_NAV_SKIP_WHEN_SQL_INJECT1Skip MemPalace pre_turn search if QueryMemory has already injected SQL
AION_SQL_QM_AUTO_LEARN0Auto-save SQL post_tool (disabled: agent sql_memory_save only)
AION_MEMPALACE_NAV_AUTO_KG0After multi-table SELECT, mempalace_kg_add joins_via
AION_MEMPALACE_PALACE_PATH(auto)Root palace; default data/mempalace/{tenant_id}/ โ†’ MEMPALACE_PALACE_PATH
AION_LTM_MIN_IMPORTANCE2LTM extraction: ignore drawer with importance below threshold
AION_LTM_EXTRACT1Enable extract_and_persist post-turn (equivalent to MemPalace hook)
AION_MNEMOS_EMBEDDING_RECALL1Hybrid FTS + embedding RRF for Mnemos recall (falls back to FTS if embedding service unavailable)
AION_MNEMOS_EMBED_ON_BULK1Embed notes during bulk ingest (set 0 for very large one-shot imports)
AION_MNEMOS_DREAM_ENABLED1Nightly dream cycle: compress, contradictions, confidence decay, embedding backfill
AION_MNEMOS_ENTITY_RECALL0Optional entity-alias RRF signal (enable when alias resolution is insufficient)
AION_AGENT_MIN_REASONING_CHARS_WITHOUT_TOOL6000SSE turn_status if many reasoning characters without tool (0=off)
AION_AGENT_MAX_REASONING_WITHOUT_TOOL0Optional: threshold on SSE reasoning chunk (0=ignore; prefer chars)
AION_REASONING_HARD_STOP0If 1, interrupts the turn when it exceeds both AION_REASONING_MAX_* (not recommended: empty response)
AION_UPLOAD_MAX_BYTES52428800Max size per uploaded file (session uploads/)
AION_OFFICE_AUTO_CONVERT_LEGACY_WORD1Auto-convert legacy .doc โ†’ .docx on upload via LibreOffice on the API host
AION_SOFFICE_PATH(auto)Path to soffice if not on PATH (macOS: LibreOffice.app bundle)
AION_OFFICE_CONVERT_TIMEOUT_SEC90Timeout for .doc conversion
AION_DOC_AUTO_INGEST1Background PDF text extraction on upload (PyMuPDF)
AION_GEOCODING_NOMINATIM_URLhttps://nominatim.openstreetmap.orgNominatim base URL for MCP geocoding
AION_GEOCODING_USER_AGENT(required for Nominatim)User-Agent string for geocoding requests
AION_GEOCODING_MIN_INTERVAL_SEC1.1Min interval between Nominatim calls (rate limit)
AION_PDF_EVIDENCE_DPI200Default DPI for MCP pdf_evidence_crop
AION_PDF_EVIDENCE_MAX_WHITE_RATIO0.90Reject evidence crops above this white pixel ratio

Session uploads, legacy Word conversion, and PDF auto-ingest are documented in Office files and legacy Word. PDF evidence crops for Word reports: PDF evidence images.

๐Ÿ”ต Observability and Telemetry Variables (V3)โ€‹

These variables configure tracking, metrics, and structured logging:

VariableDefaultDescription
AION_ENVdevEnvironment label (dev / staging / prod) propagated in trace/log
AION_OTEL_ENABLED0Enables OpenTelemetry tracing
AION_OPIK_ENABLED0Enables Opik (Comet ML) LLM telemetry tracing
AION_OTEL_ENDPOINThttp://localhost:4317gRPC/HTTP endpoint of the OTel collector
AION_OTEL_PROTOCOLgrpcProtocol to the collector (grpc or http/protobuf)
AION_OTEL_SERVICE_NAMEaion-agentService name reported in traces
AION_METRICS_ENABLED1Enables the Prometheus endpoint /metrics
AION_METRICS_PATH/metricsPath of the Prometheus endpoint
AION_LOG_FORMATjsonLog format (json or text) for integration with Loki/ELK
AION_PROFILING_ENABLED1Per-turn profiling (pipeline timing events)
AION_PROFILING_STORAGEjsonlProfiling storage backend (jsonl, sqlite, redis)
AION_PROFILING_JSONL_DIRdata/profilingJSONL records folder (Docker volume: /app/data/profiling)

๐ŸŸฃ Per-turn runtime guardrailsโ€‹

Hard limits on the single turn to avoid LLM runaway loops:

VariableDefaultDescription
AION_REASONING_MAX_CHARS0Max characters of streamed reasoning (0 = no cap; recommended for SQL)
AION_REASONING_MAX_EVENTS0Max reasoning events per turn (0 = no cap)
AION_REASONING_REPLAY1Replay the model's own reasoning from earlier steps of the current turn on assistant messages (interleaved thinking). 0 disables. Skipped for Anthropic/Google
AION_REASONING_REPLAY_FIELDSreasoning_content,reasoningAssistant-message fields carrying the replayed reasoning (vLLM reads reasoning, llama.cpp/SGLang read reasoning_content)
AION_TOOL_CALLS_MAX_PER_TURN24Hard cap on tool calls
AION_TOOL_EVENTS_MAX_PER_TURN60Hard cap on emitted tool events
AION_TOOL_DEDUPE_ENABLED1Deduplicates identical tool calls close in time (loop guard)
AION_TOOL_DEDUPE_TTL_SEC20Deduplication TTL window
AION_TTC_MAX_ATTEMPTS3Test-Time Compute: max retries per turn
AION_TTC_MAX_TOKENS10000Overall TTC token budget per turn
AION_ORCH_TOOL_TIMEOUT_SEC900Execution timeout of a single tool from orchestration

โš™๏ธ Auth & adminโ€‹

VariableDefaultDescription
AION_CHAT_AUTH_TOKEN_TTL_SEC604800chat-ui JWT token TTL (7 days)
AION_FS_POLICY_PATHFilesystem policy YAML path (empty = default in-code)
AION_PROMO_CAPTURE_ENABLED1Enables PNG export via MCP promo_render
AION_PROMO_CAPTURE_TIMEOUT_MS(optional)Playwright capture timeout (ms)
AION_ADMIN_UI_URLhttp://localhost:3870admin-ui public URL (for Chat UI banner)

Operational guide (templates config/fs_policy*.yaml, Playwright, setup/upgrade flags): Filesystem policy and promo PNG export.


Deploy via Docker Composeโ€‹

For containerized deployment (stack caddy + backend + chat-ui + admin-ui + website + redis) a .env file derived from .env.docker.example is used instead of .env.example.

Note: an .env.docker file in the root is not read by docker-compose.yml (only .env). If it exists, it is a local duplicate: align the variables in .env or delete it.

The following keys are read only by Compose/Caddy (not by Python code):

VariableExampleDescription
DOMAINcliente.example.comPublic hostname; :80 for dev HTTP
LETS_ENCRYPT_EMAILops@aion-asa.comACME Let's Encrypt contact
REDIS_PASSWORD(optional)If valued, Redis requires auth
NEXT_PUBLIC_AION_API_URL/apiBaked in chat-ui/admin-ui at build time
NEXT_PUBLIC_AION_ADMIN_UI_URL/adminLink chat-ui โ†’ admin-ui
DOCUSAURUS_BASE_URL/docs/Docusaurus baseUrl

Recommended AION_* overrides for the container context:

AION_REDIS_URL=redis://redis:6379/0 # service DNS Docker
AION_DATA_DIR=/app/data # mount aion_data
AION_FASTAPI_URL=http://backend:8001 # service-to-service
AION_PUBLIC_API_URL=https://${DOMAIN}/api
AION_CORS_ORIGINS=https://${DOMAIN}
# Do not use AION_CORS_ORIGINS=* in production without AION_CORS_ALLOW_WILDCARD=1
AION_LOG_LEVEL=INFO
AION_TURN_DIAGNOSTICS=0
AION_LLM_HEALTH_CACHE_SEC=45
VariableDefaultDescription
AION_CORS_ALLOW_WILDCARDoff1 allows AION_CORS_ORIGINS=* even with AION_ENV=prod
AION_LOG_LEVELINFORoot logger level (setup_logging)
AION_LLM_HEALTH_CACHE_SEC45Cache TTL for GET /models ping before each chat turn

Quick setup:

./scripts/setup-aion-env.sh --docker # copies .env.docker.example -> .env
vim .env # set DOMAIN, secrets, AION_API_URL
docker compose up -d --build

See Deploy with Docker Compose for the complete workflow (path-based routing, troubleshooting, scalability).


Multi-user MCP (HOME and credential store)โ€‹

For enterprise environments where multiple users share the same backend, configure:

VariableDefaultDescription
AION_MCP_USER_HOME_ISOLATION1mcp_home directory per user under AION_DATA_DIR/users/....
AION_MCP_USER_CREDENTIALS0Enables encrypted credential store and ${AION_USER_*} placeholders in the registry.
AION_CREDENTIAL_ENCRYPTION_KEY(empty)32-byte hex key for AES-GCM; mandatory in prod if credentials=1.
AION_DEFAULT_TENANT_IDdefaultTenant for credential rows.

Detailed guide: MCP isolation per user.


Trade-off: Redis vs Local Fallbackโ€‹

AION V2 introduces Redis for multi-worker scalability.

  • With Redis: Rate limiting and locks are shared across multiple worker instances. Ideal for production.
  • Local Fallback: Uses in-memory dictionaries. Simple for local development, but does not scale across multiple processes.

Unified DB vs Legacyโ€‹

AION_UNIFIED_DB=1 (default) enables the new unified schema that synchronizes Chat UI and API v1. If disabled, the system falls back to the old chat_memory.db and chat.db (strongly discouraged).


Debugging configuration issuesโ€‹

"Error 503 Unified DB disabled"โ€‹

Verify: Check that AION_UNIFIED_DB is 1 and that the file data/aion.db exists or can be created. If you updated from a previous version, run python scripts/migrate_to_aion_db.py.

"Files do not appear in S3"โ€‹

Verify: Check AION_STORAGE_BACKEND. If set to local, files remain in the filesystem. Verify the AION_STORAGE_S3_* credentials if you use the s3 backend.


P1: Plan mode, prompt budget and centralized settingsโ€‹

VariableDefaultDescription
AION_PLAN_MODE_TOOL_FIRST1Plan mode uses draft_execution_plan (tool) instead of <plan> tags.
AION_PLAN_TEXT_PARSER0Legacy text parser (only if tool-first off or rollback).
AION_PLAN_FINALIZER_TIMEOUT_SEC20Plan finalizer timeout (seconds).
AION_PROMPT_LAYER_TOTAL_BUDGET6000Estimated token budget for layers injected in the turn.
AION_AGENT_EXEC_LEGACY_THREAD01 = Agent.run in thread; 0 = run_async (default).
AION_SETTINGS_LEGACY_FALLBACK1Fallback os.getenv during migration to src/settings.py.

AION_API_URL and AION_MODEL are mandatory (no hardcoded default IP). The limits per turn (AION_TOOL_CALLS_MAX_PER_TURN, AION_STREAM_EVENTS_MAX_PER_TURN, AION_NO_PROGRESS_TIMEOUT_SEC) are loaded from TurnBudget / AionSettings.


Tool-first runtime (OpenCode-style)โ€‹

File delivery and agent-loop hardening are controlled by the following variables. scripts/upgrade_core.py injects missing keys via _TOOL_RUNTIME_ENV_DEFAULTS when you run ./scripts/upgrade-aion.sh (local or --docker). The deprecated AION_ARTIFACT_STRATEGY key is removed on upgrade.

VariableDefaultDescription
AION_MODEL_PROMPT_FRAGMENTS1Merge provider/model fragments from config_std/prompts/*.txt (src/runtime/system_prompt.py).
AION_ARTIFACT_STREAM_LEGACY01 = re-enable <aion_artifact> stream parsing and legacy write-tool blocking (artifact_tool_policy).
AION_STREAM_LOOP_V21Use StreamLoop v2 in src/runtime/stream/loop.py (tool settlement, file-preview bridge, doom loop).
AION_MODEL_TOOL_POLICY1Per-model tool exposure: GPT โ†’ sandbox_apply_patch; others โ†’ write + edit.
AION_DOOM_LOOP_THRESHOLD3Identical (tool, args) repeats before doom-loop action.
AION_DOOM_LOOP_ACTIONreminderreminder (inject nudge) or stop (end turn).
AION_JSON_RECOVERY_ALLOW_EMPTY00 = do not map "" โ†’ {} for tools with required fields.
AION_VLLM_TOOLS_STRICT0Force Haystack tools_strict on local vLLM (off by default โ€” truncated tool JSON is common).
AION_VLLM_TOOL_ARG_TOKEN_FLOOR8192Minimum max_tokens floor for vLLM when thinking + large tool-call payloads.
AION_LLM_CALL_AUDIT0Persist every LiteLLM/vLLM request+response under data/diagnostics/llm_calls/; analyze with python scripts/audit_llm_calls.py.
AION_PROMPTS_DIRconfig_std/promptsOverride directory for model prompt fragments.
AION_TOOL_DESCRIPTIONS_DIRconfig_std/tool_descriptionsExtended MCP tool descriptions for sandbox write/edit/patch.

Primary file path: sandbox_write_workspace_file, sandbox_edit_workspace_file, sandbox_apply_patch โ€” not chat-stream XML. Phantom tool names (aion_artifact, artifact, create_file) are rejected by src/runtime/tool_settlement.py before MCP runs.

See Agent pipeline โ€” Tool-first file delivery.

.env.example coverage checkโ€‹

python scripts/check_env_example_coverage.py # getenv + AionSettings + upgrade defaults
python scripts/check_env_example_coverage.py --strict # only active lines in .env.example

Exit code 1 if any AION_* used in src/ or upgrade_core.py defaults is missing from .env.example.