Running locally

How to run Companion Hub from a source checkout — for contributing, or for testing changes before they ship.

The development loop

Clone, install, bring the stack up from source, edit, test — there is no Docker image rebuild between edits.

flowchart LR
    a["Clone the repository"] --> b["pnpm install"]
    b --> c["cp .env.example .env.local<br/>fill in the required values"]
    c --> d{"How to start"}
    d -->|"Wizard"| e["./bin/cihub.cjs wizard"]
    d -->|"By hand"| f["cihub setup local<br/>cihub up local"]
    e --> g["Dashboard at :5005<br/>API at :5004"]
    f --> g
    g --> h["Edit the source"]
    h -->|"backend and frontend<br/>run from source"| g
    h --> i["pnpm test"]
    i --> j["cihub down<br/>or cihub reset local --yes"]
    click b "#install-dependencies"
    click c "#create-your-env-file"
    click e "#start-the-stack"
    click f "#doing-it-by-hand-instead"
    click i "#running-tests"
    click j "#day-to-day"

Prerequisites

• Docker with the Compose plugin — verify with docker compose version. See Install Docker if you need it.
• Node.js 22 or later — Hub declares engines.node: >=22, and .nvmrc pins Node 22
• pnpm 11 or later — engines.pnpm: >=11

The simplest way to get the right pnpm is Corepack, which reads the pinned version out of the repository’s packageManager field:

corepack enable

Install dependencies

Clone the repository  (or your fork of it), then install from its root:

pnpm install

The install needs no credentials. The design files the frontend needs are copied into the repository, so no private package registry is involved.

Build packages/common before you run backend tests, because the backend resolves @ci-hub/common/validation from its dist/ folder:

pnpm --filter common build

If you build the desktop app or run its Rust tests, you also need the GTK and WebKit development headers. On Debian and Ubuntu:

sudo apt-get install -y build-essential pkg-config libssl-dev libdbus-1-dev libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libxdo-dev

The web stack does not need them.

Create your env file

A source checkout does not generate its own environment file. Copy the template and fill in the required values:

cp .env.example .env.local

Start the stack

./bin/cihub.cjs wizard

Doing it by hand instead

If you’d rather not use the wizard, the same result in two commands:

cihub setup local

cihub up local

cihub up local starts PostgreSQL and RabbitMQ in Docker, then runs the backend and frontend from source — no Docker image rebuild between edits. pnpm run local is the same command.

If port 5004 or 5005 is already in use by something else, the command stops with Local development port conflict. Stop the other process and run it again.

Environments

Each environment reads its own file at the repository root:

Most commands take the environment as an argument — cihub up local, cihub setup local, cihub wizard staging. Omitted, it defaults to local.

Day to day

cihub status              # containers, dashboard URL, tunnel, VPN, models

cihub down                # stop the stack

cihub reset local --yes   # wipe local runtime state for a clean-slate run

cihub reset removes installed apps, runtime state, volumes, and the data folder. It does not delete .env.local, so the wizard does not re-enter first-run mode afterward. To see the first-run flow again, move .env.local aside first.

See the CLI Reference for the full command set.

Running tests

pnpm test                 # unit tests, the CLI suite, and the entrypoint tests

pnpm test:integration

pnpm test:e2e

pnpm test:cli             # CLI and TUI presentation tests

Automatic CI triggers are gated, so run pnpm run check:pr before you request review — nothing runs it for you on push. It runs lint, the dead-code check, type checks, the OpenAPI drift check, the tests, and the desktop crate’s Rust tests.