Quickstart

You need a PostgreSQL database you can connect to, and about ten minutes.

Install

brew install abhishek-mallick/tap/warden
warden version

Other routes — container image, release archive — are in Install.

Make a credential for your agent, and one for yourself

warden keygen                  # an agent key
warden keygen --kind operator  # an operator token, for approving changes

Each prints the secret once, with the hash to paste into your configuration. Keep the secrets; the config file should carry only the hashes, so the file is not itself a credential.

Write warden.yaml

Point Warden at your database with a role that is not a superuser. This is the only place the database credential exists — no agent ever sees it.

warden.yaml

version: 1
listen: 127.0.0.1:9470
masking_salt: change-me-to-something-long-and-secret
data_dir: ./warden-state

connections:
  - name: shop
    engine: postgresql
    dsn: postgres://warden_gateway:secret@localhost:5432/yourdb?sslmode=require
    policy: ./policy.yaml
    options:
      schemas: public          # only the schemas an agent has business seeing

agents:
  - id: agent:support
    connection: shop
    owner: platform-team
    key_hash: sha256:…         # from warden keygen
    scope:
      tenant_id: acme          # this agent only ever sees this tenant's records

operators:
  - name: you@example.com
    role: owner
    token_hash: sha256:…       # from warden keygen --kind operator

Every field is explained in the configuration reference.

Write a policy

What the agent may touch, what needs a human, and what is masked. Replace the table names with yours.

policy.yaml

version: 1
connection: shop
mode: policy

require:
  scoping: enforced            # refuse to start if scoping cannot be enforced
  masking: enforced

approval:
  read: auto                   # reads run on their own
  write: pr_required           # changes wait for a human
  delete: pr_required
  ddl: denied
  unbounded_mutation: pr_required

resources:
  allow:
    - { kind: table, path: [public, orders] }
    - { kind: table, path: [public, customers], columns: [id, tenant_id, email] }

scope:
  enabled: true
  bind:
    orders.tenant_id: "{tenant_id}"
    customers.tenant_id: "{tenant_id}"

limits:
  max_rows: 100
  statement_timeout_ms: 5000
  approval_timeout_ms: 60000

masking:
  customers.email: tokenize

Check it before starting:

warden policy lint ./policy.yaml

Start the gateway

warden serve --config ./warden.yaml

The first thing it prints is the capability ladder — what is enforced on this connection, and by whom:

  connection shop (postgresql)
    record scoping               enforced     (governed relations)
    field masking                enforced     (masked inside the statement)
    statement timeout            native       (enforced by the server)
    dry run                      native       (transaction + rollback)
    fence                        native       (xmin, re-checked at commit)
  state: ./warden-state (audit chain, leases, idempotency keys)

native means PostgreSQL enforces it, enforced means Warden does, unavailable means nobody does yet — and Warden says so rather than implying otherwise. A connection that cannot meet its policy refuses to start. See the capability ladder.

Be the agent

AK=wk_live_…    # the agent key from step 2

curl -s -X POST http://127.0.0.1:9470/api/v1/gateway/execute \
  -H "Authorization: Bearer $AK" -H 'Content-Type: application/json' \
  -d '{"statement":"SELECT id, tenant_id, email FROM public.customers","reason":"list customers"}'

You asked for every customer. You get only the acme tenant’s, because Warden rewrote the query before PostgreSQL saw it — and the email comes back as a tok_… token. Try to defeat it with an alias or a function (SELECT upper(email) AS shout …): the value is masked inside the statement, so there is nothing to alias.

Try to change something

curl -s -X POST http://127.0.0.1:9470/api/v1/gateway/execute \
  -H "Authorization: Bearer $AK" -H 'Content-Type: application/json' \
  -d '{"statement":"UPDATE public.orders SET status = $1 WHERE id = $2",
       "params":["refunded","ord_1"],"reason":"customer asked for a refund",
       "idempotency_key":"demo-1"}'

This one waits. Policy sends changes to a human.

Be the human

Open http://127.0.0.1:9470/ and sign in with your operator token, or use the API:

OK=wc_live_…    # the operator token from step 2
curl -s -H "Authorization: Bearer $OK" http://127.0.0.1:9470/api/v1/pending

The pending change carries a preview: fidelity exact, the records it touches, and the before/after of each field — produced by running the change in a transaction and rolling it back. Approve it:

ID=op_…         # operation_id from the pending list
curl -s -X POST -H "Authorization: Bearer $OK" -H 'Content-Type: application/json' \
  -d '{"reason":"verified with the customer"}' \
  http://127.0.0.1:9470/api/v1/pending/$ID/approve

The agent’s call returns committed, and names who approved it. If the row changed while you were deciding, it returns stale instead and nothing is written — see previews and fences.

Check the record

curl -s -H "Authorization: Bearer $OK" http://127.0.0.1:9470/api/v1/audit/verify

Every step — the read, the refused attempt, the approval, the commit — is in a hash-chained log that reports whether it is intact.

Connect a real agent

warden-mcp was installed alongside the gateway. Point any MCP-speaking agent at it:

{
  "mcpServers": {
    "warden": {
      "command": "warden-mcp",
      "env": {
        "WARDEN_GATEWAY_URL": "http://127.0.0.1:9470",
        "WARDEN_AGENT_ID": "agent:support",
        "WARDEN_API_KEY": "wk_live_…"
      }
    }
  }
}

The agent gets four tools and no database credential. See the MCP server.

Policy reference

Everything a policy can say, and the traps worth knowing about.

Approvals

Blocking and async, and what an agent should do with each outcome.

Debug Mode

Step through your agent’s database traffic live.

The API

Four endpoints for agents, and the control plane for operators.

Serving on anything but loopback needs TLS — Warden refuses a non-loopback listener without it unless you say so explicitly. Before anything real, read TLS and state.

Start here

Offerings

Install

Configure

Operate

Connect a real agent

Next

Policy reference

Approvals

Debug Mode

The API

​Connect a real agent

​Next

Policy reference

Approvals

Debug Mode

The API

Connect a real agent

Next