Agent runtime

Every Lantern run executes in one of two tiers — shared (inline executor inside the control-plane) or microVM (W12 Kubernetes/Firecracker/Kata stack) — declared in the agent version's manifest.isolation at publish time, not overridable by the caller.

The runtime, end to end

A run arrives from any entry point, passes the gates, executes in its tier, checkpoints to the journal, streams live, and ends with proof. Every cell is clickable.

Two tiers, one journal

The journal is the runtime's flight recorder: every step of every run is written down before it executes, in one place, regardless of which tier ran it. That one habit is what makes crash recovery, the dashboard waterfall, and signed receipts possible.

Concretely: both tiers write to the same journal_events table. The run waterfall, Ed25519 receipts, and crash-replay are tier-agnostic — there is no second event store.

How routing works

When POST /v1/runs arrives, the control-plane reads manifest.isolation from the resolved agent version and dispatches to either executeRunInline (shared) or scheduleAgentSpec (microVM). The caller supplies only the input; the tier comes from the manifest.

Unknown values in manifest.isolation are rejected at agent-version publish time with HTTP 400 — a typo fails at deploy, not at run time.

Shared tier

The shared tier is a goroutine inside the control-plane. Most runs execute here: loop agents, bridge replies, dashboard runs, cron-triggered runs, and sessions. It drives either the plain-LLM tool-use loop (for agents with no workflow JSONB) or the workflow interpreter (for agents with a graph saved in the visual editor). Crash-resume is handled by the recovery sweep — see Durable execution.

Entry points: POST /v1/runs, POST /v1/sessions/{id}/messages, cron scheduler, loop agent tick, bridge-triggered run.

MicroVM tier

The microVM tier is required for agents that run user-supplied code, exec arbitrary tools, or load untrusted packages. Declare it in the manifest:

manifest:
  isolation: microvm          # routes this agent version to the W12 stack
  image_digest: …@sha256:…
  limits: { vcpu: "250m", memory: "128Mi", timeout: "60s" }
  egress_rules: [{ host: "api.openai.com" }]
  idempotent: true

The in-guest tool runner gives the harness a typed tool registry:shell_exec, http_fetch, read_file, write_file and list_dir. File tools are confined to /workspace. Workflow-graph agents reach it through the engine's tool_call step.

Service-health sweep

A background loop TCP-probes peer services every 60 s (LANTERN_HEALTH_SWEEP_INTERVAL). After 3 consecutive failures it declares the peer DOWN and texts the owner's self-chat — once on transition, no storms. Read the current snapshot:

GET /v1/system/health    # JWT-authed

{
  "services": [
    {
      "name": "runtime-manager",
      "addr": "localhost:50054",
      "up": false,
      "consecutiveFailures": 5,
      "lastChecked": "2026-07-23T10:00:00Z"
    }
  ]
}

Operating it in production

System architecture

The technical view — how the control-plane, scheduler, runtime-manager, and in-VM harness collaborate across both tiers on the same journal_events substrate.

What makes it different

In this section

• Headless agent quickstart — write your first agent.yaml and run it end-to-end in ~15 minutes
• Isolation classes — the decision tree from trusted to hostile, and the fail-closed gate
• Durable execution — crash-resume: journal, replay, per-step retry, idempotency keys
• Token streaming — message_delta / message_completed / message_error contract and the SDK async iterator
• Sessions & memory — interactive multi-turn sessions on the shared tier, and LLM-distilled long-term memory
• Sandbox lifecycle — pause / resume / fork a microVM, streaming exec, with TS / Python / CLI examples
• Observability — OTel span attributes, the five lantern.run.* metrics, service-health sweep
• Identity & secrets — per-instance Ed25519 keys and short-TTL secret vending (microVM tier)
• Verifiable receipts — signed, offline-verifiable proof of what ran