Running locally

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

CI-Hub uses pnpm , not Bun. The repository declares packageManager: pnpm@11.5.1 and ships only pnpm-lock.yaml. This docs site uses Bun; Hub does not. Running bun install in a Hub checkout will not give you a working tree.

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
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

Get the code

Fork CI-Hub , clone your fork, then:


pnpm install

Start the stack

Run the wizard


./bin/cihub.cjs wizard

On a fresh checkout there is no environment file yet, so the wizard enters first-run mode: it shows a step tracker, checks Docker is available, runs setup and registration, then launches the Hub.

./bin/cihub.cjs is the CLI as declared in the repository’s package.json. It runs your working-tree TypeScript directly — see Running the CLI locally.

Open the dashboard

Surface	URL
Hub	`http://localhost:5002`
Frontend dev server (Vite)	`http://localhost:9091`

Doing it by hand instead

If you’d rather not use the wizard, the same result in three steps:


cp .env.example .env.local


cihub setup local


cihub up local

cihub up local brings up infrastructure and then runs the backend and frontend from source — no Docker image rebuild between edits.

Environments

Each environment reads its own file at the repository root:

Environment	File
`local`	`.env.local`
`dev`	`.env.dev`
`staging`	`.env.staging`
`prod`	`.env.prod`

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

.env.example is a template, not a working config. At minimum set ROOT_FOLDER_HOST (absolute path for persistent data) and JWT_SECRET (openssl rand -hex 32).

Day to day


cihub status              # containers, resolved config, ports


cihub down                # stop the stack


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

See the CLI Reference for the full command set.

Running tests


pnpm test                 # unit tests, plus the CLI suite


pnpm test:integration


pnpm test:e2e


pnpm test:cli             # CLI and TUI presentation tests

Working on the CLI itself? Running the CLI locally covers the tighter iteration loop.