First boot and the setup wizard
Walk the eleven-step, licence-first wizard, choose services from the hardware preflight, and unlock the product.
- Version: 0.4
- Role: admin_user
- Type: task
A freshly imported appliance has no accounts and serves nothing: every route answers 423 with
SETUP_REQUIRED until the wizard finishes. You walk eleven steps in a browser, create the local
administrator, accept the built-in trial or upload a licence, choose which entitled services this
machine should install, and finish. Completion unlocks the product and hands later changes to the
normal Settings and System Updates pages.
What do I need?
- Licence
- Any
- Role
admin_user
Prerequisites
- The appliance is powered on and you know its IP address, shown on the VM console.
- A browser on the same network can reach that address.
- The network the appliance boots on is trusted or isolated — the step that creates the administrator is unauthenticated by design, so whoever reaches the wizard first becomes the administrator.
- On a virtual machine: a snapshot has been taken with the wizard showing and unanswered. The wizard runs once, so that snapshot is the only way back to an unconfigured appliance.
- You have chosen a strong password of at least 8 characters for the local administrator.
- Optional: an outbound proxy URL, an LLM provider API key, directory bind details, and a paid licence file. Without a .lic file you must explicitly continue with the built-in trial.
The backend requires both Admin account and a License decision before completion. The licence decision may be the built-in trial, but the step cannot be skipped. Deployment mode is also mandatory in the browser. Steps marked optional carry a Skip button; Packages is optional because installing every entitled add-on later is valid.
Warning
Complete the wizard in one browser session. Reloading the page or closing the browser restarts the wizard at Welcome rather than returning you to the step you left, and the Admin account step then refuses to run again because an account already exists, which leaves the wizard with no way forward from the browser. Recovering from that is its own section below.
What each answer changes
The wizard separates commercial entitlement, machine suitability and operator choice. Those are different decisions: a licence may entitle a service, the hardware preflight may call it unsuitable here, and the operator may still defer it for another machine later.
| Step | What the answer changes | Where the same thing is changed afterwards |
|---|---|---|
| Admin account | Creates the one local superadmin. It is always local, so an unreachable domain controller cannot lock you out | More accounts are created on the users page — but this first one is created once and only here |
| License | Accepts the current trial or installs a signed .lic; its entitlements decide which optional services the Packages step may offer | Settings → License; a changed licence creates an add/remove service plan under Settings → System Updates |
| User identity | Nothing. The step is informational and records no choice | The attribution mechanism you choose, on its own page |
| Deployment mode | Decides which services the host starts when you select Finish: the gateway, the inspection listener, or both | Settings → System Updates, which queues the same host reconcile |
| Connectivity | Stages the outbound proxy as cold configuration. It is applied at Finish, not immediately, and is then read by the provider clients and the updater | The appliance's own environment on the host. There is no Settings page for it at 0.4 |
| Packages | Shows only optional services the live licence entitles, badges each from /etc/cid/hardware.json, and records Install now, Later or Skip | New entitlements and pending installs are reviewed under Settings → System Updates |
| LLM providers | Creates a provider credential attached to the default tenant group, so every user inherits it | Credentials, where a new credential is owned by whoever creates it. The wizard's own provider route closes at Finish |
| Active Directory | Writes directory configuration to the database and applies it immediately. Save configuration stays disabled until a test succeeds | Settings → Active Directory / LDAP |
| Connect Claude Code | Creates a Claude Code tenant group and issues a scoped key, shown once, embedded in the managed-settings file | API Keys, by issuing a new key. The one shown here cannot be displayed again |
| Finish | Marks setup complete, lifts the 423 lock, and asks the host to apply the staged configuration and start the services the mode needs | Nothing. This step happens once |
Two of those answers are worth settling before you open the browser. The deployment mode decides which containers start, so choosing Both on a machine sized for one shape is how an appliance first runs out of memory. And a provider credential added here is org-wide — every user inherits it — where one added later on the Credentials page belongs to whoever created it.
Walk the wizard
Open the appliance in a browser
Go to the appliance's address. An OVA answers on http://<appliance-ip>/; an appliance
installed from the ISO is HTTPS-only, so use https://<appliance-ip>/ and accept the one-time
certificate warning.
The appliance redirects to its setup page and shows Welcome to CID222 — first-boot setup with the ten steps listed down the left. First boot can take a few minutes while services start; a brief 502 during that window is normal.
/assets/screenshots/setup-wizard-welcome@0.4.pngRead the Welcome step and continue
Select Next.
The wizard advances to Admin account. Nothing is written yet.
Create the local break-glass administrator
Fill Admin username, Admin password (min 8 chars) and, optionally, Contact email (optional), then select Create admin & continue.
The account is created as a superadmin, the wizard signs the browser in as that account, and it shows Admin created — continue. This administrator is always local, so an unreachable domain controller can never lock you out of the appliance. The step cannot be repeated: once an account exists, the create-admin request is refused.
/assets/screenshots/setup-wizard-admin@0.4.pngAccept the trial or activate the licence
The wizard opens License immediately after the administrator. To use the built-in trial,
review its end date and select Next. To activate a paid package, select Export activation
request, send the file to your CID222 contact, and upload the returned .lic under Upload a
license file (.lic) before continuing.
This step is mandatory because its entitlements drive the later package list. It has no Skip button. The full connected and air-gapped exchange is in Licensing and activation.
/assets/screenshots/setup-wizard-license@0.4.pngRead the user-identity chain
Review the five attribution mechanisms listed under User identity, then select Next or Skip.
The step is informational and records no choice: it explains the order in which the appliance puts a name on AI traffic — extension sign-in, a web gateway's supplied username, the Active Directory user-ID agent, a manual IP or CIDR mapping, and the enrolled-device bridge. Each is configured after setup, on its own page.
/assets/screenshots/setup-wizard-identity@0.4.pngChoose the deployment mode
Select AI Gateway, Inline inspection (SWG/ICAP) or Both, then select Next.
The choice is recorded and decides which services the host starts when you finish. It has no Skip button, and you can change it afterwards under Settings → System Updates.
/assets/screenshots/setup-wizard-mode@0.4.pngDeclare the outbound proxy, if there is one
Leave Behind a corporate proxy? off and select Skip when the appliance reaches the internet directly or not at all. Otherwise turn it on, set HTTPS proxy to the proxy URL and No-proxy (comma-separated, optional) to the hosts that must bypass it, then select Next.
The values are staged on the appliance as cold configuration and take effect at Finish, not immediately. They are read by the components that make outbound connections — the LLM provider clients and the updater.
/assets/screenshots/setup-wizard-connectivity@0.4.pngChoose which entitled services to install
The Packages step lists optional compose services unlocked by the active trial or licence. Each row reports Suitable, Degraded, Unsuitable or Unknown from the hardware inventory and shows the requirement note from the signed service catalogue.
Choose Install now to add the service during host reconciliation, Later to put it in the pending-install queue, or Skip to leave it unselected. Mandatory core and guard services do not appear because they are not operator choices. An empty list means this package unlocks only the always-on core. Do not interpret Unknown as suitable: it means first boot did not produce a readable hardware report.
/assets/screenshots/setup-wizard-packages@0.4.pngAdd an LLM provider
Choose Connected (cloud) or Air-gapped (local) and pick a Provider. A cloud provider takes its API key; a local one takes Model endpoint (LAN URL), and its key field reads API key (optional). Select Test connection, then select Next. Select Skip to add the provider later under Credentials.
A successful test reports Reachable with the measured latency; a failure reports the provider's own error. On save the credential is attached to the default tenant group, so every user inherits it. Choosing Air-gapped (local) narrows the provider list to the ones that accept a LAN endpoint.
/assets/screenshots/setup-wizard-providers@0.4.pngConnect Active Directory
Leave Use Active Directory / LDAP off and select Skip to stay on local accounts. Otherwise turn it on, fill Directory type, Group membership mode, Server URL, Bind DN (service account), Bind password, Base DN, User filter and Admin group DN (optional), select Test connection, then Save configuration.
Save configuration stays disabled until a test succeeds, so you cannot finish setup with a directory that does not bind. After saving, an optional panel lets you map one AD group to a Role and a CID group and select Add mapping & import now, which reports how many users it imported. Directory settings are database state and apply immediately.
/assets/screenshots/setup-wizard-directory@0.4.pngGenerate the Claude Code managed settings
Enter Proxy hostname (base URL) and API hostname (gateway), select Generate managed settings, then Copy. Select Skip if you are not routing Claude Code through this appliance yet.
The appliance creates a Claude Code tenant group, issues a scoped key and renders the managed-settings JSON. The key is shown once and is embedded in that JSON. Leave the hostname fields empty only if the appliance already knows its own names; otherwise the file is generated with placeholders and warns you before you paste it.
/assets/screenshots/setup-wizard-claude-code@0.4.pngFinish setup
Select Finish setup.
The appliance marks setup complete, the 423 lock lifts, and the browser lands on the
dashboard. It also asks the host to apply what was staged: the host reconciler establishes the
installation identity, merges the Install now package choices into the active profile,
preserves Later choices in the pending queue, recreates the stack with the outbound-proxy
settings and entitled services, and health-gates the result. Expect a short interruption while
the stack is recreated.
/assets/screenshots/setup-wizard-finish@0.4.pngWhere the answers are kept
Setup writes only to the appliance's durable trees, so an update never discards it.
| What | Where | Written by |
|---|---|---|
| Step outcomes, completion, chosen mode | /var/lib/cid/setup/setup-state.json | the wizard |
| Outbound proxy settings | /var/lib/cid/setup/proxy.env | the wizard, applied by the host at Finish |
| The request to the host reconciler | /var/lib/cid/setup/apply-intent.json | the wizard at Finish |
| Installation identity | /etc/cid/installation.json | the host reconciler |
| Uploaded licence | /var/lib/cid/license/ | the licence upload |
| Hardware inventory used for suitability badges | /etc/cid/hardware.json | first boot |
| Package choices selected for now | /var/lib/cid/setup/packages.json | the wizard; host agent merges them into /etc/cid/profile.json |
| Deferred package queue | /var/lib/cid/pending-install.json | the wizard and host agent |
| Administrator, provider credential, directory configuration | the database | the wizard |
What cannot be undone
Warning
There is no supported way to re-run the wizard. Once setup is complete the bootstrap routes refuse further calls, and every setting the wizard collected is changed from its own Settings page instead — including the deployment mode, under Settings → System Updates.
| What | Why it is one-way | What to do instead |
|---|---|---|
| The wizard itself | POST /setup/complete marks the appliance configured, and the wizard route is gone from then on | Change each answer on its own Settings page |
| The first administrator | POST /setup/admin is refused once any account exists — during setup and after it | Create further accounts on the users page. Keep this one as the break-glass account |
| Creating a provider credential through the wizard | POST /setup/provider is refused once setup is complete, because it attaches a key to a group nobody owns | Add provider credentials on the Credentials page |
| The Claude Code key | It is returned once and never stored in a form that can be displayed again | Issue a new key on API Keys and re-distribute the managed settings |
| The installation identity | The licence is bound to it. Changing it invalidates a licence already issued | Nothing. Leave it alone, and back up /etc/cid so a rebuild keeps it |
Recover a half-finished wizard
The wizard keeps no browser session: reloading the page, closing the tab or losing the network restarts it at Welcome, and the Admin account step then refuses, because the account you created a moment ago already exists. Nothing is damaged — the appliance is still locked, the state file still records which steps completed — but the browser has no way forward.
Take the first of these that applies to you:
- You snapshotted the appliance before opening the wizard. Restore the snapshot and walk the wizard again. This is the reason to take that snapshot, and it is the only clean path.
- You did not, and the appliance is otherwise fresh. Reinstall. An import or an ISO run is cheaper than the alternative, and it is the only way back to a wizard.
- Neither is acceptable — the appliance already holds configuration you cannot lose. Setup can
be completed outside the browser: sign in as the administrator you created — the sign-in route
stays reachable while the appliance is locked — and complete setup through the API
(
POST /setup/complete). The423lock lifts, and every step you had not reached is then configured from its own Settings page. Ask your CID222 contact to run this with you; it is a recovery procedure, not a supported way to install.
Warning
Completing setup this way queues the same host reconcile the Finish button does, but a step you never submitted was never recorded — so an appliance completed this way comes up with no deployment mode chosen. Set it under Settings → System Updates afterwards, which queues the reconcile again.
Verify
- The browser lands on the dashboard and the sidebar renders. Product pages no longer answer
SETUP_REQUIRED. - Sign out and sign in again with the administrator you created. The sign-in succeeds against the local account.
- Open Settings → System Updates. The Deployment mode tile shows the mode you chose, and its tag reads that mode rather than applying on the host once the reconcile has finished.
- Open Settings → License. The page reports either the trial with its remaining days or the licence you uploaded, and shows a non-empty installation id.
If it fails
- The Connectivity step returns
500even with nothing filled in → Setup connectivity step returns 500 - The LLM providers step lists no providers → The providers step is empty
- A step is refused outright, with a message rather than a form error → A first-boot wizard step is refused
- Every request returns
402once the wizard completes → 402 after setup - The wizard finishes and the appliance asks for setup again → The setup wizard finishes and the appliance asks for setup again
- Answers do not survive a restart → Settings the appliance saves do not survive a restart
- The dashboard is unreachable over HTTPS after the reconcile → Certificate expired or nothing on 443
Next steps
- Licensing and activation — turn the 30-day trial into the package you bought, online or across an air gap.
- Naming, DNS and TLS — give the appliance names your clients can reach over trusted HTTPS, which the extension and Claude Code require.
- Hardening checklist — the settings that are the operator's job, not the image's.
Last updated on