light-heart-labs--dreamserver/ods/docs/HEADLESS-SETUP.md

Headless Setup and QR Onboarding

ODS can be prepared as a local AI appliance: install it on hardware, ship or hand over the machine without a monitor, and let the recipient finish setup from a phone, laptop, tablet, or TV browser.

This page is the hardware-neutral map of the code that makes that possible. Strix Halo, DGX Spark, NUC-style mini PCs, repurposed desktops, and home lab servers should all follow the same high-level flow once their platform-specific installer path is working.

Current Status

The headless setup stack is implemented on main across the setup-card script, dashboard, dashboard API, host agent, mDNS announcer, AP-mode script, and Caddy proxy extensions.

Status is deployed in code and partially validated on the real hardware fleet for the LAN, mDNS, dashboard, magic-link, and Hermes access paths. The packaged appliance handoff still needs per-image validation because routers, Wi-Fi chipsets, AP-mode behavior, and client devices vary. In particular:

• Magic-link generation, QR rendering, first-run state, and dashboard flows have unit/integration coverage.
• Wi-Fi management is implemented for Linux hosts with NetworkManager / nmcli.
• AP mode is available but intentionally disabled by default because it takes over a wireless interface.
• mDNS plus ods-proxy provide the friendly LAN URLs. Fleet validation covers representative LAN behavior, but each packaged hardware image should still be validated on its target router/client environment.

User Journey

1. The device is pre-installed with ODS and given a friendly ODS_DEVICE_NAME such as ods, studio, or kitchen-ai.
2. The operator prints or ships a setup card with:
   • QR #1: a Wi-Fi QR code for the device setup AP, if AP mode is used;
   • QR #2: either the setup URL for first-run provisioning, or a permanent owner-card magic link that lands the new owner in ODS Talk.
3. The recipient scans the setup QR, opens the first-boot wizard, and joins the device to their home network when needed.
4. ODS generates an owner-card magic link and QR code for the first user.
5. After redemption, the user lands in ODS Talk, a mobile-first local chat portal backed by Hermes. Power users can still open the dashboard and the advanced Hermes surface for model, service, and diagnostics controls.

Main Components

Component	Code	Tests / Docs	Purpose
Setup card generator	scripts/generate-setup-card.py	tests/test_setup_card.py, SETUP-CARD.md	Produces printable cards with Wi-Fi + setup QR codes or Wi-Fi + owner ODS Talk QR codes.
First-run state	extensions/services/dashboard-api/routers/setup.py, extensions/services/dashboard/src/hooks/useFirstRun.js	tests/test_setup.py, App.test.jsx	Server-side setup sentinel that decides whether the wizard should appear.
Phone-first wizard	extensions/services/dashboard/src/pages/FirstBoot.jsx	FirstBoot.test.jsx	Guides first setup and shows the owner-card QR.
Magic-link auth and QR	extensions/services/dashboard-api/routers/magic_link.py, extensions/services/dashboard/src/pages/Invites.jsx	test_magic_link.py, Invites.test.jsx, HERMES-SSO.md	Creates revoke-only owner cards and temporary guest links, renders QR codes, redeems tokens, and issues signed session cookies.
Wi-Fi setup API	extensions/services/dashboard-api/routers/setup.py, bin/ods-host-agent.py	test_network_config.py, test_host_agent.py	Lets the dashboard ask the host agent to scan, connect, check status, and forget Wi-Fi profiles.
First-boot AP mode	scripts/ap-mode.sh, scripts/systemd/ods-ap-mode.service, scripts/ap-mode.conf.example	test-ap-mode.sh, AP-MODE.md	Optional setup access point for devices that are not yet on the user's network.
LAN discovery	bin/ods-mdns.py, scripts/systemd/ods-mdns.service	MDNS.md	Publishes <device>.local and service subdomains on the local network.
LAN reverse proxy	extensions/services/ods-proxy/Caddyfile, extensions/services/ods-proxy/compose.yaml	ODS-PROXY.md	Routes chat.<device>.local, dashboard.<device>.local, talk.<device>.local, auth.<device>.local, api.<device>.local, and hermes.<device>.local.
Agent surface	extensions/services/hermes-proxy/Caddyfile	HERMES.md, HERMES-SSO.md	Gates Hermes behind ODS magic-link session auth.

Operator Prep Checklist

For a hardware image or pre-installed unit:

1. Install ODS normally for the target platform.
2. Set a unique ODS_DEVICE_NAME in .env.
3. Set ODS_SESSION_SECRET so magic-link redemption can issue signed ods-session cookies.
4. Enable the LAN entry path:
   • ods-proxy for friendly HTTP routing;
   • ods-mdns for local .local discovery where supported;
   • hermes-proxy if the Hermes Agent should be LAN-reachable behind auth.
5. For AP-based out-of-box setup, write /etc/ods/ap-mode.conf, install the ods-ap-mode.service unit, and generate a setup card or factory owner card.
6. Validate the exact QR flow on the target image before shipping.

Validation Checklist

Use this checklist for each target hardware profile:

• Fresh install completes without a monitor attached.
• Setup card Wi-Fi QR joins the setup AP.
• Setup URL QR opens the first-boot wizard.
• Wi-Fi scan returns nearby networks on Linux NetworkManager hosts.
• Wi-Fi connect succeeds and the device remains reachable after network handoff.
• ods-proxy answers on port 80 from another device on the LAN.
• <device>.local, chat.<device>.local, dashboard.<device>.local, and auth.<device>.local resolve on at least one phone and one laptop.
• Owner-card magic link redeems repeatedly, sets the signed cookie, and redirects to Hermes until revoked.
• Temporary guest invite links still redeem, set the signed cookie, and redirect to their selected target.
• Hermes is reachable through hermes.<device>.local when enabled.
• Mobile voice is validated from HTTPS/Tailscale HTTPS when the packaged Hermes surface exposes microphone controls; plain HTTP is expected to show fallback readiness rather than promise mic access.
• Dashboard remains available for power users after first-run completion.

Known Limits

• AP mode is Linux-only and assumes NetworkManager, hostapd, dnsmasq, iptables, and a Wi-Fi interface capable of AP mode.
• AP mode is disabled by default because it is intentionally disruptive to a wireless interface.
• mDNS behavior varies by client OS, router, VPN, and enterprise network policy.
• The complete AP-mode appliance handoff still needs repeated end-to-end testing on each target packaged hardware image.
• Owner cards are physical credentials. They are not device-bound in v1 and should be revoked if a card is lost, photographed, or replaced.