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, never sitting in an environment variable on disk. 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 and hands the value to the workload — typically at a path like /run/lantern/secrets/<NAME> — so the raw value never appears in the image, the environment, 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.

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.