Skip to main content

​
TLS

Agent keys and operator tokens travel in the Authorization header of every request. On anything but loopback, plaintext hands them to the network.
Warden refuses to start with a non-loopback listener and no TLS, unless you say so explicitly:
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.
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: 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.