> ## 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 — the gateway

> The server that holds your database credentials and decides what each agent may do with them.

`warden` is the product. Everything else exists to reach it, prove it, or ship it.

It is a single statically-configured server process. You give it a configuration file naming your database connections, the agents allowed to use them, and the policy each connection is governed by. It opens the database connections itself, so the credentials live in one place that no agent can reach.

## What it does with an operation

Every request from every agent travels one path, in this order:

```
authenticate → parse → classify → evaluate policy → deduplicate →
gate (human, if required) → rewrite → execute → classify outcome → mask → record
```

Two orderings are load-bearing:

* **Deduplication happens before the gate**, so a retry of something a human already approved replays instead of asking them again.
* **Rewriting happens before the gate**, so the human approves the statement that will actually run — scope conjunct, column list, masks and all — rather than the one the agent wrote.

## Running it

```bash theme={null}
warden serve --config /etc/warden/warden.yaml
```

At startup it prints the capability ladder for every connection, the state directory, and any warnings (a plaintext listener, a key in the config file, a recovered journal). A connection whose engine cannot meet its policy fails startup rather than serving traffic with a guarantee quietly missing.

> [!NOTE]
>
> The gateway is **stateful on disk but not on a database**: the audit chain, leases, and idempotency keys are append-only journals under `data_dir`. No second database is needed to run Warden, and nothing on the decision path talks to one.

## The CLI

`warden` is also the operator's command-line tool:

| Command | What it does |
| - | - |
| `warden serve` | Run the gateway |
| `warden debug attach` | Stream paused operations and resolve them from the terminal |
| `warden audit tail` | Follow the audit log |
| `warden audit verify` | Walk the hash chain and report the first break |
| `warden policy lint` | Check a policy, optionally against a live connection |
| `warden keygen` | Mint an agent key or an operator token |
| `warden version` | Print the version |

See [the CLI reference](https://warden.buildlab.in/operate/cli.md).

## The HTTP surface

One port serves three things, separated by credential:

* **Data plane** (agent keys): execute an operation, describe the schema the agent may see, confirm identity, and poll an async proposal. [Reference](https://warden.buildlab.in/api/data-plane.md).
* **Control plane** (operator tokens): pending approvals, debug sessions, leases, agents, audit, and a live event stream. [Reference](https://warden.buildlab.in/api/control-plane.md).
* **Operator view** (operator token): the browser interface at `/`. [More](https://warden.buildlab.in/operate/operator-view.md).

## Requirements

| | |
| - | - |
| Platforms | macOS and Linux, x86-64 and arm64 |
| Database | PostgreSQL 14+ for the reference connector |
| Runtime dependencies | None. A single binary, dynamically linked against the system C library |
| Build dependencies | Go 1.25+ and a C toolchain — it compiles PostgreSQL's real parser ([why](https://warden.buildlab.in/install/go-install.md)) |
| Disk | The state directory. Journals grow with traffic; the audit chain is the largest |
| Network | One listening port (9470 by default), plus outbound to your database |

## Install it

> [card] [Homebrew](https://warden.buildlab.in/install/homebrew.md)
>
> macOS and Linux, one command, with `warden-mcp` alongside.

> [card] [Container image](https://warden.buildlab.in/install/docker.md)
>
> Distroless, non-root, for a server deployment.

> [card] [go install](https://warden.buildlab.in/install/go-install.md)
>
> If you already have a Go toolchain and a C compiler.

> [card] [From source](https://warden.buildlab.in/install/source.md)
>
> The full clone, with fixtures and the certification suite. Needs access to the private repository.


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