Skip to main content
CID222 Docs

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.

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.

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.

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.

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

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

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
Administrator, provider credential, directory configurationthe databasethe 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

  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

Download PDF