Skip to main content

A machine is not appearing

The machine never showed up in Machines at all. That means enrollment did not complete — work through these in order.

Read the agent's output​

The agent logs what it is doing. Start there; it usually names the problem outright. If it is running as a service, check the service log — journalctl -u wt-agent on systemd, the Windows event log or NSSM's log otherwise.

Is WT_API_KEY set and correct?​

Without a key and without an existing credential, the agent has no way to identify itself.

  • The key must start with wt_.
  • Copy it whole. A truncated paste is the single most common cause.
  • If you cannot find the key, you cannot recover it — keys are shown once. Create a new one.
  • Check it has not expired, under Account Settings → Security → API keys.

Is WT_APP_URL right?​

Enrollment goes to the console, not the broker. It must be the same origin you sign in at:

WT_APP_URL=https://watchtower.page

A default left in place (http://localhost:3000) means the agent is trying to enroll against the local machine, which will fail with a connection error.

Do IP rules on the key allow this machine?​

If the key has allow rules, the machine's public address must fall inside one. Enrollment is refused otherwise, and the refusal is recorded as a security event on the Overview page.

Check under Account Settings → Security → API keys → IP rules. A key with no rules is unrestricted, so this is only a candidate if you have added some.

Remember IPv6 rotates within a /64 — an allow rule naming a single IPv6 address will stop matching. See IP rules.

Can the machine reach Watchtower?​

curl -sS -o /dev/null -w '%{http_code}\n' https://watchtower.page

A proxy, a firewall, or a captive portal will stop enrollment. The agent needs outbound access only — nothing needs to reach in.

Is there a stale credential file?​

If a credential file exists, the agent uses it and never enrolls. If that credential was revoked, the agent will connect, be refused, and retry — without ever enrolling, because it believes it already has an identity.

Delete the credential file and restart the agent. It will enroll again.

Is it already there under a different name?​

Machines are matched on hostname and hardware identity. A renamed or rebuilt machine enrolls as a new record rather than reclaiming the old one — so look for a machine you do not recognise before concluding nothing arrived.

See Re-enrolling.

It appears, but with no details​

That is a different state: enrolled, but no telemetry. Fleet health counts it under no metrics. See No metrics.

Still stuck​

Email support@watchtower.page with the agent's log output and the name of the key you used. Do not include the key itself.