Your First Hour with Companion Hub

From nothing installed to Hub running with a local app and AI behind it.

You’ll need: admin rights, a stable internet connection, and enough free disk — see below.

Disk space

Plan in layers, not one lump sum:

Layer	Typical size	Notes
Hub stack	~2 GB	Docker images for the Hub itself
Companion Memory	~8 GB	Images plus initial database/object-store data; grows with your library — see Companion Memory
Models	varies	Embedding model ~1 GB+; each chat model often 2 GB+
Other apps	varies	Leave headroom — photo libraries, media, and backups add up fast

A practical minimum for Hub + Memory + one small model is ~20 GB free; more is better if you will install extra apps or large models. Details: System Requirements.

Inference

Hub apps need two different capabilities from an LLM backend:

Chat / decoding — answering questions, agents, summarization
Embeddings — vector search; Companion Memory requires embeddings

Backend	Chat	Embeddings	Setup
Ollama (recommended to start)	yes	yes	Install on the host; Hub connects at port `11434`
vLLM	yes	no	Point Hub at an existing server URL + API key (decoding only)

If you use vLLM for chat, you still need Ollama (or another embedding-capable backend) for Companion Memory. Full detail: AI & Inference.

Companion Core Server? Docker, Ollama, and Hub are preinstalled — skip to Create your account, or follow the Core Server Quick Start.

Platform-specific traps and troubleshooting live on the dedicated pages — Install Docker, Install Ollama.

Install Docker

Hub runs every app as a Docker container. Nothing else works without Docker.

Check for Docker


docker --version

If that prints a version, skip to Install Ollama.

Install

Docker Desktop works on macOS, Windows, and Linux. Licensing-free alternatives exist (Colima, Docker Engine in WSL2, Docker Engine on Linux) — Hub’s setup wizard can install those for you later if you prefer to skip manual install.

macOS

Download Docker Desktop , install for your chip, launch it, and wait until the menu-bar whale icon is idle.

Linux — Desktop

Requires a desktop session and KVM (ls -l /dev/kvm). Install Docker Desktop for Linux or use Linux — Engine on headless machines.

Linux — Engine

For servers and VPS:


curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Log out and back in after adding yourself to the docker group.

Verify


docker run --rm hello-world
docker compose version

Docker Desktop must stay running — if you quit it, Hub stops too. Enable start-at-login in Docker settings.

Install Ollama

Required for embeddings (Memory) and the simplest path for local chat. Skip only if you already run Ollama, or you will configure vLLM and a separate embedding backend in Hub settings.

Install

macOS / Windows

Download from ollama.com/download and run the installer.

Pull a chat model and an embedding model


ollama pull llama3.2
ollama pull nomic-embed-text

Let containers reach Ollama (Linux)

On macOS and Windows with Docker Desktop, containers usually reach Ollama at host.docker.internal:11434 without extra config.

On Linux, bind Ollama to all interfaces:


sudo systemctl edit ollama


[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"


sudo systemctl restart ollama

Verify from a container


docker run --rm curlimages/curl -s http://host.docker.internal:11434/api/tags

JSON listing your models means Hub apps can reach Ollama. See Install Ollama if this fails.

Using vLLM instead of Ollama for chat? After Hub is running, open Settings → AI, select vLLM, and point Hub at your server:

Endpoint: http://host.docker.internal:8000 (Hub runs in Docker — not localhost)
API key: must match --api-key when you started vLLM (e.g. vllm-local)

Click Re-check after vLLM is serving a model. vLLM handles chat only — keep Ollama on port 11434 for Companion Memory embeddings. Details: AI & Inference — vLLM.

Install Companion Hub

Install

macOS


brew tap companionintelligence/homebrew-tap
brew install --cask companion-hub

Or download from ci.computer/hub .

Windows


scoop bucket add companionintelligence https://github.com/companionintelligence/scoop-bucket
scoop install companion-hub

Or download from ci.computer/hub .

Linux desktop

.deb or .rpm from GitHub Releases :


sudo dpkg -i Companion.Hub_*_amd64.deb

Linux server

Install the same package, then:


companion-hub --detached

Dashboard: http://<server-ip>:5002.

Launch and confirm

Open Companion Hub (or browse to http://localhost:5002). First launch pulls Hub stack images.

The desktop app adds the cihub CLI to your PATH — open a new terminal before using it.


cihub status

More install paths: Installation.

Create your admin account

Register locally

Go to http://localhost:5002 (or http://<server-ip>:5002). Create an admin password.

Registration screen

This account is local — not your CI Account at hub.ci.computer. There is no password-reset email.

Run the setup wizard

After login, the wizard shows a System Overview (CPU, RAM, GPU, disk) and your install choices on one page.

Set Up Your Hub — system overview and install choices

Reasonable defaults for a first run:

Step	First-run default
Agent framework	OpenClaw
Memory apps	Leave pre-selected (includes Companion Memory)
Models	Pre-selected; models you pulled in Ollama show as Installed
Private VPN	Skip
Recommended apps	One you’ll use from the App Store, or none
Cloud API keys	Skip if running locally

Watch the footer download tally against free disk before clicking Install & Finish.

You can click Continue (apps installing in background) and use the dashboard while installs finish.

Wizard reference: Onboarding Wizard. Browse the full catalog: Apps Available.

Install your first app

If the wizard already installed apps, skip to Open on any app card. Otherwise:

App Store → Install → Open

Open the App Store in the sidebar (see App Store) → pick an app → Install → Open.

Examples:

Immich — photos (immich.app )
Vaultwarden — passwords (project wiki )
Nextcloud — files (nextcloud.com )
Jellyfin — media (jellyfin.org )

Apps get a hostname like http://immich.localhost and a direct port on the app card. If the hostname fails, use the port — Finding Your App’s URL.

You’re done

Hub, local inference, and at least one app — on hardware you control.


docker ps

Every dashboard app is a container in that list.

Next steps

Goal	Doc
Remote access	Networking
Backups	Backup & Restore
How Hub uses Docker	Docker & Hub
Connect an agent	Connect an Agent
Models and vLLM	AI & Inference
CLI	CLI Reference
Problems	Troubleshooting

If something went wrong

Symptom	Likely cause
`cihub: command not found`	Open a new terminal after first Hub launch
Dashboard won’t load at `localhost:5002`	`cihub status`; confirm Docker is running
Wizard shows no models	Ollama not reachable from containers — verify step
Memory search empty / embedding errors	No embedding model — pull one in Ollama or configure embeddings in Settings → AI
App URL 404s	Use the direct port on the app card
`permission denied` on Docker (Linux)	Log out/in after `usermod -aG docker`
Hub can’t reach Docker but `docker info` works	Docker socket mismatch

Still stuck? Getting Help — include cihub status output.