LanternDocs

Identity & Secrets

Every headless agent spawn gets its own cryptographic identity, and secrets are vended to it at execution time over a mutually-authenticated channel — never baked into the image or the spec. The two are linked: the per-instance identity is what authenticates the secret-vending call.

In plain termsAgents need API keys to do their jobs — and API keys are exactly what an attacker wants. Lantern's approach: never put the real key anywhere the agent's code can casually find it. The agent config holds only a reference (a name, not a value); the actual key is handed over at the last possible second, expires quickly, and is delivered only to a process that can cryptographically prove it is the agent it claims to be. Each spawn also gets its own identity — like a single-use employee badge — so anything it does can be traced back to exactly that one run.

Per-instance Ed25519 identity

At spawn, the runtime issues the instance its own Ed25519 keypair. The identity is scoped to that single spawn — two runs of the same agent have different keys — and it is what the observability layer uses as agent_instance_id to keep traces from colliding.

Externally verifiable

The instance's public identity is verifiable at a well-known endpoint, so a downstream service can confirm it is talking to a genuine Lantern-issued instance:

GET /.well-known/lantern-agent-identity

Short-TTL secret vending

The workload never ships with secrets. Instead it requests them at runtime via the harness's secrets socket (/run/lantern/secrets.sock), which authenticates every connecting peer with SO_PEERCRED — kernel-attested uid and pid, not spoofable. The harness only vends to the workload uid injected by the manager as LANTERN_WORKLOAD_UID. Secrets have a 300-second TTL.

The control-plane resolves lantern.secret/... references through a relay endpoint protected by a pre-sharedX-Lantern-Runtime-Token header (SHA-256 compared, set via LANTERN_RUNTIME_SECRET_TOKEN; the endpoint returns 403 when unset). mTLS between the runtime-manager and control-plane is the planned stronger follow-up and is not yet implemented.

  • SO_PEERCRED peer auth. The kernel attests uid/pid on every socket connection; no credential the workload can forge.
  • Short TTL (300 s). A leaked value has a small blast radius — the workload re-requests as needed.
  • Pre-shared token on the relay. The manager authenticates to the control-plane relay via X-Lantern-Runtime-Token; fail-closed when unset.

The lantern.secret/... ref form

In the spec you reference a secret, you do not embed it. The runtime resolves the reference at execution time, so the raw value never appears in the image, logs, traces, or run state. From demo 02:

secrets:
  - env_name: USER_AGENT
    secret_uri: lantern.secret://__tenant__/key/scraper-user-agent
Note: The lantern.secret/... ref form is the same convention used across the platform — see Security. The runtime is where it is resolved, inside the isolation boundary, at the moment the workload needs it.
Important: Pair secret vending with the right isolation class. A workload that loads internet packages and also holds a secret should be untrusted with an egress allowlist, so a compromised dependency can't exfiltrate the vended value to an arbitrary host.

Broker mode: credentials never enter the VM

Vending still puts a short-lived value inside the VM, so a compromised workload can read it while it is valid. The opt-in broker mode (LANTERN_EGRESS_MODE=broker, Firecracker only) closes that gap for outbound API calls: the VM has no network device, and the host broker resolves the lantern.secret ref and injects the header on the way out. The workload never holds the value. See Egress and credentials.

What you get

  • Per-spawn Ed25519 identity, externally verifiable at /.well-known/lantern-agent-identity.
  • SO_PEERCRED peer-auth, short-TTL secret vending via harness Unix socket.
  • Reference-form secrets resolved inside the isolation boundary — raw values never touch the image, env, logs, or run state.