Running Companion Hub

Companion Hub can run in three ways depending on your setup: the desktop app (recommended for most users), the cihub CLI (best for servers and SSH), or an appliance-style detached stack managed through cihub.

Desktop app (macOS, Windows, Linux)

The Companion Hub desktop app bundles Docker orchestration, the web dashboard, and a native window with system tray controls.

Download: ci.computer/hub or GitHub Releases

Package managers also ship the same binary:


# macOS
brew install --cask companion-hub
 
# Windows (Scoop)
scoop bucket add companionintelligence https://github.com/companionintelligence/scoop-bucket
scoop install companion-hub
 
# npm (all platforms — installs the cihub CLI)
npm install -g ci-hub

The desktop app:

Opens the Hub dashboard in a native WebView window
Shows Hub health in the system tray (start/stop stack, open Portal)
Discovers other Hub instances on your LAN via mDNS
Remembers window size and position between sessions

On first launch, the app runs the setup wizard and starts the Docker stack automatically.

The desktop app manages Docker for you. Docker Desktop (macOS/Windows) or Docker Engine (Linux) must be installed and running.

Headless / server mode over SSH

On a Linux server or any machine where you want the appliance stack without the desktop window:


cihub up prod --detached

For a dev appliance environment instead of production:


cihub up dev --detached

The dashboard is then available at http://<server-ip>:5002 (or your configured port).

[GIF OF HEADLESS SSH STARTUP] — Screen recording of running cihub up prod --detached over SSH and opening the dashboard in a browser.

CLI (`cihub`)

For servers, automation, and power users, the cihub command-line tool provides full lifecycle control:


npm install -g ci-hub
cihub --help

Common first-run flow:


cihub wizard          # guided setup (Docker check, registration, start)
cihub up prod --detached
cihub status          # containers, tunnel URL, Tailscale IP, models

See the full CLI Reference for every command.

Which method should I use?

Scenario	Recommended
Personal computer (Mac/Windows/Linux desktop)	Desktop app
Linux server accessed over SSH	`cihub up prod --detached`
CI/CD, scripting, or fleet management	`cihub` CLI
Contributing to Hub development	`cihub up local`

Open this guide.

CLI Reference

Open this guide.

Installation

Open this guide.

Docker fundamentals