> ## Documentation Index
> Fetch the complete documentation index at: https://warden.buildlab.in/llms.txt
> Use this file to discover all available pages before exploring further.

# warden.yaml

> The gateway's configuration: connections, agents, operators, state, TLS, and lease bounds.

One file describes a gateway. It is validated at startup, and anything questionable is reported as a warning rather than silently accepted.

```yaml theme={null}
version: 1
listen: 127.0.0.1:9470

# Keys the deterministic masking. Changing it changes every token.
masking_salt: a-long-random-value-kept-secret

# Audit chain, leases, and idempotency keys. Omit and they live in memory,
# lost on restart — fine for a demo, wrong for anything else.
data_dir: /var/lib/warden

leases:
  ttl: 15m
  max_ttl: 1h
  max_lifetime: 8h

connections:
  - name: shop
    engine: postgresql
    dsn: postgres://warden_gateway:secret@db.internal:5432/shop?sslmode=require
    policy: ./policies/shop.yaml
    approval:
      mode: blocking        # or async
      async_timeout: 1h
    options:
      schemas: shop,ops
      statement_timeout_ms: "5000"
      max_conns: "5"
      application_name: warden

agents:
  - id: agent:support
    connection: shop
    owner: platform-team
    key_hash: sha256:…       # or key: for development only
    scope:
      tenant_id: acme

operators:
  - name: alice@example.com
    role: owner
    token_hash: sha256:…     # or token: for development only
```

## Top level

**version** `integer` *required*

Must be `1`.

**listen** `string` (default: 127.0.0.1:9470)

Address to serve on. A non-loopback address without TLS is refused unless `allow_insecure_listen` is set — agent keys and operator tokens travel in every request.

**masking\_salt** `string` *required*

At least 16 characters. Keys deterministic masking, so the same value always produces the same token. Treat it as a secret: it is what stops a token being reversed by anyone who can guess inputs.

**data\_dir** `string`

Where the append-only journals live. Without it, state is in memory and a restart loses the audit chain — the gateway warns at startup.

**tls** `object`

`cert` and `key`, as PEM file paths. Both or neither.

**allow\_insecure\_listen** `boolean` (default: false)

Permit plaintext on a non-loopback address, for when TLS is terminated in front of Warden. Warns loudly.

**leases** `object`

`ttl`, `max_ttl`, `max_lifetime` as Go durations. A term longer than the ceiling above it is a configuration error rather than something silently clamped. See [leases](https://warden.buildlab.in/concepts/leases.md).

## connections

**connections\[].name** `string` *required*

Unique. Agents and policies refer to it.

**connections\[].engine** `string` *required*

`postgresql`, `mongodb` (also accepted as `mongo`), `neo4j`, or `memory`. See [engines](https://warden.buildlab.in/engines/postgresql.md).

**connections\[].dsn** `string` *required*

The database credential. It exists here and nowhere else — no agent ever sees it. Use a least-privilege role.

**connections\[].policy** `string` *required*

Path to the policy file, resolved relative to this file. See [policy](https://warden.buildlab.in/configure/policy.md).

**connections\[].approval** `object`

`mode` is `blocking` (default) or `async`; `async_timeout` bounds how long a proposal waits. See [approvals](https://warden.buildlab.in/configure/approvals.md).

**connections\[].options** `map`

Engine options. For PostgreSQL: `schemas` (which to introspect — without it the catalog becomes a map of the database), `statement_timeout_ms`, `max_conns`, `application_name`, and `lease_role` (the base role each lease's own database role joins — see [a role per lease](https://warden.buildlab.in/engines/postgresql.md#a-role-per-lease)). For MongoDB: `database` (required — refused when empty rather than inferred silently), `collections` (which to introspect), `statement_timeout_ms`, `max_pool_size`, `application_name` — see [MongoDB](https://warden.buildlab.in/engines/mongodb.md#setting-it-up). For Neo4j: `database` (default `neo4j`, the only database Community serves), `labels` (which to introspect), `statement_timeout_ms`, `max_conns`, `application_name` — see [Neo4j](https://warden.buildlab.in/engines/neo4j.md#setting-it-up).

**connections\[].seed** `object`

Starting data for the `memory` engine, ignored by every other engine. Makes a demo one command rather than a setup script.

## agents

**agents\[].id** `string` *required*

The identity that appears in every audit record, conventionally `agent:name`.

**agents\[].connection** `string` *required*

Which connection this agent may use. One each.

**agents\[].key\_hash** `string` *required*

The hash of the agent's key — `warden keygen` prints both halves. `key:` accepts a plaintext key for development, and the gateway warns, because the config file then *is* the credential.

**agents\[].scope** `map`

Scope values bound into every operation, such as `tenant_id: acme`. The policy decides which fields these bind to; this says what this agent's values are.

## operators

**operators\[].name** `string` *required*

Shown as the reviewer in audit records and in the agent's response. Use something that identifies a person.

**operators\[].role** `string` *required*

`owner`, `operator`, `reviewer`, or `read_only`. Roles carry capabilities: reading, reviewing (approve, reject, revoke a lease), and managing (freeze an agent, start a debug session).

**operators\[].token\_hash** `string` *required*

As with agents, `token:` is the development-only plaintext form.

## Checking it

```bash theme={null}
warden policy lint --policy ./policies/shop.yaml
warden serve --config ./warden.yaml
```

Startup prints the capability ladder per connection, the state directory, recovery notes from the journals, and every warning. A connection that cannot meet its policy stops the process.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.