Installation

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

Prerequisites

Hub does not bundle Docker or Ollama.

Docker is required, and it must be running. Hub cannot start without it, and it needs Docker Compose 2.33 or newer (docker compose version). Docker Engine 28 or newer is recommended. If Docker is missing, the desktop app shows a startup screen with an Install Docker button, so you can also install Hub first and let it set Docker up.
Ollama is optional. It runs AI models on your own machine. The onboarding wizard can install it for you, offer other engines, or take a cloud provider key instead.

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

1. Install Docker

Optional. Runs local AI models. Skip it if you’ll use a cloud provider or another engine.

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 → install the desktop app → launch it → pair the device with your CI Account → sign in with that account as the first admin → complete the Onboarding wizard. Pairing comes first because an unpaired Hub sends you to the device registration page before anything else.

For one end-to-end page, follow Your first hour.

The same path as a diagram — the two install options on this page meet at the dashboard:

flowchart LR
    A["Install Docker"] --> C{"Where does<br/>Hub run?"}
    C -->|"macOS, Windows,<br/>Linux desktop"| D["Option 1<br/>Desktop app"]
    C -->|"Linux server<br/>or VPS"| E["Option 2<br/>companion-hub --detached"]
    D --> F["Dashboard<br/>on port 5002"]
    E --> F
    F --> P["Pair with your<br/>CI Account"]
    P --> S["Sign in as the<br/>first admin"]
    S --> G["Onboarding wizard"]
    I["Companion Core Server<br/>Docker, Ollama, Hub preinstalled"] --> F

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. If an app doesn’t support your CPU architecture, Hub refuses the install and shows Wrong architecture, naming the architectures the app needs.

The onboarding wizard rates your machine before it offers local AI. A machine with under 16 GB of RAM and no supported GPU (under 8 GB on Apple silicon) is rated Insufficient: the wizard then says local models can’t run and shows only the cloud provider, recommended apps, and Companion Memory options. See Onboarding wizard.

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 (macOS 11 or later) + Docker Desktop or Colima
Windows	Desktop app (Windows 10 or later, with WebView2) + Docker Desktop or Docker Engine in WSL2
Linux desktop	Desktop app (`.deb`/`.rpm`, needs WebKitGTK 4.1)
Linux server	Desktop package headless or `cihub` CLI

For Linux servers, Companion Intelligence primarily targets Ubuntu LTS releases, including Ubuntu 26.04 and Ubuntu 22.04. Other major distributions may work with manual Docker setup but are outside the primary test matrix.

If Docker is already installed, check that the Compose plugin is version 2.33 or newer: docker compose version. Hub refuses to start on an older Compose and recommends Docker Engine 28 or newer. Use the official Docker install script rather than outdated distro packages.

Option 1: Desktop app (recommended)

Confirm Docker is in place

This command must succeed before you continue:


docker compose version

If it fails, go back to Install Docker. If you skip this step, the desktop app detects a missing engine on first launch and offers to install one for you.

Ollama is optional. To check whether it’s already installed, run ollama list, or see Install Ollama.

Install Companion Hub

Download the installer for your platform from ci.computer/download , or from the releases page , where every release publishes the same installers:

Platform	Installer	How to install
macOS (Apple silicon or Intel)	`.dmg`	Open the `.dmg` and drag Companion Hub to Applications
Windows, x64 or ARM64	`.exe` or `.msi`	Run the installer
Linux, Debian and Ubuntu, x64 or ARM64	`.deb`	`sudo apt install ./CompanionHub__amd64.deb` (`_arm64.deb` on ARM)
Linux, Fedora and RHEL, x64 or ARM64	`.rpm`	`sudo dnf install ./CompanionHub-.x86_64.rpm` (`.aarch64.rpm` on ARM)

Run the Linux commands from the folder you saved the package in. The * matches the space in the file name that the download page gives packages, and the dot in the name the releases page gives. apt install and dnf install resolve the package’s dependencies; dpkg -i and rpm -i don’t.

Windows on ARM: the download page lists x64 installers. The ARM64 builds (arm64-setup.exe and arm64_en-US.msi) are on the releases page. They are also in the release manifest: open https://dl.ci.computer/latest.json to read the current version, then open https://dl.ci.computer/<version>/manifest.json and use the windows-aarch64 entries.

If you use a package manager, each release is also published to a Homebrew tap and a Scoop bucket:


# macOS (Homebrew)
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

Update them with brew upgrade --cask companion-hub or scoop update companion-hub. Uninstalling through a package manager doesn’t remove your data; see Uninstalling.

Launch the app

Open Companion Hub. A startup screen titled Checking CI Hub, then Starting CI Hub, shows Docker and each Hub service (database, message queue, Hub backend, router) as they come up. The first start after an install or an update downloads container images and can take a few minutes. When the Hub answers, the window opens the dashboard automatically.

If the screen stops on a problem, it names the problem and offers a matching button — Install Docker, Start Hub, Restart Hub, Try again, or View logs. See Running Companion Hub.

Next, pair the device with your CI Account.

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 CI Account pairing.

The cihub CLI is bundled inside the desktop app. On first launch it is copied to ~/.local/bin (macOS/Linux, or ~/bin if that is already on your PATH) or %LOCALAPPDATA%\Companion Hub\bin (Windows), and that folder is added to your shell profile or user PATH. Open a new terminal after first launch to use cihub. The .deb package also links it to /usr/bin/cihub at install time, so it works before you ever open the app. 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
 
# Find the latest version and download the .deb (x86_64; use linux/deb/arm and _arm64 on ARM)
VERSION=$(curl -fsSL https://dl.ci.computer/latest.json | grep -o '"version":"[^"]*"' | cut -d'"' -f4)
curl -fLo companion-hub.deb "https://dl.ci.computer/${VERSION}/linux/deb/x64/Companion%20Hub_${VERSION#v}_amd64.deb"
sudo apt install ./companion-hub.deb
 
# Start the stack headlessly (no display required)
companion-hub --detached

companion-hub --detached creates the prod data directory if it doesn’t exist, starts the stack in the background, and exits. On an RPM-based system, download the .rpm from the URLs listed in https://dl.ci.computer/<version>/manifest.json and install it with sudo dnf install.

Then finish setup from the terminal, on the Hub machine:


cihub status                            # containers, tunnel, VPN, models
cihub register --code <pairing-code>    # pair with your CI Account
cihub claim --email you@example.com     # give the Hub its first operator without a browser

Generate the six-character pairing code in your CI Account first — see Device pairing. cihub register needs the Hub running, and cihub claim needs the Hub registered.

You can also finish setup in a browser instead: open http://<server-ip>:5002 (or http://localhost:5002 on the machine itself) and follow First login and setup.

If cihub isn’t found after an RPM install, run it from /usr/lib/companion-hub/resources/cihub until the desktop app has run once. The .deb package links cihub to /usr/bin/cihub for you.

companion-hub --detached and cihub up --detached both target your packaged prod install. You do not need a separate CLI download. cihub up on a machine that has never run Hub prompts for a database password; set POSTGRES_PASSWORD in the environment to skip the prompt, or run companion-hub --detached first, which generates the secrets itself.

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

Pair the device with your CI Account — required before Hub lets you continue, and required for remote access, the marketplace, and Organizations
Sign in with your CI Account as the first admin — see First login and setup
Complete the Onboarding wizard

For updating, see Updating Companion Hub.

Running Companion Hub CLI reference Backup and restore