Configuration

Configuration

Every setting is an environment variable prefixed WARDEN_. Anything that applies to warden serve also has a command-line flag, which wins over the environment.

A .env file

warden reads a .env file from the directory the process starts in:

WARDEN_POOL_START=4000
WARDEN_POOL_END=4999
WARDEN_RESERVED=4200,4500-4510
WARDEN_TOKEN=a-long-random-string

The registry itself

Variable	Flag	Default	Meaning
WARDEN_HOST	--host	127.0.0.1	Interface it listens on
WARDEN_PORT	--port	7010	Port it listens on
WARDEN_DATABASE	--database	platform data directory	SQLite file holding everything

The database defaults to %LOCALAPPDATA%\warden\registry.db on Windows, ~/.local/share/warden/registry.db on Linux and ~/Library/Application Support/warden/registry.db on macOS. It is created on first use, along with any missing parent directories.

The pool

Variable	Flag	Default	Meaning
WARDEN_POOL_START	--pool 8000-8999	8000	First port that may be handed out
WARDEN_POOL_END	--pool 8000-8999	8999	Last port that may be handed out
WARDEN_RESERVED	--reserved	empty	Ports never handed out
WARDEN_PROBE	--no-probe	true	Test a port for an existing listener before handing it out

WARDEN_RESERVED takes single ports and ranges, separated by commas: 8080,8443,9000-9010.

The registry's own port is added to the reserved set automatically when it falls inside the pool. It lives on the same machine, so it could never be handed out anyway.

--no-probe turns off the bind test. Only worth it if something in your environment makes binding expensive; you lose the ability to notice ports that were taken outside the registry.

Access

Variable	Default	Meaning
WARDEN_TOKEN	empty	Require Authorization: Bearer <token> from people and tools
WARDEN_CLUSTER_TOKEN	empty	The secret wardens use with each other
WARDEN_ALLOW_KILL	false	Let the API stop processes

Empty means no check at all, which is fine while warden listens on loopback. Set WARDEN_TOKEN before binding to anything else.

WARDEN_ALLOW_KILL is off on purpose. A warden reachable from the network would otherwise let anyone holding the token end processes on that machine — a far bigger thing to hand out than a port number. warden kill on the command line is unaffected; it acts locally and never asks the API.

The fleet

Variable	Default	Meaning
WARDEN_NODE	the machine name	This warden's name in the fleet
WARDEN_UPSTREAM	empty	Hub to report to; empty means this one is a hub
WARDEN_ADVERTISE	from host and port	Address the hub should use to reach it
WARDEN_NODE_TTL	90	Seconds a node's entry stays fresh (10 to 86400)

The machine name is lowercased and stripped of anything a service name would not accept, so BUILD-01.office.lan becomes build-01.office.lan rather than refusing to start.

A node reports three times per WARDEN_NODE_TTL, never more often than every five seconds.

See Cluster for what these do together.

For clients, not the server

Variable	Flag	Default	Meaning
WARDEN_URL	--url, -u	http://127.0.0.1:7010	Which warden the CLI and the Python client talk to
WARDEN_TOKEN	--token	empty	Token to send with each request

WARDEN_URL is what points warden ls at a warden on another machine. Note that warden ports and warden kill ignore it: they read the local machine directly.

Limits worth knowing

Thing	Rule
Service name	lowercase letters, digits, . _ -, starting with a letter or digit, up to 64 characters
Kind	lowercase letters, digits and -, up to 32 characters
Project	same shape as a service name
ttl on a registration	1 second to 24 hours
WARDEN_NODE_TTL	10 seconds to 24 hours
Ports	1 to 65535, and pool_start may not exceed pool_end

A setting outside its range stops warden at startup with a message naming the setting, rather than being quietly clamped.