Skip to main content

The host does not appear in the console

A host normally appears within a minute of wakora --key. When it does not, the cause is almost always one of the following, in this order.

1. Is the agent running?​

systemctl status wakora-agent
sudo wakora doctor

If the service is down or wakora doctor shows a FAIL, start there: wakora doctor, line by line. A host whose agent runs and reports data flow OK is in the console; if you still do not see it, read on.

2. Did registration happen?​

wakora doctor says identity ... registered with a UUID when it did. If it says not registered, wakora --key never succeeded here. The agent log (/var/log/wakora/agent.log) tells you why:

  • The key was refused (401). The key is mistyped, or it was revoked in Settings, Agent keys. Copy it again from the console: keys are long, and a truncated paste (the last characters missing) is the most common cause. Run sudo wakora --key <KEY> with the full key; a parked, wrong key is replaced by the new attempt.
  • The plan is full (403). The workspace has reached its host quota. The console's add-host dialog says the same and links to the plans; an operator raises the plan or removes a host, then the parked key registers by itself.
  • Too many registrations (429). A rollout to hundreds of hosts at once is rate limited per key. Nothing to do: each host keeps its key parked and retries with backoff until it gets through, which takes about an hour per thousand hosts. Hosts appear in waves.
  • The endpoint was unreachable. Same retry behaviour; see Connectivity if it persists.

3. Is it in another workspace?​

The team key decides which workspace a host joins. If several workspaces exist (an agency with client workspaces, or a personal and a company workspace), check the key came from the right one: Settings, Agent keys, shows every key with the number of hosts that used it and when it was last used. A key from workspace A used on a host meant for workspace B puts the host in A. Remove it there and register again with B's key.

4. Was this host removed before?​

A host removed in the console keeps its identity but the platform answers 410 to its key; wakora doctor reports auth WARN removed from the console. The agent idles by design and does not re-register on its own. To monitor the machine again:

sudo wakora --key <YOUR_TEAM_KEY>

It comes back as a new host with a fresh history.

5. Two machines, one identity​

A disk copied with the agent already registered (a template that was registered before it was turned into a template, a VM cloned from a running one, a backup restored next to the original) is one of five situations, and the agent and the platform tell them apart:

  • The copy got a new machine id (what most hypervisors do on clone). The identity file is sealed to the original machine and cannot be decrypted here, so the agent idles and wakora doctor says sealed to this machine and no longer decryptable. Run sudo wakora --key <YOUR_TEAM_KEY>: the old file is kept aside as identity.undecryptable-<time> and the copy registers as a new host. The original keeps its entry and its key untouched.
  • The copy kept the machine id (an image with a baked /etc/machine-id). Both machines come up under one host entry. The platform notices two live instances behind one identity within a couple of minutes and separates them by itself: the machine that connected first keeps the identity; the copy is registered as a new host of its own (subject to the plan's host limit) and told to switch over, while the original's key is rotated so the copy can never use it again. Nothing to run. Until the split happens, inventory of the copy may briefly land on the original's entry; the original's next snapshot corrects it. If the plan has no room for another host, the copy is refused instead: its identity is kept aside as identity.copy-<time>, doctor reads this host is a copy of server <uuid> with the reason, and wakora --key registers it once there is room.
  • Restored from a snapshot older than the last key rotation: the host presents a key the platform already replaced. The connection is refused with a retired-key reason, and doctor says the host was restored from a snapshot or backup older than its last key rotation. There is no automatic recovery on purpose: a leaked backup must not be able to take over an offline host. Re-register with wakora --key.
  • Moved to new hardware with a new machine id: the first case, same fix.
  • Copied before the agent was registered: nothing special, each machine registers as itself.

Local secrets stored on the original (wakora secret set) cannot be read on a copy with a different machine id either; a probe that needs one reports the secret as sealed on another machine, not as missing. Set them again on the copy.

Fix the image rather than living with the split: an image used for cloning should carry an empty /etc/machine-id and no /etc/wakora, so every machine born from it registers as itself on first boot.

sudo systemctl stop wakora-agent
sudo rm -rf /etc/wakora /var/lib/wakora
sudo truncate -s 0 /etc/machine-id

When the machine id is unique but the hostname collides with an existing host, the new machine gets its own entry (two hosts can share a name); only the combination of both identifiers is read as "the same box" (a reinstall). Even then the old entry is handed over only if its agent has been silent for a week: a reinstall of a box that was decommissioned takes its old place and history, while a second machine presenting the same machine id and name next to a live one is registered as a new host and leaves a "registration collision" event in the feed, so a template image with a baked machine id cannot steal a running host's identity.

6. A container host​

A Kubernetes DaemonSet pod or a containerised agent has a machine id of its own, different from the node's. Do not share /etc/wakora between a host install and a pod on the same node; pick one. See Kubernetes and Docker.