Documentation · Configuration

Configuration

Warden combines human-editable configuration, encrypted secret storage and a migrated SQLite operational database inside one private instance directory.

Configuration directory

Warden defaults to ~/.config/warden/, or $XDG_CONFIG_HOME/warden/. Override it with --config or WARDEN_CONFIG_DIR.

~/.config/warden/
  warden.db
  config.json
  environment.json
  authentication.json
  ai.json
  users.json / roles.json
  secrets.json / master.key
  sites/

warden.db stores durable operational objects and normalized application state. JSON remains the editable/export-compatible configuration projection during migration; recoverable secrets remain encrypted with the instance master key.

Important bootstrap options

Option / variable	Purpose
`--host` / `--port` and `WARDEN_HOST` / `WARDEN_PORT`	HTTP bind address; defaults to `127.0.0.1:7332`. CLI flags override the environment, which overrides the default. Ports must be integers from 1 through 65535; invalid or empty values fail. Loopback is recommended behind a reverse proxy; `0.0.0.0` exposes Warden on all IPv4 interfaces.
`--listen` / `WARDEN_LISTEN`	Legacy single-address bootstrap; kept for compatibility and cannot be combined with `--host`/`--port`.
`--root` / `WARDEN_FILE_ROOT`	Explorer/Editor filesystem boundary; does not sandbox Terminal or Agent commands.
`--static` / `WARDEN_STATIC_DIR`	Optional override for the embedded Nift frontend.
`WARDEN_TRUST_PROXY`	Trust forwarded client/protocol headers only from a direct loopback reverse proxy.

SQLite behavior

Startup applies numbered migrations transactionally and rejects newer unknown schemas. Foreign keys, WAL, full synchronous writes and a busy timeout protect concurrent conversations, terminals, alert evaluation and operation jobs.

Frontend build

nift build

Authoritative frontend files live under content/ and templates/; public/ is generated and embedded into release binaries.

Backup and migration

Portable exports continue to use the validated compatibility configuration model, including password-encrypted export of secrets. For a complete machine-level backup, preserve the entire configuration directory so SQLite history, the master key, encrypted secrets and generated website fragments travel together.