Documentation

Give any agent bounded, revocable authority.

Warden sits between agent runtimes and real tools. It verifies identity, capabilities, delegated credentials, policy and approvals before an external side effect can occur.

Quickstart

git clone https://github.com/ishaiktaher/warden.git
cd warden
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn control_plane.api:app --reload

Open the management console or the generated OpenAPI reference. Development defaults are intentionally rejected when CONTROL_PLANE_ENV=prod.

Security model

A failure at any stage prevents credential resolution and downstream network access. Capabilities bind agent, run, principal, scope, resources and expiry. Credential grants independently bind connection ownership, delegated agent, actions, methods, paths and expiry.

Guided product surfaces

The authenticated control-plane deployment includes /onboarding for application-to-first-call setup, /policies for visual versioned policy authoring and /connections for OAuth and managed-credential grants. These routes are intentionally absent from the read-only Vercel showcase. Start the full control plane locally or follow the production deployment guide to use them.

SDKs and CLI

Install the JavaScript package from npm, or inspect its source and examples.

npm install @vouchins/warden

import { WardenClient } from "@vouchins/warden";

const warden = new WardenClient({
  baseUrl: "https://warden.example.com",
  accessToken: process.env.WARDEN_RUNTIME_TOKEN,
});

const result = await warden.execute({
  capability_token: capability,
  runtime_proof: runtimeProof,
  task_id: taskId,
  connector_id: "github-issues",
  action: "issues.create",
  resource: "repo://acme/app",
  environment: "prod",
  grant_id: githubGrantId,
  parameters: { title: "Investigate production alert" },
});

The package supports TypeScript, ESM, CommonJS, maintained Node.js 22+ and modern browsers. It rejects plaintext remote control-plane URLs and generates a fresh idempotency nonce for each action unless one is supplied.

The dependency-free Python package and CLI live in sdk-python and are prepared for PyPI trusted publishing:

pip install vouchins-warden
export WARDEN_URL=https://warden.example.com
export WARDEN_ACCESS_TOKEN=...
warden health
warden integrations --query github

Register an agent

curl -X POST https://warden.example.com/owners/agents \
  -H "Authorization: Bearer $OWNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id":"tenant--issue-agent",
    "name":"Issue Agent",
    "owner":"tenant",
    "purpose":"Create bounded repository issues",
    "model_provider":"any-runtime",
    "agent_version":"1.0.0",
    "environment":"prod",
    "risk_tier":"medium",
    "allowed_tools":["github"],
    "allowed_actions":["issues.create"],
    "allowed_data_classifications":["internal"],
    "max_delegation_depth":0
  }'

An owner can submit a manifest but cannot approve it. Administrative review activates the identity and its immutable manifest version.

Vouchins blog reference agent

The repository includes a real vouchins-blog-publisher agent that turns a validated content brief into a blog draft and can publish only through Warden. Its capability is restricted to blog.publish_post on one cms://vouchins/blog/… resource. Run python -m scripts.run_blog_agent for the local end-to-end scenario, or read the integration guide to connect a credential-grant-backed CMS endpoint.

Connections and grants

Warden exposes a versioned catalog at GET /integrations and an evidence summary at GET /integrations/summary. Each entry is labeled as catalog-only, contract-tested or live-verified. Configure OAuth providers through POST /admin/oauth/providers/{provider_id}, then use the embedded <warden-connect> component or call POST /connect/{provider_id}/start. The callback validates single-use state, verifies the provider identity, stores tokens through the selected secrets provider and creates a bounded grant. Managed credentials support bearer, custom header, multi-header, Basic, query-key and AWS SigV4 injection. Custom OAuth URLs and arbitrary credential-injection templates prevent catalog lock-in.

<script src="https://warden.example.com/warden-connect.js"></script>
<warden-connect provider="github" principal-id="user-123"></warden-connect>

Execute an action

All REST, MCP and A2A ingress converges on the same mandatory gateway. The action request carries the capability, runtime proof, task, connector, resource and optional credential grant. Responses are redacted and every decision is appended to the hash-chained audit ledger.

Production checklist

• PostgreSQL with TLS, backups, restore rehearsal and tenant RLS.
• Redis with TLS for distributed rate limits and refresh locks.
• OIDC issuer with tenant, role and on-behalf-of claims.
• External KMS/HSM signing, secret custody and immutable audit anchoring.
• TLS ingress and an explicit connector egress allowlist/firewall.
• OTLP collector, SIEM alerts, SLOs and incident ownership.
• Apply reviewed migrations in staging before canary deployment.
• Run provider conformance, tenant-isolation, failure-injection and load tests.

Operations

/live is a shallow process probe. /ready performs constant-time database and production Redis checks. /health exposes only basic service status. Run the authenticated /audit/verify operation separately so probes never rescan a growing ledger. Use the global kill switch for incident containment and export audit evidence as NDJSON.

Continue with credential connections, provider portability, production operations, or the complete implementation guide.