Installation

Companion Hub runs as Docker containers managed by the desktop app or the bundled cihub CLI. Follow the path that matches your machine.

Install the prerequisites first

Hub does not bundle Docker or Ollama. Install both before you install Hub — it will not start without Docker, and AI features stay dark without Ollama.

Required. Docker Desktop, or a licensing-free engine on any platform.

1. Install Docker

Required for local AI models. Skip only if you’ll use a cloud provider.

2. Install Ollama

Using a Companion Core Server? Don’t install anything. Core hardware ships with Docker, Ollama, and Hub preinstalled and running — go straight to Core Server Quick Start to get it on your network and pair it with your account.

Typical first-time path: install Docker and Ollama → install the desktop app → launch it → create your local admin account → complete the Onboarding Wizard → optionally pair with your CI Account.

Prefer one page end to end? Your First Hour covers all of it in sequence.

Hardware requirements

Companion Hub uses containerization and shares Docker’s requirements:

	Minimum	Recommended
CPU	2 cores, 64-bit (x86_64/amd64 or arm64)	Modern multi-core
RAM	4 GB	8 GB+ (16 GB+ for local AI models)
Storage	20 GB free	20 GB+ SSD, more for media and models

Not all App Store apps support arm64. Hub automatically hides apps incompatible with your CPU architecture.

System Requirements is the full, authoritative list — including supported distributions, network requirements, and GPU options.

OS support

Platform	How to run Hub
macOS	Desktop app + Docker Desktop or Colima
Windows	Desktop app + Docker Desktop or Docker Engine in WSL2
Linux desktop	Desktop app (`.deb`/`.rpm`)
Linux server	Desktop package headless or `cihub` CLI

For Linux servers, Ubuntu 26.04 is our primary target — Companion appliances and CI-OS are built for it. Ubuntu 22.04 LTS is also actively supported. Other major distributions may work with manual Docker setup but are outside our primary test matrix.

If Docker is already installed, ensure the Compose plugin is available: docker compose version. Use the official Docker install script rather than outdated distro packages.

Option 1: Desktop app (recommended)

Confirm the prerequisites are in place

Both commands must succeed before you continue:


docker compose version


ollama list

If either fails, go back to Install Docker or Install Ollama.

If you skip this step, Hub’s setup wizard detects the missing engine and offers to install one for you.

Install Companion Hub

Download from ci.computer/hub or GitHub Releases , or use a package manager:


# 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 on ARM: the Scoop, winget, and Chocolatey packages are x64-only. Windows ARM64 builds are published, but you must download them directly from GitHub Releases — Companion.Hub_<version>_arm64-setup.exe or Companion.Hub_<version>_arm64_en-US.msi.


# Linux desktop (.deb or .rpm from GitHub Releases)
sudo dpkg -i Companion.Hub_*_amd64.deb    # Debian/Ubuntu amd64
# or
sudo rpm -i Companion.Hub-*-1.x86_64.rpm  # Fedora/RHEL x86_64

Launch the app

Open Companion Hub. The setup wizard runs on first launch and starts the Docker stack automatically.

The desktop app is built with Tauri 2 — a lightweight native wrapper (not Electron). It manages the Docker stack for you and adds a system tray, local network discovery, and cihub:// deep links for Companion account pairing.

The cihub CLI is bundled inside the desktop app. On first launch it is copied to ~/.local/bin (macOS/Linux) or %LOCALAPPDATA%\Companion Hub\bin (Windows). Open a new terminal after first launch to use cihub. See the CLI Reference.

Option 2: Linux server (headless)

For a VPS or home server without a GUI, install the same Linux package and start the stack without opening a window:


# Install Docker (if not present)
curl -fsSL https://get.docker.com | sh
 
# Install Companion Hub from GitHub Releases
sudo dpkg -i Companion.Hub_*_amd64.deb   # adjust for your architecture
 
# Start the stack headlessly (no display required)
companion-hub --detached

After the data directory is seeded, you can also use the bundled CLI:


# Direct path before first desktop launch, or after `cihub` is on PATH:
/usr/lib/companion-hub/resources/cihub wizard
cihub up --detached

Access the dashboard at http://<server-ip>:5002 (or http://localhost:5002 on the machine itself).

companion-hub --detached and cihub up --detached both target your packaged prod install. You do not need a separate CLI download.

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

Create your local admin account at the dashboard — see First Login & Setup
Complete the Onboarding Wizard
Optionally pair with your CI Account for remote access

For updating, see Updating Companion Hub.

Running the Hub CLI Reference Backup and Restore