Enrolling machines
Enrollment is how a machine joins your account. It happens by itself the first time the agent runs.
What happens
- The agent starts and finds no credential file.
- It sends its hostname and a hardware identifier to Watchtower, along with your API key.
- Watchtower creates a record for the machine, issues it a credential of its own, and returns it.
- The agent writes that credential to disk, owner-only.
- From then on the agent uses the credential. Your API key is not read again.
You do not approve anything. A machine with a valid key enrolls itself.
Why there is no approval step
Approval sounds safer than it is. It puts a manual gate in front of every rollout while doing nothing about the actual risk, which is a key in the wrong hands — somebody holding your key would simply wait for you to click approve.
What bounds that risk instead:
- IP rules constrain where a key can enroll from.
- Expiry constrains how long it can.
- Duplicate detection catches a credential being used by two machines at once.
- Every machine can be revoked individually.
The identifiers
Watchtower matches a machine on its hostname and hardware identifier together, never the hardware identifier alone.
That combination matters when you use VM templates. A template that was imaged with a hardware identifier baked in gives every clone the same one — matching on it alone would mean each new clone seizing the previous one's record. Requiring the hostname to match as well means the worst case is an extra record, not a machine losing its identity to a clone.
Enrolling many machines
There is no bulk import. Each machine enrolls by running the agent with a key set. For a fleet, that means your usual configuration management — an Ansible role, a Group Policy startup script, a golden image with the agent installed but not enrolled.
If you bake the agent into an image, make sure no credential file is in it. See Cloning and imaging.
What you get before any telemetry arrives
The record is created at enrollment with only the hostname and hardware identifier. Everything else — operating system, CPU, memory, disks — arrives with the first telemetry sample, moments later.
A machine that enrolled but never connected shows in the console with its name and nothing else. The Overview page counts these separately as not enrolled versus no metrics, so you can tell "never finished setting up" apart from "set up and now quiet".
If enrollment fails
The agent retries with a growing delay. It will not report telemetry until it succeeds — there is no degraded mode, because without a credential it has no identity to report under.
Common causes are covered in Machine not appearing.