Configuration

Aleph reads ~/.aleph/config.toml by default. Set ALEPH_HOME to override the entire configuration and data root. Values support ${VAR} and ${VAR:-default} interpolation; only environment variables explicitly read by the implementation have additional override semantics.

File Locations

Minimal Structure

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

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

[policies]
mode = "work"
exec_tier = "auto"

[gateway]
host = "127.0.0.1"
port = 18790

Providers and Models

Providers use [providers.<name>] tables. general.default_provider and general.fallback_providers refer to those names.

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

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

[providers.openai]
provider_type = "openai"
enabled = true
api_key = "${OPENAI_API_KEY}"
models = ["<OpenAI model ID>"]

Model IDs and capabilities change over time. Use the current model catalog and the provider configuration shown in Panel.

Policies

Global session mode and execution tier live under [policies], not [agents.defaults]:

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

[sandbox.command_policy] is an independent hard security floor that full cannot lower. Thinking level defaults to minimal and is controlled by session/client state; do not add a nonexistent agents.defaults.thinking field.

Gateway

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

The WebSocket endpoint is /ws; the default full URL is ws://127.0.0.1:18790/ws.

Native TLS

[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"]

When enabled = true and cert_path/key_path are empty, the core generates and persists a self-signed certificate. Remote clients use wss://; Panel presents a TOFU approval on first connection.

Trusted Reverse Proxy

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

X-Forwarded-For and X-Forwarded-Proto are trusted only when the immediate peer is in trusted_ips.

Agent Defaults

[agents.defaults] contains only defaults supported by agent definitions, such as model, workspace, and skills:

[agents.defaults]
model = "<model ID>"
workspace_root = "~/workspaces"
skills = ["search"]

Session mode and execution tier belong to [policies], not this table.

Channels and Extensions

Telegram, Discord, iMessage, MCP, plugin, and Hooks schemas evolve independently. Use their current reference pages instead of legacy [[hook]], [provider.*], or unverified configuration fragments:

• Interfaces
• Tools
• Automation Hooks
• Extensions

Hot Reload

Reload behavior is classified by src/config/reload_impact.rs. Transport settings such as listener address, port, and TLS generally require a restart. After changes, run:

aleph-server doctor
aleph-server status

Backup

Backing up the entire ALEPH_HOME is safest. At minimum, preserve:

• config.toml and defaults.toml
• data/, memory/, and artifacts/
• user-installed skills/ and plugins/

Caches and logs are usually reproducible, but use the directories actually created by the running version as the source of truth.

Next Steps

• Deployment — run as a persistent service
• Gateway Protocol — RPC and transport
• Security — security model