Device Pairing

Pair your Companion Hub with Companion Portal to enable remote management, the Cloudflare Gateway, and the remote App Store.

Portal is optional. Hub works fully on your local network without cloud pairing.

Device registration screen

How pairing works

You create a Companion Account at portal.ci.computer (or app.ci.computer for organization setup)
In Portal, click Add Device and name your Hub — Portal generates a 6-character pairing code
On your Hub, paste the code in Settings → Companion Portal (or during the registration page on first setup)
Hub sends the code + device ID to Portal; Portal provisions DNS and a Cloudflare tunnel
Your Hub appears in the Portal dashboard

[GIF OF TAILSCALE SETUP] — Screen recording of the full pairing flow: Add Device in Portal → copy code → paste in Hub → confirmation.

Get a pairing code (Portal)

Log in to portal.ci.computer
Click Add Device
Enter a name for your Hub (e.g. “Home Server”)
Copy the 6-character pairing code shown

Codes are generated fresh each time you click Add Device. If a code expires or fails, generate a new one — you do not need to reset Hub first.

Enter the code (Hub)

From the dashboard:

Open Settings → Companion Portal
Paste the pairing code
Wait for confirmation — DNS and tunnel setup can take a few minutes

From the CLI:


cihub register    # prints device ID and Portal URL

During first-time setup: the registration page prompts for the code automatically when Hub detects it is unregistered.

Confirm success

Once paired:

Your device appears in the Portal dashboard
Cloudflare Gateway becomes available for exposing apps
Remote App Store installation is enabled
Hub shows a connected status in Settings

Managing devices in Portal

From the Portal dashboard you can:

View all paired Hubs and their online status
Enable or disable the Cloudflare Gateway per device
Expose individual apps with public URLs
Install apps remotely on a paired Hub
Add devices to Organizations for team access

Re-pairing and resetting registration

If you need to move Hub to a new Portal account, fix a broken tunnel, or start fresh:

From the Hub dashboard

Go to Settings → Companion Portal → Reset registration. This:

Clears local registration state
Deletes the Cloudflare tunnel token from disk
Returns Hub to the unregistered state so you can enter a new pairing code

From the CLI

Stop the stack, remove the tunnel token, and restart:


cihub down
rm -f <ROOT_FOLDER_HOST>/tunnel/token
cihub up prod --detached

Then generate a new pairing code in Portal and pair again.

Resetting registration removes your Cloudflare tunnel. Public URLs for exposed apps will stop working until you re-pair and re-expose them.

Adding multiple devices

Each physical Hub gets its own device ID and Portal entry. Create a separate Add Device flow in Portal for each machine — do not reuse pairing codes across devices.

Deep linking

The desktop app supports cihub:// deep links for pairing. If you start Add Device in Portal on the same machine as the desktop app, the pairing code can be passed automatically.

Troubleshooting

Issue	Fix
”Pairing code invalid”	Generate a fresh code in Portal (codes are single-use)
Pairing succeeds but no public URL	Wait 2–5 minutes for DNS propagation; check Portal device status
Hub shows degraded cloud status	Verify outbound internet; Hub validates with Portal periodically
Need to switch Portal accounts	Reset registration on Hub, then pair with the new account

Hub only needs outbound internet for pairing. No inbound ports must be opened on your router.