Configuration

Aleph reads ~/.aleph/config.toml by default; ALEPH_HOME overrides the configuration and data root. Values support ${VAR} and ${VAR:-default} interpolation.

Canonical schema

[general]
default_provider = "claude"
fallback_providers = ["openai"]

[providers.claude]
provider_type = "claude"
enabled = true
api_key = "${ANTHROPIC_API_KEY}"
models = ["<model ID>"]

[policies]
mode = "work"       # chat / work / code
exec_tier = "auto"  # ask / auto / full

[gateway]
host = "127.0.0.1"
port = 18790
allow_insecure_remote = false

[providers.<name>] tables define providers; general.default_provider and general.fallback_providers reference their names. Use the current model catalog and Panel configuration for model IDs.

[policies] contains global mode and exec_tier. [sandbox.command_policy] is an independent security hard floor that exec_tier cannot lower. Do not put session mode, execution tier, or the nonexistent agents.defaults.thinking field under [agents.defaults]; that table contains only defaults supported by agent definitions, such as model, workspace, and skills.

Gateway host, TLS, and trusted proxy

[gateway]
host = "0.0.0.0"
port = 18790
allow_insecure_remote = false

[gateway.tls]
enabled = true
# cert_path = "/path/to/cert.pem"
# key_path = "/path/to/key.pem"
# san = ["aleph.example.com"]

[gateway.trusted_proxy]
enabled = true
trusted_ips = ["127.0.0.1", "::1"]

The Gateway WebSocket path is /ws. When TLS is enabled without certificate and key paths, the core generates and persists a self-signed certificate; remote clients use wss://. X-Forwarded-For and X-Forwarded-Proto are trusted only when the immediate peer is in trusted_ips. Non-loopback remote binds reject plaintext by default.

Reload impact

Reload impact is classified by src/config/reload_impact.rs. Provider configuration, the model catalog and failover chain, channel enablement, and [execution] run caps can be hot-reloaded. Listener address, port, and TLS certificates are transport settings and generally require a restart. Do not assume a failed reload applied partially; use the running configuration and aleph-server doctor or aleph-server status as the operational check.

Related locations

• ~/.aleph/config.toml: main configuration
• ~/.aleph/defaults.toml: default overrides
• Gateway: config.schema, config.get, config.patch, and config.reload