LanternDocs

Architecture explorer

Every box below is a real process and every arrow a real call. Select one to see what it does, the port it listens on, the trust boundary it enforces, and the source lines that back the claim. The runtime manager and the harness open into component views.

System map

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

Sequences

Step through each one, or press play. Scenario buttons switch to the failure and refusal paths.

A run, end to endFrom POST /v1/runs to a journaled result, including the budget gate, the optional model router, and what happens when the process dies mid-step.

1. POST /v1/runs

The SDK sends { agentName, input }. The route requires the runs:execute scope.

server/main.go:430handlers/rest.go:579

A tool call into a microVMThe workflow engine never runs tools itself: it asks the runtime-manager, which hands a JSON envelope to the harness inside the guest.

1. ExecTool

tool_name, args (Struct), run_id, step_id, vm_id, timeout, idempotency_key run_id:step_id:attempt, tenant_id.

engine/step_executor.go:405engine/step_executor.go:417v1/runtime.proto:469

Egress in broker modeThe workload's request leaves the VM over vsock; the host broker decides, dials, and adds the credential. The VM never holds it.Opt-in: LANTERN_EGRESS_MODE=broker · Firecracker only · ADR 0026

1. CONNECT api.github.com:443

The workload uses HTTPS_PROXY=http://127.0.0.1:3128 as usual.

src/egress_forwarder.rs:3 (broker branch)

Sandbox lifecycleSchedule, idle-suspend with transparent resume, explicit pause and resume, and copy-on-write forks.

1. POST /v1/runtime/schedule

AgentSpec: image, isolation, limits, egress, secrets, and optional idleTimeoutSecs.

server/main.go:787handlers/runtime.go:1730handlers/runtime.go:754

Sandbox states

The sandbox state machine. Select a state or a transition to see what triggers it, the call it makes, and what it guarantees.
scheduleplacedheartbeatsspawn failspause · idle · deletesnapshot + stop okstop faileddrainedresume · auto-resumerestore failsfork ×N (children)PENDINGSPAWNINGRUNNINGDRAININGPAUSEDFAILEDTERMINATED

Swipe sideways to pan. Tap a state or an arrow.