Running locally

In this guide we will show you how to run Companion Home locally on your machine. This is useful if you want to contribute to the project or test new features.

Prerequisites

Docker Desktop version 28 or later (with Docker Compose plugin)
Bun (the project uses Bun as its package manager and runtime)
Node.js version 22+

Prepare

Fork the CI-OS-Hub repository and clone it to your local machine.

Install dependencies

Install the project dependencies:


bun install

Configure environment

Copy the example environment file:


cp .env.example .env.local

Edit .env.local with your local settings. At minimum you’ll need:

TIPI_DATA_DIR — path to your data directory
POSTGRES_HOST=localhost
RABBITMQ_HOST=localhost

Start infrastructure

Start the PostgreSQL database and RabbitMQ queue:


bun run infra:up

This launches containers for ci-hub-db (PostgreSQL on port 6543) and ci-os-hub-queue (RabbitMQ).

Run the application

Start the backend and frontend in development mode:


bun run dev

Or if infrastructure is already running:


npx dotenv -e .env.local -- bun run dev:app

Backend will be available at http://localhost:3000
Frontend will be available at http://localhost:9091

Stop infrastructure

When you’re done:


bun run infra:down

Running tests


# Unit tests
bun run test
 
# Integration tests
bun run test:integration
 
# E2E tests
bun run test:e2e