Headless Agent Runtime

The runtime is where headless agents actually execute. You hand Lantern an agent.yaml — an image, an isolation class, resource limits, egress rules, and secret refs — and the platform schedules it, boots it, streams its logs and traces back, meters its cost, and tears it down. Every spawn runs in your own VPC, on your Kubernetes cluster.

The model in one picture

What makes it different

Kubernetes-default substrate

Every isolation class runs as a Kubernetes pod. There is no separate microVM fleet to provision for the common case — the data plane is already K8s in your VPC, and the runtime rides the same substrate. See Isolation classes and ADR 0009.

Isolation is a RuntimeClass tier

Isolation strength is selected by runtimeClassName, not by a separate orchestration backend. A reviewer reads isolation: untrusted in the spec and knows exactly what kernel boundary the workload runs behind. Untrusted and hostile classes fail closed — they refuse to run on a node that does not advertise the hardened RuntimeClass, never downgrading to a bare pod.

Durable execution

Work is event-sourced into a journal. If a node dies mid-run, the agent resumes from the last step_completed on another node — it does not re-spend tokens or re-fire side effects. Read how.

Per-instance identity

Each spawn is issued its own Ed25519 keypair. The instance authenticates secret-vending calls with it and is externally verifiable. Read how.

One trace per spawn

Every spawn emits a single OTel trace correlated by (tenant_id, run_id, step_id, agent_instance_id, trace_id), with GenAI semantic-convention attributes for token and cost telemetry. Read how.

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 — exactly-once under crash: journal, replay, idempotency keys
• Observability — one trace per spawn, OTel wiring, the metrics endpoint
• Identity & secrets — per-instance keys and short-TTL secret vending
• Verifiable receipts — signed, offline-verifiable proof of what ran