Skip to content

Pairing and approval

All hardware agents follow the same high-level enrollment flow. Cloud consoles (Nintendo/Xbox) skip pending approval.

sequenceDiagram
  participant Agent
  participant Server
  participant Admin
  Agent->>Server: hello (system_id, linux_users, ...)
  alt new device
    Server->>Agent: pairing_status pending
    Admin->>Server: approve device
    Server->>Agent: pairing_approved + token
  end
  Agent->>Server: register (HMAC signature)
  Server->>Agent: auth_result success
  Server->>Agent: policy sync commands

Linux

  1. Run install script or install binary manually with server_url and bootstrap token.
  2. Approve in Admin → Devices.
  3. Map /etc/passwd username to child account.

Or scan Settings → Agent pairing QR from a configured agent.

Android

Two paths:

  • In-app QR — APK installed; scan server QR; approve device
  • MDM QR — factory-reset 6-tap; Device Owner + auto-config (recommended for parental control)

See Android agent.

Windows

Add Device → Windows PC — run PowerShell/MSI installer as Administrator; approve pending device.

See Windows agent.

Registration token

Pairing QR codes and agent config include a registration_token field. This may be:

  • The server-wide REGISTRATION_TOKEN environment variable, when set, or
  • The household enrollment_token (multi-tenant installs; shown in Settings → Agent pairing)

Agents must send this value in hello. It is required again when an approved device reconnects with paired: false to receive pairing_approved.

If neither token is configured, open registration assigns new devices to the default household (suitable for local dev; use a token in production).

After approval

  1. Create or select child account
  2. Add device mapping with correct username/UID
  3. Click Verify on mapping
  4. Configure schedules and policies