Self-hosting

Self-hosted CruciHiL is free and has no rig limits — the open source stack never enforces quotas on your own server. Register as many rigs as your benches need.

What the stack is

Docker Compose runs three services plus an optional virtual agent:

Service	What it is	Port
`db`	PostgreSQL 16 — run history, rigs, results	internal (5433 exposed in dev)
`server`	FastAPI control plane — REST API, agent WebSocket, Alembic migrations	8000
`mcp`	FastMCP server (SSE transport) — the AI interface	8001
`agent`	Optional virtual rig agent (compose profile `agent`)	—

The React dashboard (port 5173) runs natively via ./dev.sh (Vite HMR) or as a container through the development override compose file. Real rig agents run natively on your bench machines, not in Docker — they connect outbound to the server over WebSocket.

Prerequisites

Docker and Docker Compose (v2 plugin or v1 standalone — both are detected)
curl or wget, and python3 (used by the bootstrap script)

Bootstrap with `setup.sh`

From the project root:

./setup.sh

One command does the full bootstrap, and it is idempotent — safe to re-run:

Validates prerequisites (docker, docker compose)
Creates .env from .env.example and generates SECRET_KEY and REGISTRATION_TOKEN automatically
Starts db + server and waits for health (Alembic migrations run on startup)
Registers a default-rig and saves its API key to .env as CRUCIHIL_API_KEY
Starts all services (control plane + MCP server)

When it finishes:

Control plane: http://localhost:8000 (API docs at /docs)
MCP server: http://localhost:8001/sse

Other modes:

./setup.sh --status        # service health + rig connectivity
./setup.sh --restart       # restart all services without re-registration
./setup.sh --clean         # stop and remove containers (volumes kept)

setup.sh warns if POSTGRES_PASSWORD is still changeme. Change it in .env before exposing the server beyond localhost.

Environment variables

All configuration lives in .env (created from .env.example):

string

PostgreSQL username, used by the db service. Default: crucihil.

string

PostgreSQL password. Must be changed from the default changeme for production.

string

Database name. Default: crucihil.

string

Full connection string used by the server and Alembic, e.g. postgresql://crucihil:changeme@db:5432/crucihil. The hostname must match the compose service name db.

string

JWT signing secret. Generated automatically by setup.sh (or create one with python -c "import secrets; print(secrets.token_hex(32))"). Must be changed before production use.

string

Static token required to register new rigs (POST /api/v1/rigs). Generated automatically by setup.sh. Keep it private.

string

API key the MCP server uses to authenticate to the control plane. Written by setup.sh after it registers the default rig.

First org and admin — the one-shot `/setup` bootstrap

The dashboard and API use org-scoped users. Create the first organisation and admin account with a single call:

curl -X POST http://localhost:8000/api/v1/setup \
  -H 'Content-Type: application/json' \
  -d '{"org_name":"Acme","admin_email":"you@company.com","admin_password":"strong-password"}'

It returns a JWT and the org slug. Log in to the dashboard with the same email and password. The endpoint only succeeds while no organisation exists — every subsequent call returns 409 to prevent accidental re-initialisation. Admins can then invite team members from Settings → Team → Invite member.

Local development — `dev.sh`

For working on CruciHiL itself: backend in Docker, dashboard natively with Vite HMR.

./dev.sh                             # backend (db + server + mcp) + dashboard at localhost:5173
./dev.sh --agent                     # also start the Docker virtual rig agent
./dev.sh --rig rigs/my_bench.toml    # register + start a native agent for a TOML (repeatable)
./dev.sh --backend                   # backend only
./dev.sh --dashboard                 # dashboard only (backend must already be running)
./dev.sh --status                    # container health + rig connectivity
./dev.sh --stop                      # stop containers + kill native agents

The Docker virtual agent (rigs/virtual.toml) can also be started directly:

docker compose --profile agent up -d

Installing agents on bench machines

Each HiL bench machine runs a native agent that connects outbound to your control plane. Register the rig first (via POST /api/v1/rigs with the REGISTRATION_TOKEN, the dashboard, or the register_rig MCP tool) to get its API key, then install:

sudo ./scripts/install-agent.sh \
  --rig rigs/my_bench.toml \
  --server https://your-server.example.com \
  --key <api-key>

The installer (requires Python 3.11+, systemd, and sudo):

Creates a crucihil system user and installs the package into a venv at /opt/crucihil
Copies the rig TOML to /opt/crucihil/rigs/<name>.toml
Writes CRUCIHIL_BASE_URL and CRUCIHIL_API_KEY to /etc/crucihil/<name>.env (chmod 600)
Installs the systemd template unit crucihil-agent@.service
Enables and starts crucihil-agent@<name>

Optional flags: --dir (install directory, default /opt/crucihil) and --user (service user, default crucihil). Manage the service afterwards:

systemctl status crucihil-agent@my_bench          # check status
journalctl -u crucihil-agent@my_bench -f          # follow logs
systemctl stop crucihil-agent@my_bench            # stop
systemctl disable --now crucihil-agent@my_bench   # uninstall

The unit restarts the agent automatically on failure, backing off up to 5 minutes. The rig appears as connected in the dashboard within seconds of the agent starting.

Agents can also self-register: set registration_token in the rig TOML’s [rig.cloud] section, and on first boot the agent exchanges it for a permanent API key stored in ~/.crucihil/credentials.toml. The CRUCIHIL_BASE_URL / CRUCIHIL_API_KEY environment variables take precedence over [rig.cloud]. See Rig Configuration.

Connecting an AI client

Point any MCP client at your self-hosted MCP server. For Claude Desktop, add to claude_desktop_config.json:

{ "mcpServers": { "crucihil": { "url": "http://localhost:8001/sse" } } }

See MCP Overview for the full tool list and configuration options.

Deploying to Fly.io + Vercel

The repo ships Fly configs for the two backend services:

fly deploy --config fly.server.toml   # control plane
fly deploy --config fly.mcp.toml      # MCP server
# Dashboard auto-deploys to Vercel on push to main

The MCP app’s SECRET_KEY must match the control plane — set it with fly secrets set SECRET_KEY=... --app crucihil-mcp.

Guides

What the stack is

Prerequisites

Bootstrap with `setup.sh`

Environment variables

First org and admin — the one-shot `/setup` bootstrap

Local development — `dev.sh`

Installing agents on bench machines

Connecting an AI client

Deploying to Fly.io + Vercel

See also

​What the stack is

​Prerequisites

​Bootstrap with setup.sh

​Environment variables

​First org and admin — the one-shot /setup bootstrap

​Local development — dev.sh

​Installing agents on bench machines

​Connecting an AI client

​Deploying to Fly.io + Vercel

​See also

What the stack is

Prerequisites

Bootstrap with `setup.sh`

Environment variables

First org and admin — the one-shot `/setup` bootstrap

Local development — `dev.sh`

Installing agents on bench machines

Connecting an AI client

Deploying to Fly.io + Vercel

See also