Headless Wi-Fi Setup Portal

Every CI-OS appliance — Companion Core Server or otherwise — can be set up without a keyboard, mouse, or monitor. Whenever it has no working network, it broadcasts its own Wi-Fi hotspot and serves a single captive-portal page, “Connect Companion Core,” so you can hand it your network credentials from any phone or laptop. Companion OS is in beta. This page covers what that portal actually is; the Core Server Quick Start is the shorter, task-oriented version of the same flow.

Which network is my phone on?

Your phone changes networks twice during setup, and the Core changes once. This is the step where people get lost, so it helps to know the sequence:

flowchart LR
    accTitle: Which network your phone and the Core are on during Wi-Fi setup: the setup hotspot, the handoff, then your own network
    subgraph S1["1. Join the hotspot"]
        P1["Phone joins<br/>Companion-Setup-XXXX"]
        C1["Core broadcasts the hotspot<br/>Portal at 192.168.99.1"]
    end
    subgraph S2["2. Submit and hand off"]
        P2["Page says Settings saved,<br/>then the phone drops off<br/>the hotspot: this is expected"]
        C2["Core stops the hotspot,<br/>joins your Wi-Fi, and checks<br/>the pairing code if you gave one"]
    end
    subgraph S3["3. Back on your network"]
        P3["Phone rejoins your home Wi-Fi<br/>or mobile data"]
        C3["Core is on your Wi-Fi<br/>Hub at http://CORE_IP:5002"]
    end
    P1 -->|"Configure Device"| P2
    P2 -->|"reconnect yourself"| P3
    C1 --> C2
    C2 -->|"about 2 minutes"| C3
    P3 -->|"open Hub, or sign in<br/>at hub.ci.computer"| C3
    C2 -.->|"can't join Wi-Fi"| X["Core records why and brings the<br/>hotspot back, which can take minutes"]

How it works

The whole exchange, from a network-less boot to the hotspot shutting itself down:

sequenceDiagram
    participant D as CI-OS appliance
    participant P as Your phone or laptop
    D->>D: No working connection (up to 45 s boot grace, then ~6 s): scan for networks, then hostapd brings up SSID Companion-Setup-XXXX
    P->>D: Join Companion-Setup-XXXX (WPA2, dnsmasq, 192.168.99.0/24)
    P->>D: Open http://192.168.99.1 (nginx serves the portal page)
    D-->>P: Pairing-code field (when needed) and the network list captured before the hotspot started
    P->>D: POST /api/configure with pairing code, SSID, and password
    D-->>P: 202 Settings saved (the reply goes out before the hotspot stops)
    D->>D: About 3 s later, stop the hotspot, join the network via NetworkManager, then check the pairing code with your CI Account
    D--xP: Your phone has left the hotspot, so any later failure is recorded on the Core and not shown on your phone

The states

The portal is one page whose look changes entirely based on what the backend reports — there’s no separate screen to navigate to.

First-boot form. The default state: pairing code, network selector, password field, Configure Device. The network list loads automatically.

Network list. The selector shows the networks the device saw before it started the hotspot, with the signal percentage beside each name. Choose Enter network manually… to type a hidden or out-of-range SSID. When the Hub is already paired, or isn’t running, the backend reports require_pairing: false and the page hides the pairing-code field.

Settings saved. When you submit over the hotspot, the Core replies before it shuts the hotspot down. The banner reads Settings saved. The setup hotspot will now close and the device will join “your network”. Reconnect this phone to your usual network to continue. It ends with a link to https://portal.ci.computer, and the button reads Setup in progress. About 20 seconds later the page opens that link. It isn’t your Hub, and it may not load. Ignore it: reconnect your phone to your normal network and open Hub at http://CORE_IP:5002, or check the device at hub.ci.computer .

If a wired connection with internet is already up when you submit, the Core pairs over Ethernet first and answers with the real result, Device paired or the exact reason it refused. A refusal leaves the hotspot up so you can try again.

Device configured successfully. The screenshot shows this banner, which the Core sends only when you reach the setup page over your own network rather than through the hotspot. It was captured against a stubbed backend. It isn’t what you see when you submit over the hotspot.

What errors you can and can’t see

Only problems the device finds before it stops the hotspot show up inline. When Ethernet is already up, that includes pairing problems. Every other problem happens after your phone has left the network.

See it end to end

The golden path — pairing code, network list, password, success — in one take. It was captured against a stubbed backend, and it ends on the Device configured successfully banner that a real Core doesn’t show over the hotspot:

If setup goes wrong

Start with the Something went wrong? table on the Core quick start. These are the recovery options behind it.

Restart the Core. After a restart, the hotspot starts again whenever the Core has no working network. Try this if the hotspot hasn’t returned several minutes after a wrong Wi-Fi password.

Use Ethernet instead. A working wired connection needs no hotspot. Plug the Core into your router before you power it on, find its address, and open http://YOUR_DEVICE_IP:5002. From there, pair and set up Hub as usual.

Fix Wi-Fi from a terminal on the Core. You need a monitor and keyboard, or a terminal over Ethernet. These commands ship with the setup package:

• sudo setup-wifi-recover stops the hotspot, unblocks the Wi-Fi radio, and reloads the Wi-Fi driver. Use it if Wi-Fi disappears after setup or the hotspot keeps cycling.
• sudo bash /usr/local/bin/setup-hotspot-reset.sh WIFI_INTERFACE disconnects the Wi-Fi interface, restarts NetworkManager and the setup services, then starts the hotspot once. Find your interface name with nmcli device.
• To remove a saved network that has the wrong password, run nmcli connection show, then sudo nmcli connection delete "NETWORK_NAME". These are standard NetworkManager commands.

Reset Hub, not the network. These reset Hub’s own data. They don’t change Wi-Fi or the operating system:

Both Settings resets leave the device in your CI Account until an owner or admin removes it there. If the account still has the device, Hub’s registration screen offers Restore my device: in your CI Account, open this computer’s device menu, choose Regenerate pairing code, and enter the code on the Hub.

Reinstall the operating system. Companion Core ships with a Companion OS recovery USB. Instructions for using it are not documented yet.