Installation

Companion Hub runs as Docker containers managed by either the desktop app or the cihub CLI. Choose the path that fits your machine.

Hardware requirements

Companion Hub uses containerization and shares Docker’s requirements:

Minimum

• 64-bit processor (x86_64 or arm64)
• 4 GB RAM
• 10 GB free disk space

Recommended

• Modern multi-core processor
• 8 GB RAM or more (16 GB+ if running local AI models)
• 20 GB+ free SSD space

See System Requirements for full details.

OS support

Ubuntu 22.04+ is recommended for Linux servers. Other major distributions work but may need manual Docker setup.

Option 1: Desktop app (recommended)

1. Install Docker Desktop  (macOS/Windows) or Docker Engine (Linux)
2. Download Companion Hub from ci.computer/hub 
3. Launch the app — the setup wizard handles the rest

Package managers:

brew install --cask companion-hub          # macOS
scoop install companion-hub                # Windows (after adding the CI bucket)

Option 2: CLI on a Linux server

# Install Docker (if not present)
curl -fsSL https://get.docker.com | sh
 
# Install the Hub CLI
npm install -g ci-hub
 
# Run guided setup
cihub wizard

Or use the install script:

curl -L https://raw.githubusercontent.com/companionintelligence/CI-Hub/dev/scripts/install.sh | bash

Option 3: Headless over SSH

If the desktop app is installed on a Linux machine without a display:

cihub up prod --detached

Access the dashboard at http://<server-ip>:5002.

VPS considerations

Running Hub on a VPS exposes services through a public IP. Prefer:

• A firewall blocking direct port access
• Tailscale for private access
• Cloudflare Gateway for public apps (not raw port forwarding)

After installation

1. Create your local admin account at the dashboard
2. Complete the Onboarding Wizard
3. Optionally pair with Companion Portal for remote access