Managed Client Concepts

Managed clients are Nanami's CLI and Desktop device applications. Both use the same deployment-scoped authentication, enrollment, stable-device identity, and observed runtime truth. The Electron Desktop client is implemented for the supported source-build platforms; public Desktop installers and distribution remain part of the separate release pipeline.

Canonical API Contract

Authentication supports native email/password with MFA when enabled, configured SSO providers, and browser/device approval as a fallback. Available methods are discovered from the selected Cloud or Self-hosted deployment; no provider is assumed by default.

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. Select Nanami Cloud or a validated Self-hosted deployment.
2. Authenticate with an enabled method. MFA completion is required before the client becomes authenticated.
3. The local daemon reuses the stable, non-secret physical-device identity for that deployment and idempotently enrolls or updates the managed device.
4. Choose a visible network and request connection with nanami connect or the Desktop Connection screen.
5. The daemon reconciles WireGuard state. Authentication, daemon health, and driver readiness do not imply a connected tunnel.
6. nanami status and Desktop show connected state only after observed local runtime truth confirms it. Presence and metadata update automatically.

Local Secret Storage

Passwords are never persisted. Session credentials and private key material stay outside renderer storage and use the daemon-owned secure-storage contract for the host platform. The stable physical-device identity is non-secret and must not be treated as a credential. Support output redacts session material, private keys, raw tunnel configuration, and local IPC credentials.

Config Generation vs Apply

• WireGuard is the production transport; GRE remains unavailable and fails closed.
• Runtime apply requires the platform service/driver and OS permissions.
• Config and runtime internals remain daemon/support concerns rather than the ordinary user workflow.

If apply cannot proceed:

• CLI and Desktop show short platform-appropriate remediation.
• Primary UI and ordinary CLI output do not expose raw command output, socket paths, stack traces, tokens, or tunnel configuration.

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": [...] } }