Leviath

A structured runtime for AI agents

Give a model one flat list of messages and a single big file read pushes your system prompt out of the window. Leviath gives it structure instead.

Coherent. Structured context regions mean an agent still knows what it read 50 tool calls ago.
Right-sized. Each phase of a task gets its own model, tools, and context layout, so you aren't paying frontier prices for file reads.
Light. Thousands of agents in one bevy_ecs process, from a single binary. No Node, Python, or Docker.

Tests Coverage License: MIT Docs stable beta alpha

Quick Start · Agents · Features · Dashboard · API · Comparison · Why not Leviath · Contributing

At a glance

lev run coder --task "Build a CLI that converts CSV to JSON"    # run a coding agent...
lev run deep-researcher --task "Survey solid-state batteries"   # ...or a research agent
lev ps                           # list running agents, and what each is waiting on
lev msg <agent-id> "..."         # steer a running agent mid-task
lev respond                      # answer questions agents are waiting on
lev dash                         # watch everything in the TUI dashboard
lev serve                        # REST + WebSocket API server
lev agent-client --agent coder   # serve an agent over the Agent Client Protocol
lev create my-agent              # scaffold your own agent

Quick Start

1. Install

macOS and Linux:

curl -fsSL https://leviath.dev/install.sh | sh

Windows, pasting into either Command Prompt or PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://leviath.dev/install.ps1 | iex"

Both install prebuilt binaries, so no Rust toolchain is needed. Stable is the default; for beta or alpha, pass the channel as an argument: curl -fsSL https://leviath.dev/install.sh | sh -s -- --channel beta. Release channels →

# macOS - what install.sh runs for you
brew tap gemisis/leviath https://github.com/GEMISIS/leviath-dist.git
brew trust gemisis/leviath          # Homebrew 6 requires trusting third-party taps
brew install leviath                # stable - or: leviath-beta, leviath-alpha

# Windows
scoop bucket add leviath https://github.com/GEMISIS/leviath-dist.git
scoop install leviath

Cargo (any platform, requires Rust):

cargo install leviath-cli                # released version from crates.io
cargo install --git https://github.com/GEMISIS/leviath.git --bin lev   # latest development build

Leviath is also a library: add the leviath crate to embed the runtime in your own application. The embedding guide covers building a world, spawning agents, and streaming their events in-process.

2. Configure a provider

One provider is all you need: an API key from Anthropic, OpenAI, Google AI, or OpenRouter. No key at all? Run a local Ollama, or opt into the Claude Code transport to run on your Claude subscription (read its terms-of-service note first).

lev setup      # interactive wizard

# scriptable. --install-agents is what puts the bundled blueprints on disk,
# so leaving it off means `lev run coder` has nothing to run.
lev setup --non-interactive --anthropic-key sk-ant-... --install-agents

3. Run an agent

lev run coder --task "Add pagination to the /users endpoint"

# ...or try a non-coding agent
lev run log-analyzer --task "Find what caused the error spike in ./logs last night"

lev run hands the agent to a background daemon that hosts every agent in one shared world, so runs keep going after your terminal closes. For unattended agents, lev daemon install puts it under launchd/systemd so it starts at login, restarts if it dies, and reloads interrupted runs. Daemon docs →

4. Create your own

lev create my-agent        # scaffolds a new agent directory
cd my-agent
lev run . --task "Your task here"

This writes an agent.leviath config you can customize: models per stage, context regions and their budgets, tools, and the workflow graph. Agent configuration →

Agents

Seven agents ship out of the box, covering coding, review, research, data gathering, and log analysis. Each is a multi-stage directed graph with structured context regions, per-stage model fallback, and error recovery, and five of them fan out to cover several things at once instead of one after another. coder is the largest:

Diamonds are LLM-routed or human-in-the-loop decisions, and dotted edges fire automatically on a runtime condition (like the stuck detector) rather than by the agent's choice. Every agent's workflow graph is in the agent catalog →

Features

Dashboard

lev dash is a full TUI for managing concurrent agents: stage tabs, context-window visualization, markdown rendering, sub-agent tree view, and full mouse support including drag-to-copy (works over SSH). Press m to manage MCP tool servers without leaving the dashboard. Dashboard docs →

API Server

lev serve exposes a REST + WebSocket API, so anything that speaks HTTP can integrate with it. No SDK required. It covers agent lifecycle, human-in-the-loop interaction, per-agent streaming, and signed webhook callbacks on completion. The Lair is a browser console that drives it, so you get a web UI without writing one. Because the API can spawn tool-executing agents, it refuses to start without a token and binds to 127.0.0.1 by default.

export LEVIATH_API_TOKEN="$(openssl rand -hex 16)"
lev serve --port 3000

# spawn an agent (with a completion webhook + signing secret)
curl -X POST http://localhost:3000/api/agents \
  -H "Authorization: Bearer $LEVIATH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"blueprint": "coder", "task": "Add input validation",
       "callback_url": "https://example.com/hook",
       "callback_secret": "whsec_…"}'

Full API reference →

Observability

Production deployments can export structured traces, metrics, and logs over OpenTelemetry. Every run becomes a trace (agent.run → agent.stage → per-call agent.inference / agent.tool_call spans) alongside token counters, latency histograms, and log records carrying the run's trace ID. Off by default; one config block turns it on. Observability docs →

Agent Client Protocol

lev agent-client --agent coder serves any Leviath agent over the Agent Client Protocol (JSON-RPC 2.0 over stdio), so hosts like Zed and Gas City can drive a headless agent as a child process. Wiring it into a host is config, not code. A session/prompt stays in flight until the run genuinely finishes, and hosts with session/request_permission get interactive tool approval in-turn. Editor integration docs →

"ACP" is claimed by two unrelated protocols; Leviath implements the Agent Client Protocol (JSON-RPC/stdio), not BeeAI's Agent Communication Protocol.

How it compares

Leviath is a runtime that agents run on. Claude Code, Codex, and OpenHands are agents you work with, CrewAI and LangGraph are frameworks you build agents in, and Gas Town and Gas City are orchestrators that decide which work happens. Several of those are worth running alongside Leviath rather than instead of it.

The full breakdown, including what each design buys and costs, when to reach for something else, a factor-by-factor score against 12-Factor Agents, and why you might not want Leviath at all, is on the docs site: Where Leviath sits →

Why you might not want Leviath

• It's not a replacement for Claude Code, Codex, or your favorite coding agent. Those are polished interactive products at a different layer, and Leviath can even run on top of Claude Code as a transport.
• Agents are config, not code. A Leviath agent is a TOML blueprint plus optional Rhai script tools. If you want to write agent logic in Python or TypeScript against an SDK, other languages drive Leviath through the REST API instead.
• Agents execute on one machine. The daemon hosts every agent in a single process on a single box. You can reach it from anywhere over the REST and WebSocket API, and it can call out through signed webhooks, but there is no hosted service and no scheduling work across several machines.
• Isolation is at the data layer by default. Every agent has its own state, working directory, tool policy and read-path grants, and a panic fails that agent alone rather than the daemon. The OS sandbox is opt-in: one [sandbox] block turns it on for the whole world and each agent gets its own container or namespace, which a blueprint may tighten per stage but never loosen. Two limits are worth knowing. There is no way to sandbox a single lev run on demand, and the boundary covers what an agent executes (shell, seed commands, script shell()) rather than file tools, web_fetch, or MCP servers, which stay on the host behind workdir confinement. Widening it is the intended end state.
• You need a model provider: an API key, a local Ollama, or the Claude Code transport (with its terms-of-service caveat).

CLI

The At a glance block above covers the daily commands; the full surface (packaging, testing, policy, auth, daemon control) is in lev --help and the CLI reference. Every config.toml key and environment variable is in the configuration reference.

Leviath also connects to Model Context Protocol tool servers over stdio or HTTP: lev mcp add detects OAuth servers and opens your browser to log in, and tokens are stored with 0600 permissions and refreshed automatically. MCP docs →

Providers

Anthropic, OpenAI, Google (Gemini), OpenRouter, local Ollama with no key, and the Claude Code subscription transport, with per-stage model fallback, optional client-side rate limits enforced before each call, and custom OpenAI-compatible providers as Rhai scripts. Provider docs →

Security

Leviath runs LLM-driven tools on your machine. SECURITY.md states plainly what it defends against and what it does not, and covers vulnerability reporting, hardening a lev serve deployment, and verifying a release's signed build provenance.

Contributing

git clone https://github.com/GEMISIS/leviath.git
cd leviath
cargo build
cargo test --workspace

The workspace is gated at a hard 100% coverage on lines, regions, and functions, with no opt-outs and coverage-suppression markers banned by lint; CI enforces it on Linux, macOS, and Windows. The only exclusion is the thin lev binary entrypoint, guarded by a CI check. CONTRIBUTING.md covers the rest.

graph TD
    CLI["leviath-cli"]
    LIB["leviath"]
    RT["leviath-runtime"]
    TOOLS["leviath-tools"]
    PROV["leviath-providers"]
    CORE["leviath-core"]
    MCP["leviath-mcp"]
    ACP["leviath-agent-client"]
    PKG["leviath-package"]
    SCRIPT["leviath-scripting"]
    TELEM["leviath-telemetry"]
    NET["leviath-net"]
    SYS["leviath-sys"]

    CLI --> RT
    CLI --> MCP
    CLI --> ACP
    CLI --> PKG
    CLI --> NET
    LIB --> RT
    LIB --> MCP
    LIB --> ACP
    LIB --> PKG
    LIB --> TELEM
    RT --> TOOLS
    RT --> PROV
    RT --> SCRIPT
    TOOLS --> CORE
    TOOLS --> SYS
    PROV --> CORE
    PROV --> SYS
    MCP --> CORE
    MCP --> SYS
    ACP --> CORE
    PKG --> CORE
    SCRIPT --> CORE
    TELEM --> CORE

License

MIT © Gerald McAlister

Website · Docs · GitHub · Issues