Setup Wizard

Cloud OS has two setup flows:

• First-run setup. It runs the first time you open a new node, before anyone has signed in. You create the owner account, name the machine, pick a mode and choose starter apps.
• Goal-based setup wizard. You can re-run it later from Settings to install a ready-made stack for a goal (family server, dev environment, and so on).

First-run setup

Open http://YOUR_SERVER_IP:8080. A fresh node first shows Press any key to ignite. Press a key or click to play the short boot animation, or press again to skip it. The setup then walks through these steps. The step bar at the top shows where you are, and Back works at every step.

Click Launch to apply everything. If it all works, the camera flies into the desktop.

Setup summary and retry

If any step fails (an app install hits the plan limit, the Control Center rejects the token, the proxy can’t be configured), you get a Setup summary (“Almost there.”) listing each step with its result:

• Retry re-runs just that step, for example one app install.
• Fix goes back to the step where the problem is. Launch there only redoes what failed; steps that already worked are not repeated.
• Continue to desktop leaves the rest for later. Everything can be finished in Settings, and apps can be installed from Launchpad.

Skip setup is always available and takes you straight to the desktop.

Finishing or skipping the first-run setup also marks the goal-based wizard as done, so it doesn’t pop up afterwards.

Goal-based setup wizard

Pick a goal and Quazzar pre-installs the matching app stack, primes Drive, and opens the right invite flow.

The landing screen also has a link, Already running self-hosted? Import →, which opens the Import Wizard.

Re-running

Open Settings → General → Re-run setup wizard. Confirm and the wizard opens at /welcome. Idempotent — already-installed apps stay; missing apps install. Useful when you want to switch a node’s purpose without a full reinstall.

How it works

The goal wizard renders client-side in pages/SetupWizardPage.tsx. On goal selection it calls POST /api/setup/run with the template id; the runner walks the template’s steps:

• install_app → goes through the existing app-installer chokepoint (so license gating, sandbox, and audit-log all behave normally).
• server_mode → flips the server-mode flag.
• invite_slots → pre-creates N empty invite tokens.
• hint_card → sets a dashboard banner the user sees on first visit.
• enable_audit → flips the audit toggle.

Per-step progress streams via the existing /api/events SSE channel. The run state persists in setup_runs so the user can leave the screen — when they come back, the progress picks up.

Templates

Templates ship as JSON under internal/setup/templates/ and are embedded into the binary via //go:embed. Each one declares an ordered list of steps. Future templates ship without code changes.

Plans

profiles.setup_completed (boolean, defaults false) gates the auto-popup for admins. It is set to true when the first-run setup finishes or is skipped, when the goal wizard is dismissed, and after its first successful run.

API

POST /api/auth/setup   { display_name, email, password }   → first-run owner account (only while no user exists)
POST /api/setup/node   { name, mode, starter_apps[] }     → name, mode and starter apps in one call; per-app errors in apps[]
GET  /api/setup/state                    → { completed, last_template, can_rerun }
GET  /api/setup/templates                → [{ id, name, description, steps:[{label}] }]
POST /api/setup/run     { template_id }  → 202 { run_id }
GET  /api/setup/runs/:id                 → run state + last progress
POST /api/setup/dismiss                  → 204

All session-authed; the run + reset endpoints additionally require admin role on the local OS (regular tenants don’t see another admin’s wizard).

Sign in with Quazzar Cloud

When a node has been linked to the Control Panel (a Control Center token under More options in the first-run setup, or Settings → Control Center), the sign-in screen shows a Sign in with Quazzar Cloud button alongside the other sign-in options (see Sign-in & Lock Screen).

How it works

1. Click Sign in with Quazzar Cloud on the OS login page.
2. Your browser is redirected to the Control Panel’s authorization screen, where you review the access request and click Approve.
3. The Control Panel issues a short-lived authorization code and redirects back to the OS.
4. The OS exchanges the code for a session and logs you in using your CP identity.

This uses a standard OAuth 2.0 Authorization Code flow — the OS never sees your CP password, and the authorization code is single-use and short-lived.

When it appears

The Sign in with Quazzar Cloud button is only shown if:

• The node was linked to a Control Panel during setup or via Settings → Control Center.
• The wizard_cp_endpoint setting is configured on the node.

If the button is not visible, link the node under Settings → Control Center.