Enrollment & Identity

Every TunTun agent has a persistent identity: an Ed25519 keypair generated at first enrollment. 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 tuntun enroll --control-url http://control:8080 --token TOKEN

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

After enrollment, the agent stores its identity and network state in ~/.local/state/tuntun (Linux), configurable with --state-dir or TUNTUN_STATE_DIR.

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):

tuntun 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 stored locally and enables management operations from the CLI.