First-Time Configuration

The current aleph-server CLI does not expose a wizard subcommand. src/wizard/ is a session-based framework for Gateway clients; it does not imply an aleph wizard command.

1. Create the Configuration File

Aleph reads ~/.aleph/config.toml by default. Set ALEPH_HOME to override the root directory.

mkdir -p ~/.aleph

Minimal example:

[general]
default_provider = "claude"

[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

Model IDs change as providers evolve. Use the current model catalog or the provider list in Panel instead of copying stale static model names.

2. Configure Credentials

Use environment-variable interpolation for credentials:

export ANTHROPIC_API_KEY="sk-ant-..."

For production, prefer Aleph's encrypted secret management over plaintext values in the configuration file. See the current CLI surface with:

aleph-server secret --help

3. Diagnose and Start

aleph-server doctor
aleph-server start

The Gateway listens on 127.0.0.1:18790 by default. Its WebSocket endpoint is ws://127.0.0.1:18790/ws; the browser Panel uses the HTTP page on the same port.

4. Set Session Policies

Global defaults live under [policies]:

mode = "chat" | "work" | "code" controls only the tool presentation surface and defaults to work
exec_tier = "ask" | "auto" | "full" controls approval policy and defaults to auto

Session mode can also be changed in Panel or by the model through the session_set_mode tool. [sandbox.command_policy] remains a hard security floor that no execution tier can lower.

5. Configure Remote Access

A non-loopback bind requires native TLS, a trusted TLS reverse proxy, or an explicit insecure-remote opt-in. Native self-signed TLS is the recommended direct setup:

[gateway]
host = "0.0.0.0"
port = 18790

[gateway.tls]
enabled = true

When cert_path and key_path are empty, the core generates a self-signed certificate. Panel presents a TOFU approval and pins the certificate on first connection.

6. Configure Messaging Channels

Telegram, Discord, and iMessage fields and access policies are defined by the current channel schemas. Configure them in Panel or edit config.toml using the corresponding interface reference:

After changing channel configuration, restart the core or follow the current reload-impact classification.

Next Steps

Configuration — core configuration structure
Deployment — run as a persistent service
Quick Start — start and verify the Gateway