Skip to main content

Agent Locksmith

User-facing documentation for agent-locksmith — the Rust credential broker at the keystone of the Layer8 Proxy stack.

Agent-locksmith runs a daemon (locksmithd) that sits between your agents and the upstreams they call (LLM providers, tools, infra middleware). Agents authenticate to locksmith with a per-agent bearer token; locksmith validates the bearer against an ACL, injects the real upstream credential on the wire, and writes one audit row per request. The agent never sees the real key.

This documentation reflects the latest-shipped state and is not versioned by filename. Versioned material — PRD, technical spec — lives in the agents-stack/docs/{prd,spec}/ tree.

Audiences​

  • Developers running locksmithd standalone (evaluation, embedding in your own deployment system).
  • Operators running the locksmith CLI against a deployed daemon (locksmith agent register, locksmith audit query, etc.).
  • Agent developers wiring an agent (hermes, openclaw, custom) into a Layer8 Proxy deployment.

For the production Docker Compose bundle deployment story, see the Layer8 Proxy docs.

What it gives you​

  • Per-agent bearer + ACL. Each agent gets a distinct bearer token and an allowlist (or denylist) of tool/model names it may reach. A call to a name outside the allowlist gets 403 tool_not_allowed.
  • Credential injection. Locksmith reads the real upstream credential from its own environment (or a sealed store) and injects it on the wire. Agents carry only their locksmith bearer.
  • Catalog substrate. Registrations are discriminated by kind (model / tool / infra); agents discover models via /models and tools via /tools, ACL-filtered.
  • OAuth session management. Bootstrap and refresh OAuth sessions (codex, copilot, anthropic-oauth, gemini-cli, qwen-cli) with sealed token storage.
  • Audit. Every request and every admin write emits one audit row — the operator's single source of truth for who-called-what-when.

Where to go next​

  • Getting started — build the crate, mint an operator credential, register an agent, make a call.
  • Architecture — the user-level view of the daemon's runtime composition and request flow.
  • CLI reference — every locksmith subcommand and flag.