Installation

Govrix Scout can be installed in two ways: via Docker Compose (recommended for production) or as a native binary (recommended for local development).

Prerequisites

Docker ≥ 24 and Docker Compose v2 (for Docker install)
OpenAI or Anthropic API key
PostgreSQL 16 with TimescaleDB (included in the Docker Compose stack)
Ports 4000, 4001, 3000, and 5432 available on your host

Option 1 — curl install (native binary)

The install script downloads the latest govrix-scout binary for your platform and places it in /usr/local/bin.


curl -fsSL https://raw.githubusercontent.com/manaspros/govrix-scout/main/install.sh | sh

After installation, verify the binary is available:


govrix-scout --version

The install script supports macOS (arm64, x86_64) and Linux (arm64, x86_64). If your platform is not detected automatically, see the GitHub releases page to download the appropriate binary.

Option 2 — Docker Compose

Clone the repository


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

Create your environment file

Copy the example env file and fill in your API key and database credentials:


cp .env.example .env

Open .env and set at minimum:


GOVRIX_API_KEY=your-management-api-key
GOVRIX_DATABASE_URL=postgres://govrix:govrix_scout_dev@postgres:5432/govrix
GOVRIX_PROXY__UPSTREAM_OPENAI=https://api.openai.com

Start the stack


docker compose up -d

This starts three services:

postgres — PostgreSQL 16 + TimescaleDB on port 5432
govrix-scout — the proxy on port 4000 and management API on port 4001
dashboard — the React dashboard on port 3000

Verify all services are healthy


docker compose ps

All three services should show healthy. If any service is not healthy after 30 seconds, check logs with docker compose logs <service>.

Health check

Once running (either install method), confirm the proxy and management API are responding:


# Proxy health
curl http://127.0.0.1:4000/health
 
# Management API health
curl -H "Authorization: Bearer $GOVRIX_API_KEY" http://127.0.0.1:4001/api/v1/health

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

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

Port reference

Port	Service	Description
4000	Proxy	Agent traffic — point your LLM SDK here
4001	Management API	17 REST endpoints, bearer auth required
3000	Dashboard	React UI for real-time observability
5432	PostgreSQL	Database (TimescaleDB hypertable for events)

Next steps

Quickstart — send your first proxied request in under 2 minutes
Configuration — full environment variable reference