Running Companion Hub

Companion Hub can run as the desktop app (recommended for personal computers), companion-hub --detached on Linux without a display, or via the cihub CLI for servers, automation, and power users.

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 (same desktop app):


# macOS
brew tap companionintelligence/homebrew-tap
brew trust companionintelligence/homebrew-tap   # first time only, on recent Homebrew
brew install --cask companion-hub
 
# Windows x64 (Scoop)
scoop bucket add companionintelligence https://github.com/companionintelligence/scoop-bucket
scoop install companion-hub

Windows ARM64 is published as a direct download only — see Installation.

Linux packages (.deb/.rpm from GitHub Releases) install the same app and bundled CLI.

The desktop app:

Opens the Hub dashboard in a native WebView window
Shows Hub health in the system tray — start/stop the stack, show or hide the Hub window, open Account Management at hub.ci.computer , view logs, or quit
Discovers other Hub instances on your LAN via mDNS
Remembers window size and position between sessions
Installs the bundled cihub CLI to your user PATH on first launch

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

The desktop app manages Docker for you, but a Docker engine must be installed and running: Docker Desktop, or a licensing-free alternative — Docker Engine in WSL2 on Windows, Colima on macOS, Docker Engine on Linux. Install Docker walks through each, and Docker backends compares them.

Headless / server mode (Linux)

On a Linux machine without a GUI — a VPS, home server, or SSH session — use the installed package directly:


companion-hub --detached

This seeds the prod data directory (if needed), starts the Docker stack in the background, and does not require DISPLAY or a window manager.

Once seeded, the cihub CLI works from any directory:


cihub status
cihub up --detached      # restart after a stop
cihub down

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

If cihub is not found, either open the desktop app once (it adds the CLI to ~/.local/bin) or invoke the bundled binary: /usr/lib/companion-hub/resources/cihub.

CLI (`cihub`)

The cihub command-line tool ships inside the desktop app and Linux packages. It provides full lifecycle control for servers, scripting, and contributors working from a source checkout.

Common first-run flow on a packaged install:


cihub wizard          # guided setup (Docker check, registration, start)
cihub up --detached   # start or restart the stack
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	`companion-hub --detached`
Restarting or scripting a packaged install	`cihub` CLI
Contributing to Hub development	`cihub up local` (from checkout)

CLI Reference Installation Docker fundamentals