Self-hosted runtimes

A self-hosted runtime is a machine you operate that executes an agent's nodes. The agent itself stays on Levain: its recipe and versions, triggers, schedules, channels, run logs, and the improvement loop all work as before. Only the nodes run elsewhere, with whatever dependencies, tools, data, and credentials that machine has.

Self-hosted runtimes are available on Enterprise plans.

How it worksCopy Anchor Link

The runner, levain-runtime, opens one outbound connection from your machine to Levain's runtime gateway. Levain never connects inbound. Over that connection the platform dispatches each node of a run and streams its logs back, and the agent reaches everything it would reach on Levain: progress and memory, artifact publishing, the knowledge base, app data, and model calls when the runtime uses your Levain plan for models.

Two execution modes:

• direct runs nodes as processes on the host. Use it on a machine you already set up for the work, such as a workstation holding a dataset.
• docker starts one container per conversation from an image you choose. Use it to pin dependencies or isolate the agent from the host.

Two model credential modes:

• platform keeps model calls on your Levain plan, metered as usual, with full run cost reporting. Bring Your Own Key works the same way.
• local uses the model provider login present on the machine. Model usage is neither metered nor reported.

Compute on a self-hosted runtime is not billed. Builds and verification of the agent's versions still run on Levain and are billed as usual.

Set up the machineCopy Anchor Link

Install the runner and prepare the machine:

uv tool install levain-runtime
levain-runtime init --mode direct

init creates the directories nodes expect under ~/.levain/runtime. In direct mode it asks for sudo once to create four links at the root of the filesystem (/workspace, /recipes, /sdk, /sandbox). On macOS those links come from /etc/synthetic.conf; init writes the entries and asks you to restart the machine once.

For docker mode pass --mode docker --image <image>. The image needs Python 3.12 or later with levain-sdk[review,models] installed, plus whatever your recipe imports. With local model credentials the runner copies the host's Claude login into each container.

Register the runtimeCopy Anchor Link

From the machine, with a workspace API key:

export LEVAIN_API_KEY=...
levain-runtime register --name workstation --model-auth local
levain-runtime up

register stores the runtime's credentials on the machine. up keeps running: it holds the tunnel, serves node executions, and reports liveness. The runtime shows as online under Settings → Runtimes while it does.

You can also register from Settings → Runtimes in the app, with the create_runtime tool in Claude, or with POST /api/v1/runtimes. Those return the credentials once; save them as a file and run levain-runtime connect --credentials credentials.json on the machine. Delete the runtime and register a new one if the credentials are lost.

Bind an agentCopy Anchor Link

Open the agent's Settings tab and pick the runtime under Runtime, or use the set_agent_runtime tool in Claude. Over the API:

curl -X PATCH https://api.levainlabs.com/api/v1/agents/$AGENT \
  -H "Authorization: Bearer $LEVAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config": {"runtime_id": "<runtime id>"}}'

From the next run on, the agent's nodes execute on that machine, and each run shows the runtime it ran on. Pick Levain cloud again, or unset runtime_id, to move the agent back. A runtime cannot be deleted while an agent is bound to it.

LimitsCopy Anchor Link

• A direct runtime serves one conversation at a time. A second conversation waits up to ten minutes for the first to pause, then fails. Use docker mode for concurrency.
• Runs of an agent bound to an offline runtime wait up to ten minutes for it to come back, then fail with a clear reason.
• Only agents you designed can be bound. Managed agents and organization agents always run on Levain.
• In direct mode with local model credentials, nodes inherit the host account's Claude Code configuration, including its connectors and skills. Their tool definitions count toward every node's context, so prefer a dedicated account or docker mode on a machine with a busy personal setup.