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 (the machine id 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.

If registration fails​

wakora --key against an unreachable server does not fail the install. The agent parks the key on disk as machine-bound ciphertext (/etc/wakora/pending-key) and exits cleanly, so the installer completes and the service comes up. The running service then retries registration forever with backoff, and wipes the pending key after the first success. Even a long control-plane outage ends with the host registering itself, with no one re-running anything.

Confirming it connected​

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

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

doctor verifies the whole path including authentication and data flow; the log shows it live.

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.