Self-Hosting with Docker

Docker Compose is the recommended way to self-host Govrix Scout. It brings up the full stack — PostgreSQL 16 + TimescaleDB, the govrix-scout proxy, and the React dashboard — in a single command.

Prerequisites

Docker >= 24 and Docker Compose v2
Ports 4000, 4001, 3000, 5432, and 9090 available on your host
An OpenAI and/or Anthropic API key (or a compatible upstream URL)

Clone the repository


git clone https://github.com/manaspros/govrix-scout.git
cd govrix-scout

Configure environment

Copy the example env file:


cp .env.example .env

Open .env and set the required variables. A minimal working configuration looks like this:


# Management API bearer token — pick any strong random string
GOVRIX_API_KEY=replace-with-a-strong-random-secret

# Database connection string (matches the Compose postgres service)
GOVRIX_DATABASE_URL=postgres://govrix:govrix_scout_dev@postgres:5432/govrix

# Upstream LLM provider base URLs
GOVRIX_PROXY__UPSTREAM_OPENAI=https://api.openai.com
GOVRIX_PROXY__UPSTREAM_ANTHROPIC=https://api.anthropic.com

# Log level (optional — info is a sensible default)
RUST_LOG=govrix_scout_proxy=info,tower_http=debug

# Proxy and API listen ports (optional — defaults shown)
GOVRIX_PROXY_PORT=4000
GOVRIX_API_PORT=4001

All GOVRIX_PROXY__UPSTREAM_* variables accept any HTTP/HTTPS URL. You can point them at an internal gateway, a corporate proxy, or directly at the provider.

Start the stack


docker compose -f docker/docker-compose.yml up -d

This starts three services:

Service	Container	Description
`postgres`	`govrix-scout-postgres`	PostgreSQL 16 + TimescaleDB on port 5432
`proxy`	`govrix-scout-proxy`	`govrix-scout` binary — proxy on 4000, API on 4001, Prometheus on 9090
`dashboard`	`govrix-scout-dashboard`	React dashboard served by nginx on port 3000

The proxy service waits for postgres to pass its healthcheck before starting.

Verify the stack

Check that all containers are healthy:


docker compose -f docker/docker-compose.yml ps

Then confirm the proxy and management API are responding:


# Proxy liveness
curl http://127.0.0.1:4000/health
 
# Management API liveness
curl http://127.0.0.1:4001/health
 
# Management API readiness (waits for DB connection)
curl http://127.0.0.1:4001/ready
 
# Authenticated endpoint — replace $GOVRIX_API_KEY with your key
curl -H "Authorization: Bearer $GOVRIX_API_KEY" \
     http://127.0.0.1:4001/api/v1/agents

Both health endpoints should return {"status":"ok"}.

Use http://127.0.0.1 rather than http://localhost in health check curls. On some Linux distributions localhost resolves to IPv6 ::1 first, which fails if the service only listens on IPv4.

Open the dashboard

Navigate to http://localhost:3000 in your browser. The dashboard polls the management API every 5 seconds and shows real-time agent activity, costs, and events.

Port reference

Port	Service	Notes
4000	Proxy (agent traffic)	Set `OPENAI_BASE_URL=http://localhost:4000/proxy/openai/v1` in your agents
4001	Management API	Bearer auth required on `/api/v1/*`
3000	React dashboard	No auth in OSS tier
5432	PostgreSQL	TimescaleDB hypertable for events
9090	Prometheus metrics	Scrape with any Prometheus-compatible agent

Running only PostgreSQL (native binary dev mode)

When developing locally you may want to run the govrix-scout binary natively (for faster iteration) while keeping PostgreSQL in Docker:


# Start only the database container
docker compose -f docker/docker-compose.yml up postgres -d
 
# Run the proxy natively (adjust upstream URL and API key as needed)
GOVRIX_PROXY__UPSTREAM_OPENAI=https://api.openai.com \
GOVRIX_DATABASE_URL=postgres://govrix:govrix_scout_dev@localhost:5432/govrix \
GOVRIX_PROXY_PORT=4000 \
GOVRIX_API_PORT=4001 \
GOVRIX_API_KEY=govrix-local-dev \
./target/release/govrix-scout

If you need to target a corporate gateway or VPN-protected endpoint as your upstream, this native mode avoids Docker Desktop’s NAT layer, which is often blocked by Cloudflare WAF rules.

Customising upstreams with a Compose override

Create a docker-compose.override.yml at the repo root to inject custom upstream URLs without editing the base Compose file:


services:
  proxy:
    environment:
      GOVRIX_PROXY__UPSTREAM_OPENAI: "https://your-internal-openai-gateway.example.com"
      GOVRIX_PROXY__UPSTREAM_ANTHROPIC: "https://your-internal-anthropic-gateway.example.com"

Docker Compose merges this file automatically when you run docker compose up. No changes to docker/docker-compose.yml are needed.

Stopping the stack


docker compose -f docker/docker-compose.yml down
 
# To also remove the PostgreSQL volume (destructive — deletes all data)
docker compose -f docker/docker-compose.yml down -v