LanternDocs

Run agents in production, on infrastructure you control.

Lantern is the self-hosted runtime for AI agents. The agent loop runs on your control plane; untrusted code runs in its own microVM. Durable runs, hard budgets, capability-routed models and signed receipts come with it.

Run it locallymake dev, then lantern onboard: a running agent and the dashboard on localhost:3001.Run code in a sandboxWrite an agent.yaml, pick an isolation class, and lantern run it in a microVM.Understand the security modelWhat the workload can reach, where credentials live, and which boundary checks what.Ship to your cloudControl plane and data plane on your Kubernetes, with Helm and Terraform.

The shape of the system

The control plane owns the agent: workflow interpreter, journal, model router and budgets. When a durable tool_call step runs code, the workflow engine calls ExecTool on the runtime-manager on a data-plane host, which runs the code inside a microVM whose PID 1 is the Lantern harness. In broker mode (LANTERN_EGRESS_MODE=broker, opt-in, Firecracker only) the VM has no network device; its requests leave over vsock through a host broker that checks the allowlist and adds the credential.

The agent loop runs outside; untrusted code runs inside a microVM Lantern architecture at a glance. On the left, the control plane runs the agent loop (the workflow interpreter), budgets and quotas, the replayable journal, and the model router; LLM calls leave from the model router to the LLM providers and never from the VM. In the middle, the data plane host runs the trusted runtime-manager and (in opt-in broker mode) a host egress broker. On the right, a microVM wall contains the Lantern harness as PID 1 and the untrusted agent workload. A tool call goes from the agent loop to the runtime-manager over ExecTool, across the wall to the harness, which runs it for the workload. This diagram shows the broker mode path (LANTERN_EGRESS_MODE=broker, opt-in, Firecracker only): the VM has no network device; a network request from the workload goes to the harness forwarder on 127.0.0.1:3128, then over vsock to the host broker, which checks the allowlist and injects the credential before calling the upstream API. In the default mode the allowlist is enforced in-guest. The agent loop runs outside; untrusted code runs inside a microVM Tool calls cross the wall through the runtime-manager. Network requests leave only through the host broker. Control plane (Go) Agent loop workflow interpreter, tool_call steps Budgets and quotas HTTP 402 when a hard cap is hit Journal journal_events, replayable Model router capability, not model name Data plane host (managed or your cloud) runtime-manager spawns microVMs, runs tool calls (ExecTool) Host egress broker allowlist check, credential injection (opt-in broker mode) microVM no network device (broker mode, opt-in) Harness (PID 1) tool runner, secrets socket, audit stream egress forwarder 127.0.0.1:3128 Agent workload user code, packages from the internet runs as an unprivileged uid runs the tool outbound request vsock credential added at the host LLM calls, never from the VM LLM providers Upstream APIs Control plane Trusted host In-VM harness Untrusted guest microVM wall Trust boundary
Agent loop outside, untrusted code inside. In broker mode, credentials are added at the host boundary, never inside the VM.

What the runtime gives you

Durable execution
A crash mid-step resumes from the journal. Completed steps are skipped and idempotency keys stop double side effects.
Isolation classes
runc, gVisor, Kata and Firecracker by declared class. Untrusted code is refused rather than downgraded when the hardened runtime is missing.
Token streaming
Session replies stream token by token over SSE, with no buffering between provider and client. Tool-using turns return one completed message.
Observability
Control-plane HTTP/gRPC and step spans carry tenant_id, run_id and step_id; the trace context propagates into the in-VM harness.
Budgets
Hard caps on cost, tokens and runs per day, per agent and tenant-wide; over the cap, the call returns HTTP 402 before the model is called. Workflow runs also stop mid-run at the per-run cap, and tool nodes respect per-tool limits.
Evaluations
Pin a baseline per branch and fail CI on regression with HTTP 422. Replay past failures before promoting a version.

New since 0.2.0

Knowledge base & handoff
Upload docs for cited answers, and hand a chat to a human with a Slack ping.
Examples
Runnable end-to-end examples, starting with a support desk.
Webhook triggers
A signed public URL per agent. GitHub, Sentry, PagerDuty or any HMAC sender starts a run; duplicates are deduplicated.
Accounts & sign-up
Gated sign-up, email verification, password reset, invite codes, captcha, data export and workspace deletion.
Budgets, enforced
Tokens per day, per-run caps inside workflows, per-tool limits, and fail-closed 503 when a hard-fail budget cannot be read.
Capability names
Every capability and optimize target, and the model it resolves to per provider.
Connector actions
Slack thread replies, GitHub PR comments, Sentry issues, Calendar events, PagerDuty, and a recorded test mode.
Disk snapshots
Snapshots capture the VM disk; restore and fork stage from it.
Real microVMs on a Mac
make lima-up, then make lima-e2e: Firecracker on KVM inside a Lima guest, on Apple Silicon M3+.
End-to-end tests
make test-e2e against a live stack, with a spend policy and make e2e-clean.

Control plane orchestrates. Your cloud executes.

The data-plane agent dials out to the control plane, so your VPC opens no inbound ports. Untrusted code and its data run in your cluster; self-host the control plane too and prompts, keys and run data never leave your infrastructure.

Your cloud runs the code; the control plane only orchestrates A request passes four control-plane steps: authenticate, budget and quota, mint per-VM identity, dispatch over service-token gRPC. It crosses a metadata-only trust boundary to the data plane, where the runtime scheduler picks a node, runtime-manager spawns the workload and the harness inside the microVM runs it. Step events, journal and a signed receipt come back up. Your cloud runs the code; the control plane only orchestrates User code executes in the data plane. The control plane decides and records by metadata. Control plane (managed SaaS) 1 Authenticate JWT or API key · RBAC tenant_id on every row, span and gRPC call · RLS 2 Budget and quota Forecast, then hard-fail limits: over budget is 402 per-tenant VM quota (402/429) 3 Mint identity Per-VM certificate at spawn Secrets are lantern.secret refs, resolved at run time 4 Dispatch gRPC to the data plane, service-token authenticated tenant_id in call metadata Also here: workflow engine · model router · memory · evals · marketplace · notifier Postgres, Redis, S3 hold metadata, costs and journals Trust boundary: token-authenticated, metadata only Down: specs, secret refs, tenant_id. Up: heartbeats, step events, audit. mTLS is the planned hardening; the shared service token is the current gate. Data plane: your VPC (EKS, GKE, AKS, laptop) runtime-scheduler :50055 · Go HA leader election · placement: warm pool, region, fair share, cost, health · picks the node for the spec runtime-manager :50054 · Rust isolation gate fails closed: Firecracker, Kata, gVisor, Wasm snapshot, restore, warm pools microVM (the glass) harness (Rust, PID 1) egress allowlist proxy (:3128) secrets via SO_PEERCRED reports bound to the VM's own run Comes back up: step events to the journal, then the run waterfall and traces, then a signed, verifiable receipt. Control plane Trusted host In-VM harness microVM wall Trust boundary
SDKsTypeScript · Python · Golantern CLIGo · CobraDashboardNext.js · :3001LLM providersAnthropic · OpenAIGatewayRust · :8443 TLSControl planeGo · :8080 REST · :50051 gRPCModel routerRust · :50053Data-plane agentGo · dials outWorkflow engineGo · :50052Runtime schedulerGo · :50055 · :8085Runtime managerRust · :50054 · per nodeview ›HarnessRust · PID 1view ›Untrusted codeyour agent's workloadInternetallowlisted hosts only

Swipe sideways to pan the diagram. Tap a component for details.

Click a component for what it does, its port, the trust boundary it enforces, and the code. Runtime manager and harness open into component views.

  • Trusted host code
  • Untrusted guest code
  • The microVM wall
  • A gate: what a caller must present

Open it full width, with every sequence diagram, in the architecture explorer.

Reference

REST API
Every endpoint on the control plane.
SDKs
TypeScript, Python and Go.
CLI
onboard, doctor, run, vm and more.