Setup Wizard

The setup wizard is the fastest way to get Aleph configured and ready to use. It walks you through every essential setting in a friendly, step-by-step flow — from choosing your AI provider to connecting messaging apps.

Starting the Wizard

Run the onboarding wizard from the command line:

aleph wizard

The wizard opens an interactive session in your terminal. You can also launch it through the Gateway RPC if you are building a client interface (see wizard RPC methods).

Wizard Variants

Aleph ships with three wizard flows. The default aleph wizard command runs the full onboarding flow.

The 10 Stages

Below is what to expect at each stage of the full onboarding wizard.

Stage 1 — Welcome

The wizard greets you and explains what it will configure:

• AI provider and model
• Optional secondary model for failover
• Thinking level for AI responses
• Messaging app integrations

No input required — press Enter to continue.

Stage 2 — Provider Selection

Choose your primary AI provider. Use the arrow keys to highlight an option and press Enter to select.

Stage 3 — Credentials

If you chose a cloud provider, the wizard asks for your API key:

Enter your anthropic API key:
> sk-ant-••••••••

The input is masked — your key is never displayed on screen. Aleph stores it securely in the local vault at ~/.aleph/.

If you chose Ollama, the wizard skips this step and reminds you to ensure Ollama is installed and running locally.

Stage 4 — Primary Model

Select the default model for your chosen provider. The options vary by provider. For example, with Anthropic:

Stage 5 — Secondary Model (Optional)

The wizard asks whether you want to configure a failover model:

Would you like to configure a secondary model for failover? (y/N)

If you answer yes, you repeat the provider, credentials, and model steps for the secondary provider. When the primary model is unreachable, Aleph automatically falls back to the secondary.

If you answer no (the default), the wizard moves on.

Stage 6 — Thinking Level

Choose how deeply Aleph reasons before responding:

You can always change this later per-conversation using aleph chat --thinking high.

Stage 7 — Messaging Apps

Select which messaging platforms to connect. This is optional — you can skip by pressing Enter without selecting anything.

If you select one or more apps, the wizard does not collect bot tokens here. You will configure those in ~/.aleph/config.toml or via aleph config set after the wizard completes.

Stage 8 — Review

The wizard displays a summary of everything you configured:

Configuration Summary:

  Primary Provider: anthropic
  Primary Model:    claude-sonnet-4-20250514
  Secondary:        None
  Thinking Level:   medium
  Messaging Apps:   telegram

Review the summary carefully before proceeding.

Stage 9 — Finalize

Apply this configuration? (Y/n)

If you confirm, the wizard validates your API keys and writes the configuration to ~/.aleph/config.toml. A progress indicator shows the status:

  Validating API keys...
  Saving configuration...
  Configuration saved

If you decline, the wizard exits without saving anything.

Stage 10 — Complete

Aleph is ready! Run 'aleph chat' to start.

You are done. Start chatting with aleph chat or launch the gateway with aleph gateway run.

Re-running the Wizard

You can run the wizard again at any time:

# Full onboarding — overwrites existing configuration
aleph wizard

# Add a new provider without touching other settings
aleph wizard --provider

Running the wizard again replaces the values for any stages you complete. Settings you skip (for example, declining the secondary model) remain unchanged from your current configuration.

Quick Setup

If you just want to get started with the recommended defaults (Anthropic Claude Sonnet 4, medium thinking), use the quick setup:

aleph wizard --quick

Quick setup only asks for your Anthropic API key and configures everything else automatically. It takes about 10 seconds.

Tips

• Wrong API key? Re-run aleph wizard --provider to update your credentials without reconfiguring everything else.
• Change thinking level later: Use aleph config set agents.defaults.thinking high or pass --thinking to individual commands.
• Messaging tokens: After the wizard, set up bot tokens with aleph config set channels.telegram.token "YOUR_TOKEN" and then start the channel with aleph channels start telegram.
• Skip the wizard entirely: Power users can edit ~/.aleph/config.toml directly — see Configuration for the full reference.

Next Steps

• Configuration — Fine-tune every setting by hand
• Deployment — Run Aleph as a persistent service
• Quick Start — Start chatting immediately