First boot and the setup wizard
Walk the ten-step first-boot wizard, understand what each step writes and what Skip defers, 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 ten steps in a browser, create the local
administrator, tell the appliance what it is for, and finish — which unlocks the product and hands
the rest of the configuration to the normal Settings 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.
- You have chosen a strong password of at least 8 characters for the local administrator.
- Optional, and each deferrable: an outbound proxy URL, an LLM provider API key, directory bind details, and the licence file for this appliance.
Only the Admin account step blocks completion. Steps the sidebar marks optional carry a Skip button, which records the step as skipped and moves on; the setting is then configured later from its own Settings page, and nothing about the appliance is left broken.
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.
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.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.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.pngActivate the licence, or stay on the trial
Select Export activation request, send the downloaded file to your CID222 contact, and
upload the .lic they return under Upload a license file (.lic). Select Skip to run on
the built-in trial instead.
The panel above the field states the current licence state and shows this appliance's installation id. The full procedure, including the air-gapped transfer, is Licensing and activation.
/assets/screenshots/setup-wizard-license@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, recreates the stack with the outbound-proxy settings and the services
the chosen mode needs, 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 |
| Administrator, provider credential, directory configuration | the database | the wizard |
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.
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
- Every request returns
402once the wizard completes → 402 after setup - 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