Quick Start

Get Aleph running in under 5 minutes.

Option 1: Desktop App (Fastest)

Download the latest release for your platform:

1. Install and launch the app
2. Complete the setup wizard (API key, model selection)
3. Start chatting

The desktop app bundles the core server as a background daemon. The shell stays in your system tray; closing the window does not stop the server.

Global hotkey: CmdOrCtrl+Shift+A summons the window from anywhere.

Connect to a Remote Core

The desktop shell can connect to a remote aleph-server over Tailnet or VPN:

# On the remote machine, ensure the gateway is accessible
aleph gateway run --bind 0.0.0.0 --port 18790

Then point your local shell at the remote origin (advanced — see Configuration).

Option 2: From Source (Development)

1. Build and Run

# Clone the repository
git clone https://github.com/rootazero/Aleph.git
cd Aleph

# Run in development mode (rebuilds WASM automatically)
just dev

# Or build and run manually
cargo run --bin aleph-server

The server starts on ws://127.0.0.1:18790 by default.

2. Configure

Create your configuration file at ~/.aleph/config.toml:

mkdir -p ~/.aleph
cat > ~/.aleph/config.toml << 'EOF'
[agent]
model = "anthropic/claude-sonnet-4"

[provider.claude]
protocol = "anthropic"
api_key = "${ANTHROPIC_API_KEY}"

[gateway]
port = 18790
bind = "127.0.0.1"
EOF

Set your API key:

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

3. Connect via WebChat

Open the WebChat interface at http://localhost:18790 (or the port configured in gateway.port).

The WebChat is a WASM-based UI that connects to the Gateway WebSocket.

4. Connect a Messaging Channel (Optional)

Telegram

Add to ~/.aleph/config.toml:

[channel.telegram]
enabled = true
token = "YOUR_BOT_TOKEN"

Restart the server to pick up the new channel.

Discord

[channel.discord]
enabled = true
token = "YOUR_BOT_TOKEN"

5. Verify

Check that the server is running:

# Server logs show "Gateway listening on ws://127.0.0.1:18790"
tail -f ~/.aleph/logs/aleph.log

Test the WebSocket connection:

curl http://localhost:18790/health

Architecture at a Glance

Single-Core Multi-Terminal, Shell-Core Separation; Gateway Interoperability, Access Control.

• One core (aleph-server) powers every interface
• Shell (desktop app) = pure OS integration; Core = all business logic
• All terminals speak the same authenticated WebSocket protocol
• Desktop shell can connect to local or remote core

Next Steps

• Configuration - Full configuration reference
• Gateway Protocol - WebSocket JSON-RPC API
• Interfaces - Connect more platforms
• Architecture - Deep dive into shell-core separation