Setup Wizard
The streamlined sequential setup tour served by the host agent at /setup — runtimes, models, mode, optional earn, and local credentials.
The setup wizard is the operator UI served by the host agent at /setup. It
turns a fresh install into a working local node in a strict sequential tour, and
keeps every important readiness signal visible at each stage. The desktop app
opens the same UI inside its window; CLI and script installers open it in a
browser.
The wizard never hides advanced state behind marketing copy. You are configuring real hardware, so the page shows identity, readiness, runtime, model profile, and enrollment exactly as the host agent reports them.
Setup Flow
The tour moves forward one step at a time. The local-only path is five steps. Choosing to earn adds a sixth step.
Runtimes
The wizard reads the runtimes the host agent detects on the machine and helps you install or select one. Nothing routes until a runtime is ready, so this is the first gate.
Models
Pick one or more models to install. Installs run through a serialized queue:
clicking install while another download is in flight enqueues the new job
rather than competing for bandwidth. A warm-start can prefetch a small
recommended starter model so you reach a working state quickly. To see the
canonical list of installable model profiles, query GET /v1/model-profiles.
Ready
A one-prompt smoke test runs the selected runtime and model end to end so you can confirm the node actually answers before going any further. If the smoke test fails, fix the runtime or model here rather than discovering it later.
Link to your account
Choose how the machine serves inference. Serve inference locally is the silent default: the machine serves only your own local clients and the wizard takes no further network action. Link to your account & earn is the recommended, explicit choice — it links the machine to your B3 account so it serves requests made with your own API keys (local serving stays on) and opens the "Bring it online" step.
Bring it online (only if you chose to link)
Name the machine, bring it online with a public route, and claim it with a device-flow 8-character code (or scan the QR) so it serves your account's API keys. Each stage reports its own progress so a stall is easy to locate.
Finish
The wizard hands you off to the node dashboard with the node working and, if you opted in, enrolled. Local-only operators finish here without ever touching a payout account, enrollment, or registration.
Serving inference locally requires no decision and no network enrollment — it is what you get if you do nothing at the Link step. Linking is never automatic. It only begins after you explicitly choose Link to your account & earn and complete the managed setup. Routability still depends on the gates described in Route readiness.
Linking a brand-new machine currently requires a B3IQ onboarding code — B3IQ
admits new hardware to the fleet rather than opening it to self-service. Set
it before you run the installer, or redeem it any time with
b3iq-host license redeem --code CODE. A machine that has already enrolled
before is unaffected, and re-enrolling it never requires a fresh code.
Model and runtime installs run one at a time. If you queue several models, they download in order rather than saturating the link, so a large pull will not stall the smaller starter model you need for the smoke test. Watch the queue on the Models step to see what is downloading now and what is waiting.
Wizard Principles
Expose real machine state
The wizard should show identity, readiness, runtime, endpoint, model profile, enrollment, support grants, and audit state.
Hide advanced state behind marketing copy
Operators are configuring real hardware. Trust comes from visible state, explicit actions, and clear recovery paths.
Setup Surfaces
The wizard is one of several surfaces the host agent serves. Each surface has a distinct purpose and its own credential.
| Surface | Purpose | Credential |
|---|---|---|
| Bootstrap setup URL | Initial claim or recovery entry into the wizard | Setup token |
| Command panel URL | Post-install playground, settings, keys, support, and audit | Owner session or local bootstrap token |
| Owner login | Normal local operator access | HttpOnly session cookie |
| Local API keys | Local inference clients | `b3iq_local_` scoped secret |
| Support grants | Temporary diagnostics access | `b3iq_support_` scoped secret |
| Managed enrollment | Signed node sync with control plane (Earn path only) | Node Ed25519 identity |
Host Menu And Advanced Panel
Beyond the linear tour, a host menu and advanced panel keep recovery and diagnostics one click away after setup:
- Readiness — the live route-readiness view for the node.
- Claim override — re-run or correct the device-flow claim if the original code expired or the node was claimed in the wrong place.
- Network status — current operating mode and managed sync state.
- Tunnel rotate / revoke — rotate or revoke the node's tunnel without re-running the whole wizard.
Revoking the tunnel takes the node off its public route — your account's API keys can no longer reach it — until you rotate a fresh credential and the node re-publishes a healthy heartbeat. Use revoke when you suspect the route is compromised; use rotate for a clean cycle.
Local Playground
Signed-in operators can use persisted local playground sessions to test runtime and model behavior after setup. API-key request logs stay separate and redacted by default.
Use the playground for operator smoke testing. Use b3iq_local_ API keys for
application clients.