System requirements
Companion Hub runs on Linux servers, macOS, Windows, and Linux desktops using Docker containers, with optional GPU acceleration for local AI models.
Minimum requirements
- CPU: 2 cores, 64-bit (x86_64/amd64 or arm64)
- RAM: 4 GB (8 GB recommended; 16 GB+ for local AI models)
- Storage: 20 GB free disk space (more for media and model weights)
- Architecture: amd64 or arm64
Platform support
| Platform | Role | Requirements |
|---|---|---|
| Linux server | Primary deployment target | Docker Engine + Compose plugin |
| macOS | Desktop app | Docker Desktop or Colima, macOS 11 or later |
| Windows | Desktop app | Docker Desktop or Docker Engine in WSL2, Windows 10 or later with WebView2 (x64 or ARM64) |
| Linux desktop | Desktop app or CLI | Docker Engine or Docker Desktop; the desktop app needs WebKitGTK 4.1 (x64 or ARM64) |
Docker backends
Hub does not require Docker Desktop. Docker Desktop needs a paid subscription for organizations with more than 250 employees or more than $10M in annual revenue, so every platform also has a licensing-free option:
| Platform | Docker Desktop | Licensing-free alternative |
|---|---|---|
| Windows | Supported | Docker Engine inside WSL2 |
| macOS | Supported | Colima (Docker Engine in a lightweight VM) |
| Linux | Supported | Docker Engine (already licensing-free) |
Hub can install the alternative for you — the desktop app’s Docker setup screen offers Auto-Install Docker Engine in WSL2 on Windows and Auto-Install Colima on macOS.
Pick a backend by platform and licensing:
flowchart LR
P{"Platform?"}
P -->|"Windows"| W{"Licensing-free?"}
P -->|"macOS"| M{"Licensing-free?"}
P -->|"Linux"| L["Docker Engine<br/>+ Compose plugin"]
W -->|"no"| WD["Docker Desktop<br/>WSL2 or Hyper-V backend"]
W -->|"yes"| WE["Docker Engine in WSL2<br/>Hub can install it"]
M -->|"no"| MD["Docker Desktop"]
M -->|"yes"| MC["Colima<br/>Hub can install it"]Windows
Either backend works, and WSL2 is usually involved either way: Docker Desktop defaults to its WSL2 backend, and Hub installs it that way. Docker Desktop’s Hyper-V backend (Windows Pro and Enterprise) is also supported.
- Docker Desktop — install it, start it, and Hub detects it automatically.
- Docker Engine in WSL2 — Hub provisions an Ubuntu WSL2 distro, installs the open-source Docker Engine inside it, exposes the daemon on
127.0.0.1:2375, and selects it through awsl-engineDocker context. No Docker Desktop license required.
If WSL has to be enabled during setup, restart Windows before reopening Hub.
Hub detects Docker by running docker.exe on the Windows side. It does not
detect a Docker CLI installed only inside a WSL distro with nothing exposed to
Windows — use Hub’s WSL2 installer, or expose the in-distro daemon through a
Windows Docker context yourself.
Linux server distributions
| Distribution | Status |
|---|---|
| Ubuntu 26.04 LTS | Primary target for Companion Core machines and base of the reference Companion OS ISO |
| Ubuntu 24.04 LTS | Supported for standalone Companion Hub installs |
| Ubuntu 22.04 LTS | Supported for standalone Companion Hub installs |
| Companion OS (CI-OS) | Preinstalled on Companion Core; available in Ubuntu 26.04.1 LTS (amd64/arm64) and CachyOS Plasma (x86_64) editions (beta) |
| Other Linux | Debian, Fedora, and RHEL packages (.deb / .rpm) available; other distros may work with Docker Engine |
The Hub backend always runs in Docker. Connect macOS and Windows machines through the desktop app rather than running them as bare-metal Linux container hosts.
Software requirements
- Docker — Docker Desktop or Docker Engine (see Docker backends for the licensing-free options on each platform). Install Docker is the step-by-step walkthrough.
- Docker Compose plugin, version 2.33 or newer — Verify with
docker compose version. On an older Compose, Hub refuses to start and names the version it found. Docker Engine 28 or newer is recommended: on an older Engine, Hub starts but warns that its containers may use the wrong network for internet traffic. - A local inference engine — Ollama is the default, and the engine vLLM and oMLX borrow for embeddings. Hub also supports vLLM on NVIDIA GPUs, oMLX on Apple silicon, and Lemonade on AMD GPUs. You need one for local AI models; cloud provider keys need none. See AI and inference
Optional:
- NVIDIA drivers + Container Toolkit — For CUDA GPU acceleration
- ROCm — For AMD GPU acceleration on Linux
Network requirements
- Outbound internet for pulling Docker images and App Store catalog
- Port 5002 on the host for the Hub dashboard and API
- Port 80/443 on the host for Traefik, the reverse proxy for exposed apps. Traefik uses them when they’re free and moves to 8880 and 8443 when they aren’t. The Linux desktop app always uses 8880 and 8443, because Linux doesn’t let a normal user open ports below 1024
- No inbound ports required for CI Account pairing or Tailscale
Not supported
- 32-bit systems
- Windows containers — Hub runs Linux containers only
- Bare-metal Windows or macOS as a server host — use the desktop app instead
Companion hardware
Companion Intelligence sells purpose-built hardware preloaded with Hub. See ci.computer for current devices and Core Server quick start for headless setup.
What you supply on each route:
| Requirement | Companion Core | Bring your own hardware |
|---|---|---|
| Hardware | Purpose-built, preloaded with Hub | 2-core 64-bit CPU (amd64 or arm64), 4 GB RAM (8 GB recommended, 16 GB+ for local AI models), 20 GB free disk |
| Operating system | CI-OS (Companion OS), Ubuntu-based | Linux server (Ubuntu 26.04, 24.04, or 22.04 LTS), or the desktop app on macOS 11 or later, Windows 10 or later, or Linux desktop |
| Docker | Preinstalled | Docker Engine + Compose plugin, Docker Desktop, or Colima |
| Ollama | Preinstalled | Install it for local AI models |
| Companion Hub | Preinstalled | Install the desktop app or the cihub CLI |
| First step | Power on, connect to your network, then pair with your CI Account | Install Docker and Ollama, then Hub, then run the setup wizard |