Enrollment & Identity

Every Tunnet agent has a persistent identity: an Ed25519 keypair generated at first enrollment (or first Direct create/join). The public key (as a 64-character hex string) serves as the endpoint ID - a globally unique identifier for that machine.

Enrollment flow (Managed)

Enrollment registers a machine with the control plane. There are two paths.

Token enrollment uses a one-time token generated by an admin in the dashboard. The agent presents this token during enrollment and is immediately admitted to the network with an assigned IP.

Quick enrollment uses an organization slug. The agent registers itself and enters a "pending" state. An admin must approve the request in the dashboard. The agent polls the control plane and starts operating once approved.

# Token enrollment (immediate)
sudo tunnet enroll --control-url http://control:8080 --token TOKEN

# Quick enrollment (requires admin approval)
sudo tunnet enroll --control-url http://control:8080 --org my-company

After enrollment, the agent stores public state in state.json and seals the identity seed (and later login tokens) in state.enc. Public settings go in tunnet.toml. See Configuration and Encryption & Secrets.

Default state directory: ~/.local/state/tunnet (Linux user), /var/lib/tunnet (Linux service), or override with --state-dir / TUNNET_STATE_DIR.

Pass --no-encrypt-state (or TUNNET_NO_ENCRYPT_STATE=1) only for containers/CI when platform sealing is unavailable.

You cannot enroll into Managed mode while already joined to Direct networks (or the reverse). Wipe local state first with tunnet reset --yes.

Request signing

After enrollment, every request from the agent to the control plane is signed with the Ed25519 private key. The control plane verifies the signature against the registered public key, with a 60-second clock skew tolerance. This is the "endpoint authentication" layer that prevents impersonation.

CLI login

Separate from machine enrollment, users can authenticate from the CLI to the management API using OAuth device authorization (RFC 8628):

tunnet login --management-url http://localhost:3000

This opens a browser flow where the user enters a code displayed in the terminal. The resulting token is sealed in state.enc and enables management operations from the CLI.