---
title: Where Leviath fits
description: The four ways to drive Leviath from a tool you already use, and how to choose between them.
group: Integrations
group_order: 5
order: 1
---

# Running Leviath under another tool

If you already use an orchestrator like [Gas City](/docs/gas-city) or
[OpenHands](https://docs.all-hands.dev/), you have something deciding *which* work happens: which
issue gets picked up, which repo it runs in, who reviews the result. What you plug into it decides *how* one piece of that work actually gets done.

That second job is what Leviath is. Your orchestrator keeps doing the coordinating. Leviath takes
one task and runs it as a multi-stage agent with structured context, its own tools, and whichever
models you configured.

```mermaid
flowchart TD
  ORCH["Your orchestrator<br/>Gas City / OpenHands / CI"]
  ORCH -->|"stdio JSON-RPC"| ACP["lev agent-client"]
  ORCH -->|"one process per job"| RUN["lev run"]
  ORCH -->|"HTTP + WebSocket"| API["lev serve"]
  ORCH -->|"Rust library"| EMB["the leviath crate"]
  ACP --> D["Shared-world daemon"]
  RUN --> D
  API --> D
  EMB --> W["Embedded world"]
  D --> M["Model providers"]
  W --> M
```

## Which way in

| You want | Use | Covered in |
|---|---|---|
| A host that already speaks the Agent Client Protocol | `lev agent-client` | [Agent Client Protocol](/docs/agent-client-protocol) |
| One run per job, usually in a container | `lev run` | [CLI reference](/docs/cli) |
| A long-lived service that several jobs share | `lev serve` | [HTTP API](/docs/api) |
| Leviath inside your own Rust program | the `leviath` crate | [Embedding](/docs/embedding) |

Most orchestrators land on one of the first two. If yours can launch a subprocess and speak
JSON-RPC over its stdin and stdout, use `lev agent-client`, because you get streaming output and
in-turn tool approvals for free. If it thinks in terms of "run this command in this container until
it exits", use `lev run`.

## Three things worth knowing up front

**Approvals need somewhere to go.** By default Leviath asks before a tool call that changes
something. Under an orchestrator there is usually nobody there to answer, so a run would stop and
wait indefinitely. Either run with `--yolo`, or list the specific tools you trust with `--allow`.
The [Gas City page](/docs/gas-city) covers what this looks like in practice.

**The daemon outlives your command.** `lev run` hands the agent to a background
[daemon](/docs/daemon) and returns. In a container that exits as soon as the command finishes, that
is the wrong shape, and [Containers and CI](/docs/containers) covers how to handle it.

**Polling needs the right field.** If your side tracks slots and needs to know whether a run is
still going, read [External work queues](/docs/work-queues) first. Two of the obvious fields to poll
do not mean what they look like.

## When Leviath is not the right choice

Three cases where plugging Leviath in does not pay off:

- **For a single quick edit**, a coding agent CLI you already have is less setup and does the job.
  Leviath is worth the wiring on work with several distinct phases, or on many agents at once.
- **If your orchestration already lives in Python** and you want the workflow expressed in code
  rather than TOML, a framework you can import is a better fit than a separate runtime.
- **If you need an OS boundary around every tool an agent has**, note that Leviath's opt-in
  [sandbox](/docs/security) covers shell execution today, and its file tools are path-confined
  rather than containerized. Widening it is
  [in progress](https://github.com/GEMISIS/leviath/issues/326). Meanwhile, running the whole daemon
  in a container gives you the blanket boundary, and a container-per-job orchestrator gives you one
  per unit of work.

[Where Leviath sits](/docs/comparison) goes into this properly.