Agent configuration
The agent reads its configuration from environment variables. There is no config file and there are no command-line flags.
Settings
| Variable | Default | What it does |
|---|---|---|
WT_API_KEY | — | Your account API key (wt_…), from Account Settings → Security. Used only to register the machine the first time. Once the machine has its own credential this is never read again |
WT_APP_URL | http://localhost:3000 | Where the console lives. Used only for the one-off registration request. Not the broker |
WT_BROKER_URL | ws://localhost:8787/ws | The broker WebSocket endpoint — the connection the agent keeps open. Use wss:// for any real deployment; the ws:// default is for a broker running on your own machine |
WT_CREDENTIAL_PATH | Platform config directory (see Credential file) | Where the machine's credential is stored |
WT_METRICS_INTERVAL_MS | 2000 | How often to send a telemetry sample while a console is watching, in milliseconds. Values below 100 are raised to 100 |
The defaults point at a local development setup, so for a real machine you must
set at least WT_API_KEY, WT_APP_URL, and WT_BROKER_URL.
A worked example
export WT_API_KEY="wt_XXXXXXXXXXXXXXXXXXXXXXXX"
export WT_APP_URL="https://watchtower.page"
export WT_BROKER_URL="wss://broker.watchtower.page/ws"
export WT_CREDENTIAL_PATH="/var/lib/wt-agent/credential.json"
export WT_METRICS_INTERVAL_MS="5000"
wt-agent
Choosing a sample interval
WT_METRICS_INTERVAL_MS only applies while somebody is looking at the machine.
An unwatched machine sends nothing regardless of this value, so a fast interval
costs less than it appears to.
- 2000 (default) — smooth graphs, fine for a handful of machines.
- 5000–10000 — sensible for larger fleets or metered connections.
- Below 1000 — rarely useful. The console cannot usefully display it and the agent spends more time sampling than idling.
What the agent collects
Read from the real host today:
- Operating system name, platform, version, architecture
- CPU model, cores, speed, and utilisation
- Memory total and used
- Disks and volumes, with used and total bytes
- Boot time, from which uptime is derived
- Logon sessions — who is signed in, whether the session is remote, how long it has been open (Linux and Windows; not macOS)
Reported as empty rather than guessed:
- GPU details and GPU metrics
- WAN IP address
- Geolocation
- Network adapters
Those fields appear blank in the console. That is honest absence, not a failure — the collection code for them is not written yet. Nothing you configure will populate them.
Security notes
Use wss://, not ws://. The agent bundles its own root certificates, so
wss:// works without any TLS configuration on the host. The ws:// default
exists only for a broker running on your own machine — pointing it at a real
endpoint over ws:// would send telemetry and your machine's credential across
the network in the clear.
The API key is only needed once. After registration the agent uses the
credential it was issued. If you are configuring many machines, you can remove
WT_API_KEY from the environment after the first successful run — though leaving
it set does no harm, since it is not read again while a credential exists.
Restrict where a key can be used. IP allow and block rules on an API key are enforced at registration, so a stolen key cannot be used to add machines from somewhere you did not expect. See IP rules.
Development-only settings
The agent has several environment variables used for local development — running synthetic fleets, simulating churn, deliberately tripping security detectors. They are compiled out of release builds and are not documented here, because a release binary does not have them. If you set one, a release build logs a warning saying it was ignored.