> ## 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.

# TLS and state

> Serving safely off loopback, and what Warden keeps on disk.

## TLS

Agent keys and operator tokens travel in the `Authorization` header of every request. On anything but loopback, plaintext hands them to the network.

```yaml theme={null}
listen: 0.0.0.0:9470
tls:
  cert: /etc/warden/tls/fullchain.pem
  key:  /etc/warden/tls/privkey.pem
```

Warden **refuses to start** with a non-loopback listener and no TLS, unless you say so explicitly:

```yaml theme={null}
listen: 0.0.0.0:9470
allow_insecure_listen: true   # only when something in front terminates TLS
```

That setting produces a startup warning every time. It is appropriate behind an ingress controller or a load balancer that terminates TLS, and wrong everywhere else.

> [!NOTE]
>
> The demo configurations are loopback-only by design, and a real deployment needs a real certificate. Warden does not obtain or renew certificates; point it at files your existing tooling manages.

## State on disk

With `data_dir` set, three append-only journals live there:

| File | What it holds | If it is lost |
| - | - | - |
| `audit.jsonl` | The hash-chained audit record of every decision | The history is gone. It is the artefact a post-incident review starts from |
| `leases.jsonl` | Agent credential lifecycles | Active leases are lost; agents are issued fresh ones |
| `idempotency-<connection>.jsonl` | Idempotency keys and their outcomes | A retry can no longer be recognised as a retry |

Writes are appended and flushed to disk, so a crash loses nothing that was acknowledged.

### What a restart does

* **A torn tail** — a record half-written when the power went — is discarded, and the gateway reports it as a startup note.
* **Corruption in the middle of a file, or a broken audit chain, refuses to start.** Appending new history on top of a broken chain would hide whatever broke it.
* **An operation in flight at the crash** has its idempotency key marked `outcome_unknown`: whether it took effect is genuinely unknown, and the agent is told to check the data and retry with a new key. Refusing a retry is recoverable; running a write twice is not.

### Running without it

Omit `data_dir` and everything is in memory. Startup warns. Fine for a demo or a test; for anything else it means no audit trail survives a restart.

### Backups

Copy the directory. The files are append-only, so a copy taken while running is a consistent prefix. `warden audit verify` (or `GET /api/v1/audit/verify`) walks the chain and reports the first break, which is also how you check a restored copy.

## Least privilege beneath Warden

Warden's own database credential should not be a superuser. The PostgreSQL fixture creates the role the project recommends: no superuser, no `BYPASSRLS`, and access only to the schemas it governs. It can't create roles. Per-lease roles are made by two helper functions it may call, which can only create a `NOLOGIN` lease role or drop one they made. A gateway compromise is then bounded by that grant, and governance is not the only thing standing between an agent and the rest of the database.


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