llms.txt
Compare with other sites' llms.txt files →# Leviath
> A structured agent runtime for LLMs: coherent context across hundreds of tool calls, a model per phase, and many agents in one process.
## Getting Started
Leviath runs LLM agents. What it adds over asking a model directly is **structure**. That means
context that stays coherent across hundreds of tool calls, a different model for each phase of a
task, and thousands of agents running at once in one process.
You'll go from nothing to a running agent in four steps:
```mermaid
flowchart LR
A["Install<br/>lev"] --> B["Configure<br/>a provider"]
B --> C["Run<br/>an agent"]
C --> D["Read<br/>the result"]
```
### Install
One command, any platform. It installs a prebuilt binary, so no Rust toolchain is needed.
**macOS and Linux**
```bash
curl -fsSL https://leviath.dev/install.sh | sh
```
**Windows**, in PowerShell (Windows Terminal opens one):
```powershell
irm https://leviath.dev/install.ps1 | iex
```
No administrator is needed: it unpacks into `%LOCALAPPDATA%\Leviath\bin` and adds that folder to
your own PATH.
Paste it into PowerShell rather than Command Prompt. The old form that spawned PowerShell from
cmd (`powershell -ExecutionPolicy Bypass -c "..."`) is the launch pattern endpoint protection
refuses on managed machines. It answered "Access is denied." before anything ran.
If Windows Defender or another antivirus quarantines `lev.exe`, that is a false positive on a new,
unsigned binary, not something it found. You can check the file is exactly what this repo's CI
built with `gh attestation verify "$env:LOCALAPPDATA\Leviath\bin\lev.exe" --repo GEMISIS/leviath`.
Then restore it from quarantine, or add the folder to the exclusions. Reporting it as a false
positive to your vendor helps every later install.
Check it worked:
```bash
lev --version
```
That is the whole install. The options below are here when you want them, not because you need
them.
<details>
<summary>Prefer Homebrew or Scoop</summary>
The one-liners above already use Homebrew on macOS when you have it. To manage the tap yourself:
```bash
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
```
On Windows, Scoop works the same way:
```powershell
scoop bucket add leviath https://github.com/GEMISIS/leviath-dist.git
scoop install leviath
```
</details>
<details>
<summary>Switch to the beta or alpha channel</summary>
`stable` is the default. It is what you want unless you have a reason to be ahead of it. To ride a
faster channel, pass it to the installer:
```bash
curl -fsSL https://leviath.dev/install.sh | sh -s -- --channel beta
```
The installer prints which channel it is about to install, so you can see you got the one you
asked for.
Homebrew and Scoop name the channels as separate packages instead: install `leviath-beta` or
`leviath-alpha` in place of `leviath`. See [Releases and channels](/docs/releases) for what each
channel means and how often it moves.
</details>
<details>
<summary>Build with Cargo, or embed the runtime</summary>
With [Rust](https://rustup.rs/) installed:
```bash
cargo install leviath-cli # released version from crates.io
cargo install --git https://github.com/GEMISIS/leviath.git --bin lev # latest development build
```
To embed the runtime in your own application instead of running the CLI, add the
[`leviath`](https://crates.io/crates/leviath) crate as a dependency.
</details>
### Configure a provider
One provider is all you need. That can be an API key from Anthropic, OpenAI, Google AI, xAI, Meta,
or OpenRouter. It can be a ChatGPT or Grok subscription you sign in to (OpenAI Codex or Grok, no
key). It can also be a local [Ollama](https://ollama.com) with no key at all.
```bash
lev setup
```
The wizard detects keys already in your environment, sets a default model, and installs the
pre-built agents.
> [!TIP]
> No API key handy? Two paths need none: sign in to a ChatGPT or Claude subscription, or point
> Leviath at a local [Ollama](https://ollama.com) install and run entirely offline. `lev setup`
> sets up either. See [Providers](/docs/providers) for the full list.
<details>
<summary>Script the setup instead</summary>
For CI, containers, or any headless machine:
```bash
lev setup --non-interactive --anthropic-key "$ANTHROPIC_API_KEY" --install-agents
```
Two flags matter more than they look:
- `--install-agents` installs the pre-built agents. Without it, non-interactive setup configures
the provider and installs nothing.
- `--default-model <provider>/<model>` sets the model every stage falls back to. Without a default
model, a blueprint's own list decides, which may not pick your provider.
The other credential flags are `--openai-key`, `--google-key`, `--openrouter-key`,
`--bedrock-key` (with `--bedrock-region`), and `--ollama-url`. See [`lev setup`](/docs/cli#lev-setup) for the full set.
</details>
### Run an agent
First `cd` into the directory you want the agent working in. That directory becomes the run's
**workdir**: its file tools are confined to it, and its output lands there.
Then pick one of the seven [pre-built agents](/docs/agent-catalog) and give it a task:
```bash
lev run coder --task "Build a CLI that converts CSV to JSON"
lev run deep-researcher --task "Survey the state of solid-state batteries"
```
A run spends real API tokens on your configured provider. For a free first try, point
`lev setup` at a local Ollama instead.
Leave `--task` off and your editor opens on a template, which is easier than
fighting shell quoting for anything longer than a sentence. It also takes a
file: `lev run coder --task ./brief.md`.
`lev run` returns as soon as the work is accepted, not when it is done. The agent runs in the
background and keeps going after you close the terminal, so the next section is how you check on
it. Real tasks take minutes.
### Read the result
Watch it live, or come back later. Either way:
```bash
lev dash # live view of every run
lev ps # one-shot list: what is running, what finished
lev result <run-id> # the answer, once a run is complete
```
Files the agent created are in the workdir you ran it from. See [Outputs](/docs/outputs) for
structured answers.
Expect to be asked things along the way. The agent **stops and waits** before it writes a file or
runs a shell command. Answer in `lev dash` (select the run, `Enter`, then `i`) or with
[`lev respond`](/docs/interaction), or pass `--yolo` to pre-approve everything for an unattended
run. To pre-approve some of it and keep the rest,
[write a yolo profile](/docs/first-yolo-profile).
> [!TIP]
> Prefer a visual UI? Serve the daemon over HTTP and open
> [The Lair](https://leviath.dev/lair), the browser console:
>
> ```bash
> lev serve --token <your-secret> --cors https://leviath.dev
> ```
>
> It shows the same runs, context, logs, and interactions, from any browser.
On Windows the agent's shell is `cmd.exe`, not a POSIX shell, and Leviath tells the model so. See
[which shell you get](/docs/tools#which-shell-you-get), and
[Troubleshooting](/docs/troubleshooting#windows-quoting-and-environment-variables) for PowerShell
quoting and environment-variable syntax.
### Keep it up to date
One command brings everything current: the binary, the bundled agents, and the config file.
```bash
lev update --check # show what would change, touch nothing
lev update # do it
```
The binary is upgraded with whatever installed it (Homebrew, Scoop, the install script), and then
the agents in `~/.leviath/agents` and the config beside them are offered the same treatment. That
second half is the reason to use `lev update` rather than `brew upgrade` alone: a package manager
hands you a new binary and says nothing about blueprints written for the old one. The full flag
list is under [`lev update`](/docs/cli#lev-update).
### Create your own
```bash
lev create my-agent # scaffolds an agent directory
cd my-agent
lev run . --task "Your task here"
```
This writes an `agent.leviath` file you can customize: the stages, the model for each phase, and
the context regions. [Build your first agent](/docs/first-agent) walks through writing one from
scratch, a stage at a time, and is the natural next thing to read.
### Where to go next
- The [Agent catalog](/docs/agent-catalog) tours the seven pre-built agents and what each is for.
- [Build your first agent](/docs/first-agent) writes one from an empty directory, explaining each
piece as it goes.
- [Overview](/docs/overview) explains what Leviath is doing underneath: stages, context regions,
and the shared world your agents run in.
- [Agent blueprints](/docs/agents) covers what goes in an `agent.leviath` file, for building your
own.
- [Troubleshooting](/docs/troubleshooting) has the common snags, and `lev doctor` diagnoses most of
them for you.
- [Glossary](/docs/glossary) defines every term these docs use in a particular way. Worth a skim if
a page starts using a word you have not met.
- [Where Leviath sits](/docs/comparison) is for deciding whether you want Leviath at all, and what
to run alongside it.
- [How Leviath integrates](/docs/integrations) covers driving Leviath from a tool you already use,
like an orchestrator or a CI job.
---
## Documentation
Every link below is the page as raw Markdown.
### Get started
- [What is Leviath?](https://leviath.dev/docs/stable/what-is-leviath.md): Why Leviath exists, the six ideas it is built on, and whether it is for you. Start here if you are new.
- [Getting Started](https://leviath.dev/docs/stable/getting-started.md): Install Leviath, configure a provider interactively or headlessly for CI, and run your first agent, in four steps.
- [Where Leviath sits](https://leviath.dev/docs/stable/comparison.md): Where Leviath sits among other agent tools, and which are worth running alongside it rather than instead of it.
- [Providers](https://leviath.dev/docs/stable/providers.md): Set up Anthropic, OpenAI, Google, xAI, Meta, OpenRouter, Bedrock, Meshy, Ollama, or a Codex or Grok sign-in, and pick each stage's model.
- [Agent catalog](https://leviath.dev/docs/stable/agent-catalog.md): The seven pre-built agents Leviath ships, what each is for, how to install them, and the lev run command for each.
- [Build your first agent](https://leviath.dev/docs/stable/first-agent.md): Build a release-notes agent from an empty directory: stages, models, context regions, an error edge, and a structured answer.
- [Build an advanced agent](https://leviath.dev/docs/stable/advanced-agent.md): Build an agent that turns a one-line idea into concept art and a short film, with text, image and video models handing their work from stage to stage.
- [Built-in tools](https://leviath.dev/docs/stable/tools.md): The built-in tool catalog every agent can advertise, and how a stage decides which ones the model may call.
- [MCP tool servers](https://leviath.dev/docs/stable/mcp.md): Connect Leviath to Model Context Protocol servers over stdio or HTTP, giving agents tools beyond the built-ins.
- [Write your first yolo profile](https://leviath.dev/docs/stable/first-yolo-profile.md): Build a yolo profile that lets an unattended run compile and test on its own, while it still stops at anything you did not approve in advance.
### Concepts
- [Overview](https://leviath.dev/docs/stable/overview.md): How the pieces of Leviath fit together: blueprints, stages, context regions, tools, and the shared world that runs them.
- [The daemon](https://leviath.dev/docs/stable/daemon.md): The background daemon that owns every run, so agents survive a closed terminal and share one process.
- [The agent engine](https://leviath.dev/docs/stable/engine.md): How one process runs many agents at once: each is a row of data in an Entity Component System, so a waiting agent costs almost nothing.
- [Agent blueprints](https://leviath.dev/docs/stable/agents.md): The agent.leviath blueprint format: the TOML defining an agent's stages, models, tools, and context layout.
- [Structured context](https://leviath.dev/docs/stable/context.md): How structured context regions keep an agent coherent across hundreds of tool calls, where a flat message list drifts.
- [Multi-stage workflows](https://leviath.dev/docs/stable/stages.md): Split an agent into stages so each phase of a task gets its own model, tools, and context.
- [Final outputs](https://leviath.dev/docs/stable/outputs.md): Get a structured answer out of a run with output formats, schemas, and lev result, instead of scraping its logs.
- [More than text](https://leviath.dev/docs/stable/mime.md): Agents that read, draw, speak and film. Images, audio, video, documents and 3D models move through regions, tools, stages and outputs.
- [Sub-agents & fan-out](https://leviath.dev/docs/stable/sub-agents.md): Start child agents and fan work out across them, so many small jobs run at once.
- [Human-in-the-loop](https://leviath.dev/docs/stable/interaction.md): What to do when a run shows waiting: answer agent questions, tool approvals, and checkpoints with lev respond, the dashboard, or the API.
- [Security & sandboxing](https://leviath.dev/docs/stable/security.md): Sandboxed execution, tool permissions, and taint tracking, for running a blueprint you did not write.
- [Data retention](https://leviath.dev/docs/stable/data-retention.md): What each provider keeps of your prompts and replies, how to ask for zero retention, and how Leviath refuses a model that cannot give it.
### Reference
- [Configuration](https://leviath.dev/docs/stable/configuration.md): Every config.toml key with its type and default, the env vars that fill them when the file is empty, and the published JSON schema.
- [HTTP API](https://leviath.dev/docs/stable/api.md): Every REST route and WebSocket stream `lev serve` exposes, with auth, payload shapes, and the published OpenAPI spec.
- [CLI reference](https://leviath.dev/docs/stable/cli.md): Every lev command and flag, which ones speak --json for scripts and CI, and how to read lev ps status and wait reasons.
- [Yolo profiles](https://leviath.dev/docs/stable/yolo.md): Name a set of approval rules in yolo.toml so an unattended run builds and tests on its own, and still stops before anything risky.
- [GraphQL API](https://leviath.dev/docs/stable/graphql.md): The GraphQL endpoint `lev serve` answers beside its REST routes, with its filter grammar, paging, mutations, live frames and published schema.
- [Rhai scripting](https://leviath.dev/docs/stable/scripting.md): The Rhai extension points, providers, tools, regions, hooks, and validators, and the sandbox each one runs in.
- [Rhai providers](https://leviath.dev/docs/stable/rhai-providers.md): Teach Leviath any HTTP model API with a Rhai script, without waiting for it to be added upstream.
- [Rhai regions](https://leviath.dev/docs/stable/rhai-regions.md): Write a context region's behaviour in Rhai when none of the built-in kinds does what you want.
- [Rhai tools & policy rules](https://leviath.dev/docs/stable/rhai-tools.md): Declare new agent tools in Rhai, and write policy rules deciding whether a tool call may fire.
- [Rhai output validators](https://leviath.dev/docs/stable/rhai-validators.md): Teach Leviath what "valid" means for your own output format, so a bad answer is caught and retried instead of shipped.
- [Rhai stage hooks](https://leviath.dev/docs/stable/rhai-hooks.md): Run your own Rhai at seven points in an agent's lifecycle to seed a stage, gate a call, or reshape an answer.
- [Rhai mime checks](https://leviath.dev/docs/stable/rhai-mime-checks.md): Say what bytes must look like to be stored as one of your mime types, so a mislabelled file is refused where it arrives, not three tools later.
- [Agent Client Protocol](https://leviath.dev/docs/stable/agent-client-protocol.md): Serve an agent over the Agent Client Protocol on stdio, so an editor or orchestrator can drive it as a child process.
- [Observability](https://leviath.dev/docs/stable/observability.md): Export traces, metrics, and logs over OpenTelemetry so your dashboards can answer which run is stuck.
- [Embedding](https://leviath.dev/docs/stable/embedding.md): Run the Leviath runtime inside your own Rust process with the leviath crate, with no CLI, daemon, or config file.
### Guides
- [Dashboard](https://leviath.dev/docs/stable/dashboard.md): The `lev dash` terminal UI for watching a fleet of runs, answering their questions, and steering them.
- [Managing your costs](https://leviath.dev/docs/stable/costs.md): What a run actually costs and why, how to watch it while it happens, and the knobs that bound it - each one with the measurement behind it.
- [Troubleshooting](https://leviath.dev/docs/stable/troubleshooting.md): Common snags organised by symptom, starting with what `lev doctor` tells you.
- [Reporting issues](https://leviath.dev/docs/stable/reporting-issues.md): How to pack the logs and settings a bug report needs with `lev rage`, what the zip holds, what it never holds, and how to attach it to an issue.
- [Glossary](https://leviath.dev/docs/stable/glossary.md): Every term the Leviath docs use in a particular way, defined in one place.
- [Packaging blueprints](https://leviath.dev/docs/stable/packaging.md): Bundle a blueprint into a .leviath-bundle, install one, and share it without a hosted registry.
- [Releases and channels](https://leviath.dev/docs/stable/releases.md): How the alpha, beta, and stable channels work, and why stable ships the byte-for-byte alpha build.
### Integrations
- [How Leviath integrates](https://leviath.dev/docs/stable/integrations.md): The four ways to drive Leviath from a tool you already use, and how to choose between them.
- [Gas City](https://leviath.dev/docs/stable/gas-city.md): Wiring Leviath into Gas City, the multi-agent orchestration SDK, as the coding-agent backend behind its workflows.
- [OpenClaw](https://leviath.dev/docs/stable/openclaw.md): Wiring Leviath into OpenClaw as a custom acpx harness, so a gateway agent can hand one task to a multi-stage run.
- [Containers and CI](https://leviath.dev/docs/stable/containers.md): Running Leviath as a container-per-job step, and the one thing to get right, that `lev run` returns before the agent finishes.
- [External work queues](https://leviath.dev/docs/stable/work-queues.md): Poll lev ps --all --json to tell a live run from a dead one, without leaking slots or cancelling work that is still going.
## Machine-readable
Schemas for the formats you would otherwise infer from prose.
- [Blueprint JSON Schema (agent.leviath)](https://leviath.dev/docs/stable/blueprint.schema.json)
- [Config JSON Schema (config.toml)](https://leviath.dev/docs/stable/config.schema.json)
- [OpenAPI spec (lev serve)](https://leviath.dev/docs/stable/openapi.json)
## Everything at once
The complete documentation is one file at https://leviath.dev/docs/stable/llms-full.txt.