Skip to main content

First start

Registration​

The first time the agent runs with a team key, it performs a one-time bootstrap:

wakora --key <YOUR_TEAM_KEY>

The agent sends its host identity (machine id, a hardware fingerprint, and the hostname as a display label) to the server over a pinned HTTPS request. The server returns a per-server key and a UUID (the server id). From this point on:

  • the per-server key, not the team key, authenticates the WebSocket,
  • the team key is discarded and never written to disk,
  • the UUID is the stable identity of this host, independent of its hostname.

The team key is a shared bootstrap credential for a whole team. It only ever mints per-server keys. A stolen host therefore yields only its own short-lived, revocable key, not the powerful team key.

Key rotation​

The per-server key rotates every 7 days while the agent is online, over the already authenticated connection, with a short overlap so there is never a lockout. If a host was offline past the rotation window, its current key stays valid until it reconnects, then rotates immediately.

Installing the service before the key​

If you set up the service before registering (common with configuration management), the agent does not crash-loop. It logs that it has no identity yet, idles, and checks for the identity file every 15 seconds. The moment wakora --key writes the identity, the agent picks it up and starts, no restart needed.

Confirming it connected​

The host should appear in your console within about a minute. On the host you can confirm directly:

tail -f /var/log/wakora/agent.log

You are looking for the heartbeat and, shortly after, lines like definitions received: N followed by service <name>: matched, K probe(s) activated as the server pushes the catalog and the agent activates the probes that match this host.

Where identity lives​

Identity is stored under the config directory:

  • Linux and macOS: /etc/wakora/identity
  • Windows: %ProgramData%\Wakora

The file holds the UUID and the per-server key as ciphertext, encrypted with a key bound to this machine. Copying it to another host does not work: it will not decrypt there. See Security model for the details.