Aleph Documentation

"This is the first time in human history, a machine's soul has been given a body." — Ghost in the Shell

Aleph is a personal AI assistant built in Rust. It fuses a high-performance Gateway control plane with multi-channel messaging, memory governance, tool execution, and a federation of local/remote executor nodes — all in a single core — so AI agents can work across your platforms on your hardware, with end-to-end visibility.

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

One aleph-server core powers every interface — desktop app, CLI, TUI, Telegram, Discord, iMessage, and more. The native desktop shell is a thin container with zero business logic; all reasoning, tools, and state live in the core. Every terminal connects through the same authenticated WebSocket gateway, whether local or remote.

Key Features

• Multi-Provider AI — Claude, GPT, Gemini, Ollama with atomic-counter failover and an atomic regen marker; session.usage is computed in-core from a single source of pricing
• Multi-Channel — Telegram, Discord, iMessage, WebChat, and the desktop app share one authenticated gateway, inbound router, session model, memory, and tool ecosystem
• Session Mode (chat / work / code) — the third twin of exec_tier and think_level; statically partitions the tool presentation surface; switchable at runtime via session_set_mode
• Native Performance — 100% Rust core, no interpreted languages
• Shell-Core Separation — desktop shell is pure OS integration; the core runs standalone
• Remote Core + Self-Signed TLS — connect the desktop shell to a remote aleph-server over Tailnet/VPN; the SAN auto-discovers the host's non-loopback interface IPs
• TOFU Certificate Trust — fingerprint + SAN approval, pinned locally, surfaced in-app from the Panel
• Cluster Federation — one center core orchestrates many machines (nodes) as execution arms; node keys are Unicode-normalized (CJK node names work)
• Three-Tier Security Model — fail-closed approval / sandbox / pairing, with exec_tier, session mode, and a capability ledger
• Loop-Graph Governance Layer — team node / independent-evidence auditor (loop-auditor) / victory-claim watchers / objective ACLs
• Extensible — type-safe built-in tools, capability-gated MCP discovery, plugins, Markdown skills, and custom tools share the scoped tool service and approval path
• Self-Hosted — run on your own hardware, full control

Architecture

                          Terminals
    ┌────────────────────────────────────────────────────────────┐
    │ Desktop │   CLI    │ Telegram │ Discord │ iMessage │  TUI  │
    │(Tauri v2)│         │          │         │          │       │
    └────┬─────┴────┬─────┴────┬────┴────┬────┴────┬─────┴──┬────┘
         │          │          │         │         │         │
         │       WebSocket (JSON-RPC 2.0, optional wss://)    │
         │          │          │         │         │         │
    ┌────▼──────────▼──────────▼─────────▼─────────▼─────────▼───┐
    │                  Aleph Core (aleph-server)                  │
    │  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────┐ │
    │  │  Gateway    │  │  Harness     │  │  Tool Registry      │ │
    │  │  (TLS/TOFU) │  │ (Think→Act)  │  │ (builtin/MCP/plugin)│ │
    │  └─────────────┘  └──────────────┘  └─────────────────────┘ │
    │  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────┐ │
    │  │  Thinker    │  │  Session     │  │  Memory + Loop      │ │
    │  │ (PromptBuilder)│ │ Service      │  │  Graph (governance) │ │
    │  └─────────────┘  └──────────────┘  └─────────────────────┘ │
    │  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────┐ │
    │  │  Approval / │  │  Extension   │  │  Heartbeat / Cron   │ │
    │  │  Guardrails │  │  / Skill     │  │  Schedulers         │ │
    │  └─────────────┘  └──────────────┘  └─────────────────────┘ │
    └────────────────────────────────────────────────────────────┘
                                  │
                                  │ Authenticated execution dispatch
                                  ▼
                        Cluster Nodes (remote executors)

Shell-Core Separation. The desktop app is a thin Tauri v2 shell — window, tray, notifications, auto-update, global hotkey. It contains no business logic and no business UI. All product UI lives in the Leptos Panel (served by the core at http://127.0.0.1:18790). All reasoning, tools, and state live in aleph-server. The shell can connect to a local core or a remote one (self-signed TLS with client-side TOFU pinning).

The Third Twin: Session Mode. chat / work / code is the third user-adjustable dimension alongside exec_tier (execution approval tier) and think_level (thinking budget). It statically partitions the tool presentation surface only (progressive-disclosure core set + deferred-tool tier); permissions remain controlled by exec_tier and the approval gate. Switchable from the Panel composer pill, from Settings → Policies, or via the session_set_mode tool.

Loop-Graph Governance Layer. loop_graph adds a governance topology on top of the harness: team nodes / audit ring / objective ACLs / victory-claim watchers / built-in loop-auditor agent. It gives the four single-loop failure modes (Goodhart, reference blindness, ring conflict, measurement decay) a topological answer.

Quick Start

# Build the core from source (Rust 1.95+)
git clone https://github.com/rootazero/Aleph.git
cd Aleph
cargo build --bin aleph-server --release

# Create ~/.aleph/config.toml, then start the core
./target/release/aleph-server doctor
./target/release/aleph-server start

Open http://127.0.0.1:18790/, or connect the CLI to ws://127.0.0.1:18790/ws.

Documentation Sections

Philosophy

Aleph is built on a five-layer emergence architecture:

1. Sea of Knowledge — AI's pre-training foundation
2. Domain Classification — Organized expertise
3. Atomic Skills — Know-what to Know-how
4. Functional Modules — Composable capabilities
5. Polymorphic Agents — Soul gains body

The goal is not just to build a tool, but to explore a path toward AGI — when intelligence gains the ability to act.

License

Apache 2.0