Quick Start

Desktop App

Download an artifact actually published for the current version from GitHub Releases. Package formats vary by release and platform; use the files attached to that release as the source of truth.

The desktop shell handles windows, tray, notifications, and OS integration. The aleph-server core owns inference, tools, and state.

Run from Source

Building from source requires Rust 1.95+. Building Panel or using repository development tasks also requires just, Node.js/npm, and wasm-bindgen-cli.

git clone https://github.com/rootazero/Aleph.git
cd Aleph
just dev

To start only the core:

cargo run --bin aleph-server

The Gateway uses 127.0.0.1:18790 by default:

Panel: http://127.0.0.1:18790/
WebSocket: ws://127.0.0.1:18790/ws

Minimal Configuration

Create ~/.aleph/config.toml:

[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

export ANTHROPIC_API_KEY="sk-ant-..."
aleph-server doctor
aleph-server start

mode defaults to work and affects only tool presentation. exec_tier defaults to auto and controls approval policy. The two axes remain orthogonal.

Verify

aleph-server status
aleph-server gateway call health

For a systemd user service, inspect logs with:

journalctl --user -u aleph-server.service -f

Remote Core

Enable a non-loopback listener and native TLS in the remote machine's ~/.aleph/config.toml:

[gateway]
host = "0.0.0.0"
port = 18790

[gateway.tls]
enabled = true

When cert_path and key_path are empty, Aleph generates a self-signed certificate. The remote WebSocket URL is wss://<host>:18790/ws; Panel presents a TOFU approval for the certificate fingerprint and SANs on first connection.

Next Steps

First-Time Configuration — current CLI and configuration flow
Configuration — core configuration structure
Gateway Protocol — WebSocket JSON-RPC API
Deployment — services, containers, and TLS