warden: Instructions file for Codex

Warden — agent guide

This file orients an autonomous agent (LLM, AI assistant, automation script) that needs to call services through Warden. Operators looking to set up Warden, mount providers, or onboard credentials should read the docs — start with Providers and the per-backend guides under docs/provider-backends/; this tree is for the consumer side.

Where to start

Warden runs its own MCP discovery server at /v1/sys/mcp. Point your MCP client at it (for Claude Code, claude mcp add), presenting your identity — a bearer JWT (Authorization: Bearer <jwt>) or an mTLS client certificate — and, for a sub-namespace, the X-Warden-Namespace header. It needs no role: it authorizes on the identity you present. It exposes two tools:

• list_roles — the roles your identity can assume. This is your menu. Each role carries:
  • description — operator-written prose: what the role is for;
  • provider — the type of provider it is used with (vault, aws, mcp, …);
  • skill — the skill://<name>/SKILL.md URI of the recipe for it;
  • url — where to call it, relative to Warden's address (prepend $WARDEN_ADDR).
• read_skill — given a role's skill URI, returns that SKILL.md: the markdown recipe for driving the role's provider. The structured output carries it whole as markdown.

A client that supports the MCP Skills extension can use skills/list, skills/get, and resources/read on the same skill:// URIs instead of read_skill.

For example:

{
  "name": "read-secret",
  "description": "read app secrets",
  "provider": "vault",
  "skill": "skill://vault/SKILL.md",
  "url": "/v1/vault/role/read-secret/gateway/"
}

A role listed without a url or a skill is not wired to a provider yet; the warnings in the same response say why. Don't build a URL for it — pick another role or ask the operator.

The agent loop