Managed Client Concepts

Managed client is Nanami’s CLI-first onboarding path for macOS/Linux without desktop GUI apps.

Canonical API Contract

Login:

• POST /api/v1/auth/login

Managed client lifecycle:

• POST /api/v1/client/devices (create/enroll)
• POST /api/v1/client/devices/:id/config (refresh config)
• POST /api/v1/client/devices/:id/heartbeat (update last_seen)
• GET /api/v1/nodes/:id (status source of truth)

Enrollment Flow

1. nanami login authenticates and stores session tokens in ~/.nanami/config.json.
2. nanami up --node-name ... --network ... creates a managed node and receives a server-generated WG payload.
3. CLI writes deterministic local config:
   • ~/.nanami/wireguard/nanami0.conf
4. nanami up --apply attempts wg-quick up.
5. CLI posts heartbeat so server-side status remains current.
6. nanami status reads server truth and local state summary.

Local Secret Storage

• ~/.nanami directory mode: 0700
• ~/.nanami/config.json mode: 0600
• ~/.nanami/wireguard/*.conf mode: 0600

Private keys are generated and stored locally by CLI. Only public key rotation is sent to control-plane.

Config Generation vs Apply

• --print-config prints a sanitized config (PrivateKey redacted).
• Config generation always writes to local path even when apply fails.
• --apply requires wg-quick and OS-level permissions.

If apply cannot proceed:

• CLI prints exact install hint (wireguard-tools) and fallback instructions.
• No silent failure; errors include command output and next-step remediation.

Error Contract

Managed-client endpoints follow stable response classes:

• 401: { "error": { "code": "unauthorized", "message": "..." } }
• 403: { "error": { "code": "forbidden", "message": "..." } }
• 404: { "error": { "code": "not_found", "message": "..." } }
• 400: { "error": { "code": "validation_error", "message": "..." } }
• 422 validation schema:
  • { "error": { "code": "VALIDATION_ERROR", "message": "Validation failed", "fields": [...] } }