Server Mode (Self-Hosting)

Note

This page describes the opt-in Docker server runtime. It is not required to use Verfix — by default, verfix run executes entirely in a single Node.js process on your machine with no Docker, no queue, and no database. See Getting Started for the default, local-first path. Server mode is the foundation of a future hosted CI product; today it’s useful for teams that want a shared, centrally observable deployment.

Server mode packages a Go API, a Redis-backed job queue, containerized Playwright workers, and a Next.js execution-timeline dashboard into a single Docker image.

Image	Database	Use case
ghcr.io/verfix-dev/verfix-server:latest	PostgreSQL	Shared team deployments, CI/CD, server hosting

Opt in per-command with --server, or set VERFIX_RUNNER=server in .verfix/.env to make it the default for a project.

---

Quick start (single container)

docker run -d \
  --name verfix \
  --network=host \
  -e VERFIX_HOST_NETWORK=1 \
  ghcr.io/verfix-dev/verfix-server:latest

Verify the runtime is healthy:

curl http://localhost:3611/api/v1/health

Expected response:

{ "status": "healthy" }

Then point the CLI at server mode:

verfix init --server
verfix run --server --flow login --output json

---

Ports

Port	Service	Description
3610	Dashboard	Next.js execution timeline UI
3611	API	Go/Fiber REST API

If ports 3610/3611 are occupied, the CLI automatically tries the next pair (3612/3613, 3614/3615, …).

---

Volume mounts

Volume	Container path	Description
verfix-data	/var/lib/postgresql/15/main	PostgreSQL data — execution history, assertion results
verfix-artifacts	/app/workers/artifacts	Screenshots, traces, HAR files, console logs

Data persists across container restarts when these volumes are mounted.

---

Environment variables

Variable	Default	Description
OPENAI_API_KEY / provider key	—	Required for Assisted and Exploratory modes.
AI_MODEL	provider default	AI model used for semantic healing and exploratory mode.
MAX_CONCURRENCY	3	Maximum number of parallel Playwright jobs.
DATABASE_URL	Internal	PostgreSQL connection string (pre-configured inside the container).
REDIS_URL	Internal	Redis connection string (pre-configured inside the container).

docker run -d \
  --name verfix \
  --network=host \
  -e VERFIX_HOST_NETWORK=1 \
  -e OPENAI_API_KEY=sk-... \
  -e MAX_CONCURRENCY=5 \
  -v verfix-data:/var/lib/postgresql/15/main \
  -v verfix-artifacts:/app/workers/artifacts \
  ghcr.io/verfix-dev/verfix-server:latest

---

docker-compose.yml for teams

services:
  verfix:
    image: ghcr.io/verfix-dev/verfix-server:latest
    container_name: verfix
    network_mode: host
    environment:
      VERFIX_HOST_NETWORK: "1"
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      MAX_CONCURRENCY: ${MAX_CONCURRENCY:-3}
    volumes:
      - verfix-data:/var/lib/postgresql/15/main
      - verfix-artifacts:/app/workers/artifacts
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3611/api/v1/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

volumes:
  verfix-data:
  verfix-artifacts:

Start with:

OPENAI_API_KEY=sk-... docker compose up -d

---

Health check

curl http://localhost:3611/api/v1/health

A healthy runtime returns 200 OK with { "status": "healthy" }.

---

Updating

verfix update --server

Or manually:

docker pull ghcr.io/verfix-dev/verfix-server:latest
docker stop verfix && docker rm verfix
docker run -d ... # same flags as before

---

CLI with a remote server runtime

If the runtime is running on a remote machine, point the CLI at it:

verfix run --server --flow login --dashboard http://your-server:3610 --output json

Or set VERFIX_API_URL:

export VERFIX_API_URL=http://your-server:3611
verfix run --server --flow login --output json

---

CI with server mode

Local mode is the recommended default in CI (no containers to start or wait on — see Agent Integration). If you specifically need to exercise the server runtime itself:

- name: Start Verfix server runtime
  run: |
    docker run -d --network=host -e VERFIX_HOST_NETWORK=1 ghcr.io/verfix-dev/verfix-server:latest
    sleep 15 # wait for services

- name: Run verification
  run: npx verfix run --server --output json