The credential file
When a machine registers, Watchtower issues it a credential of its own. The agent writes that credential to disk and uses it for every connection afterwards. Your API key is not stored on the machine.
Where it lives
By default, in the platform's config directory:
| Platform | Default path |
|---|---|
| Linux | $XDG_CONFIG_HOME/wt-agent/credential.json, usually ~/.config/wt-agent/credential.json |
| Windows | %APPDATA%\wt-agent\credential.json |
| macOS | ~/Library/Application Support/wt-agent/credential.json |
Override it with WT_CREDENTIAL_PATH.
The default is derived from the home directory of the user running the agent.
A service account has a different home directory, or none at all — so a service
must set WT_CREDENTIAL_PATH explicitly, or the credential lands somewhere
surprising. See Running as a service.
What is in it
The machine's assigned identity, its own secret, and which account it belongs to.
The file is written with owner-only permissions (0600 on Unix).
Treat it like a password. Anyone who can read it can report telemetry as that machine. It cannot be used to add new machines or read your other machines — it is scoped to this one — but it is still a credential.
If the file is on a system-wide path such as /var/lib/wt-agent/, make sure the
directory is owned by the service account and not readable by everyone. The
0600 default assumes a private home directory.
What happens if you delete it
The agent registers again on next start. That is a supported recovery path, not a problem — the machine is matched on its hostname and hardware identity, so it reclaims its existing record along with its history and labels, and is issued a fresh secret. The old secret stops working.
See Re-enrolling.
Backing it up
Do not. There is nothing to preserve — deleting it and letting the agent register again is faster and produces the same result. A restored copy of an old credential will not work if the machine has registered since, because registering rotates the secret.
Moving a machine
If you are moving a disk image or cloning a VM, delete the credential file in the image before cloning. If you do not, every clone starts with the same credential and they will fight over one identity — the console reports this as a duplicate machine security event.
See Security events.