Private Networking¶

The agent creates and manages WireGuard mesh networks between your servers. Keys are generated locally and private keys never leave the machine.

Lifecycle¶

1. Key exchange¶

When a server is added to a private network, the backend sends desired state with phase: KEY_EXCHANGE.

Agent                              Backend
  │                                   │
  │◄── FetchDesiredState ────────────│
  │    phase=KEY_EXCHANGE             │
  │                                   │
  │    GenerateKeyPair()              │
  │    Store private key locally      │
  │                                   │
  │── ReportResourceState ──────────►│
  │   status=key_generated            │
  │   data={public_key: "xxx="}       │
  │                                   │

2. Network activation¶

Once all members have exchanged keys, the backend sends phase: ACTIVE with the full peer list.

Agent                              Backend
  │                                   │
  │◄── FetchDesiredState ────────────│
  │    phase=ACTIVE                   │
  │    peers=[{public_key, endpoint,  │
  │            allowed_ips}]          │
  │                                   │
  │    wg.Apply(config)               │
  │    WireGuard interface comes up   │
  │                                   │
  │── ReportResourceState ──────────►│
  │   status=active                   │
  │                                   │

3. Peer updates¶

When peers are added or removed, the agent detects the diff and re-applies the WireGuard configuration.

4. Network deletion¶

When a network is removed from desired state, the agent tears down the WireGuard interface and cleans up local keys.

WireGuard configuration¶

The agent configures WireGuard with the following parameters:

Parameter	Source	Example
Interface name	Desired state	`wg-10abc907`
Private key	Generated locally	Stored in bbolt
Address	Desired state	`10.1.0.2/32`
Listen port	Desired state	`51821`
Peers	Desired state	Public key, endpoint, allowed IPs
Persistent keepalive	Hardcoded	`25s`

Security¶

Private keys are generated on the machine and stored in the local bbolt database. They are never transmitted to the backend.
Public keys are reported to the backend and distributed to peers.
The agent requires CAP_NET_ADMIN and CAP_NET_RAW capabilities (granted via systemd).

Firewall¶

Ensure UDP port 51821 is open for inbound traffic from peer endpoints. The agent does not manage firewall rules automatically.