Configuration

This page documents all available environment variables for XTM One. The .env.sample file is the canonical source and includes inline comments for each variable.

SECRET_KEY

This is the most critical value. It encrypts all stored integration credentials. If you lose it or change it, all encrypted data becomes unrecoverable.

ADMIN_PASSWORD

The platform resets the admin password to the value in .env on every startup. This means .env is a standing password reset mechanism — anyone with read access to the file can take over the admin account by restarting the service. Treat .env as a privileged secret (owner-only permissions, never committed to version control). After first login, consider rotating the password via the UI and keeping the .env value in sync.

Security

Variable	Required	Default	Description
`SECRET_KEY`	Yes	—	JWT signing + Fernet encryption key. Generate with `python -c "import secrets; print(secrets.token_urlsafe(48))"`. Never change after deployment.
`ADMIN_EMAIL`	Yes	—	Default admin account email. Created or updated on every startup.
`ADMIN_PASSWORD`	Yes	—	Default admin account password. Reset to this value on every startup.
`ADMIN_TOKEN`	No	—	Programmatic API token for the admin (must start with `fcp-`, min 16 chars).

URLs

Variable	Required	Default	Description
`BASE_URL`	Yes	`http://localhost:4000`	Public URL of the platform. Used for OAuth/SAML callbacks and email links.
`FRONTEND_URL`	Yes	`http://localhost:4000`	Public URL of the frontend. Usually same as `BASE_URL`.

Platform mode

Variable	Required	Default	Description
`PLATFORM_MODE`	No	`xtm_one`	`xtm_one` (default, open) or `copilot` (requires Filigran license).
`PLATFORM_REGISTRATION_TOKEN`	No	—	Shared token for OpenCTI/OpenAEV registration. Must match across services.
`ENTERPRISE_LICENSE`	No	—	Enterprise license PEM. Can also be configured from Settings UI.
`PLATFORM_NAME`	No	Mode default	Display name override. DB value takes precedence.
`PLATFORM_LOGO`	No	Mode default	Logo override (data URI). DB value takes precedence.

Database

Variable	Required	Default	Description
`DATABASE_URL`	No	Built from `DB_PASSWORD`	Full asyncpg connection string. Override when using external PostgreSQL.
`DB_PASSWORD`	Yes (if bundled)	—	Password for the bundled PostgreSQL container.
`DB_POOL_SIZE`	No	`10`	Connections per worker process.
`DB_MAX_OVERFLOW`	No	`10`	Extra connections allowed beyond pool size.
`PG_MAX_CONNECTIONS`	No	`200`	PostgreSQL `max_connections` (Docker Compose managed only).

Redis

Variable	Required	Default	Description
`REDIS_URL`	No	`redis://redis:6379`	Redis connection string. Override for external Redis.
`REDIS_PASSWORD`	No	—	Redis password (if required).
`REDIS_MODE`	No	`standalone`	`standalone` or `sentinel`.
`REDIS_SENTINEL_HOSTS`	No	—	Comma-separated Sentinel addresses (host:port).
`REDIS_SENTINEL_SERVICE`	No	`mymaster`	Sentinel service name.

File storage (S3 / MinIO)

Variable	Required	Default	Description
`S3_ACCESS_KEY`	Yes	—	S3/MinIO access key.
`S3_SECRET_KEY`	Yes	—	S3/MinIO secret key.
`S3_ENDPOINT`	No	`minio:9000`	S3-compatible endpoint.
`S3_BUCKET`	No	`copilot-files`	Bucket name.
`S3_USE_SSL`	No	`false`	Enable TLS for S3 connections.
`S3_REGION`	No	—	AWS region (required for AWS S3).

AI providers

Pre-provision LLM providers via environment variables so the platform is ready without UI configuration.

Variable	Required	Default	Description
`LLM_PROVIDER_{NAME}_API_KEY`	No	—	API key for the named provider.
`LLM_PROVIDER_{NAME}_MODELS`	No	All available	Comma-separated list of models to expose.
`DEFAULT_MODEL`	No	First configured	Platform-wide default model.

Supported provider names: OPENAI, ANTHROPIC, GEMINI, OPENROUTER, OLLAMA, MISTRAL, AZURE_OPENAI, BEDROCK, LITELLM, CUSTOM_OPENAI.

Performance

Variable	Required	Default	Description
`WEB_WORKERS`	No	`2`	Uvicorn worker processes. Production: `2 × CPU cores + 1`.
`WORKER_CONCURRENCY`	No	`20`	Concurrent async jobs per worker container.
`MAX_CONCURRENT_RUNS`	No	`10`	Max parallel assignment executions.
`MAX_CONCURRENT_SUB_AGENT_TASKS`	No	`5`	Max parallel sub-agent tasks.

PostgreSQL connection budget

(DB_POOL_SIZE + DB_MAX_OVERFLOW) × (WEB_WORKERS + SAQ workers) + 20 < PG_MAX_CONNECTIONS

Example with 4 web workers and 1 SAQ worker: (10 + 10) × (4 + 1) + 20 = 120 → fits the default PG_MAX_CONNECTIONS=200.

Logging

Variable	Required	Default	Description
`LOG_LEVEL`	No	`info`	`debug`, `info`, `warning`, `error`, `critical`.
`LOG_FORMAT`	No	`json`	`json` (structured) or `console` (human-readable). When unset, defaults to `json` in production or `console` when `DEBUG=true`.

Email (SMTP)

Variable	Required	Default	Description
`SMTP_HOSTNAME`	No	—	SMTP server hostname.
`SMTP_PORT`	No	`587`	SMTP port.
`SMTP_USERNAME`	No	—	SMTP authentication username.
`SMTP_PASSWORD`	No	—	SMTP authentication password.
`SMTP_FROM`	No	—	Sender address for outgoing emails.
`SMTP_STARTTLS`	No	`true`	Use STARTTLS.

Observability

Variable	Required	Default	Description
`LANGFUSE_HOST`	No	`https://cloud.langfuse.com`	Langfuse server URL.
`LANGFUSE_PUBLIC_KEY`	No	—	Langfuse public key.
`LANGFUSE_SECRET_KEY`	No	—	Langfuse secret key.
`PROMETHEUS_ENABLED`	No	`false`	Enable Prometheus metrics endpoint.
`PROMETHEUS_BEARER_TOKEN`	No	—	Bearer token for metrics endpoint (min 16 chars).

Security feature flags

Variable	Required	Default	Description
`DISABLE_CODE_INTERPRETER`	No	`true` (xtm_one mode)	Disable code interpreter at infra level.
`DISABLE_CUSTOM_TOOLS`	No	`true` (xtm_one mode)	Disable custom tools at infra level.
`CUSTOM_TOOL_SANDBOX`	No	`auto`	Custom tool execution mode: `auto`, `docker`, `subprocess`.

Feature flags

Variable	Required	Default	Description
`ENABLED_FEATURES`	No	— (none enabled)	Comma-separated list of feature flag ids to turn on experimental/in-development features, e.g. `MY_FLAG,OTHER_FLAG`. Use `*` to enable all of them. Leaving this unset enables none of them. Changing it requires a restart — there is no toggle in the Settings UI. An unrecognized flag id (e.g. left over from another branch) is logged as a warning and ignored — it never enables anything and never prevents the platform from starting.

The resolved list of enabled flags is also sent to the frontend (as part of the public, boot-time GET /auth/config response), so a flag can control both backend behavior and whether a UI element is shown — with the backend independently enforcing the same flag on any route it gates.