Skip to main content
CID222 Docs

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.

StepWhat the answer changesWhere the same thing is changed afterwards
Admin accountCreates the one local superadmin. It is always local, so an unreachable domain controller cannot lock you outMore accounts are created on the users page — but this first one is created once and only here
LicenseAccepts the current trial or installs a signed .lic; its entitlements decide which optional services the Packages step may offerSettings → License; a changed licence creates an add/remove service plan under Settings → System Updates
User identityNothing. The step is informational and records no choiceThe attribution mechanism you choose, on its own page
Deployment modeDecides which services the host starts when you select Finish: the gateway, the inspection listener, or bothSettings → System Updates, which queues the same host reconcile
ConnectivityStages the outbound proxy as cold configuration. It is applied at Finish, not immediately, and is then read by the provider clients and the updaterThe appliance's own environment on the host. There is no Settings page for it at 0.4
PackagesShows only optional services the live licence entitles, badges each from /etc/cid/hardware.json, and records Install now, Later or SkipNew entitlements and pending installs are reviewed under Settings → System Updates
LLM providersCreates a provider credential attached to the default tenant group, so every user inherits itCredentials, where a new credential is owned by whoever creates it. The wizard's own provider route closes at Finish
Active DirectoryWrites directory configuration to the database and applies it immediately. Save configuration stays disabled until a test succeedsSettings → Active Directory / LDAP
Connect Claude CodeCreates a Claude Code tenant group and issues a scoped key, shown once, embedded in the managed-settings fileAPI Keys, by issuing a new key. The one shown here cannot be displayed again
FinishMarks setup complete, lifts the 423 lock, and asks the host to apply the staged configuration and start the services the mode needsNothing. 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.

Read 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.

Accept 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.

Read 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.

Choose 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.

Declare 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.

Choose 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.

Add 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.

Connect 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.

Generate 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.

Finish 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.

Where the answers are kept

Setup writes only to the appliance's durable trees, so an update never discards it.

WhatWhereWritten by
Step outcomes, completion, chosen mode/var/lib/cid/setup/setup-state.jsonthe wizard
Outbound proxy settings/var/lib/cid/setup/proxy.envthe wizard, applied by the host at Finish
The request to the host reconciler/var/lib/cid/setup/apply-intent.jsonthe wizard at Finish
Installation identity/etc/cid/installation.jsonthe host reconciler
Uploaded licence/var/lib/cid/license/the licence upload
Hardware inventory used for suitability badges/etc/cid/hardware.jsonfirst boot
Package choices selected for now/var/lib/cid/setup/packages.jsonthe wizard; host agent merges them into /etc/cid/profile.json
Deferred package queue/var/lib/cid/pending-install.jsonthe wizard and host agent
Administrator, provider credential, directory configurationthe databasethe 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.

WhatWhy it is one-wayWhat to do instead
The wizard itselfPOST /setup/complete marks the appliance configured, and the wizard route is gone from then onChange each answer on its own Settings page
The first administratorPOST /setup/admin is refused once any account exists — during setup and after itCreate further accounts on the users page. Keep this one as the break-glass account
Creating a provider credential through the wizardPOST /setup/provider is refused once setup is complete, because it attaches a key to a group nobody ownsAdd provider credentials on the Credentials page
The Claude Code keyIt is returned once and never stored in a form that can be displayed againIssue a new key on API Keys and re-distribute the managed settings
The installation identityThe licence is bound to it. Changing it invalidates a licence already issuedNothing. 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:

  1. 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.
  2. 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.
  3. 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). The 423 lock 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

  1. The browser lands on the dashboard and the sidebar renders. Product pages no longer answer SETUP_REQUIRED.
  2. Sign out and sign in again with the administrator you created. The sign-in succeeds against the local account.
  3. 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.
  4. 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

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

On this page