Quickstart

This guide assumes you have completed Installation and that the proxy is running on port 4000.

1. Start the proxy

If you used Docker Compose, the proxy is already running. If you installed the native binary, start it with your environment variables:


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

The proxy binds to port 4000 (agent traffic) and port 4001 (management API) by default.

2. Send a request

Replace sk-... with your actual OpenAI or Anthropic API key. The proxy forwards it to the upstream and records the event — your key never touches govrix-scout’s storage.

OpenAI SDK (Python)


from openai import OpenAI
 
client = OpenAI(
    api_key="sk-...",           # your real OpenAI key
    base_url="http://localhost:4000/openai/v1",  # govrix-scout proxy
)
 
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
    extra_headers={
        "X-Agent-ID": "my-first-agent",   # used for cost attribution
        "X-Session-ID": "session-001",    # used for session forensics
    },
)
 
print(response.choices[0].message.content)

Anthropic SDK (Python)


import anthropic
 
client = anthropic.Anthropic(
    api_key="sk-ant-...",        # your real Anthropic key
    base_url="http://localhost:4000/anthropic",  # govrix-scout proxy
)
 
message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=256,
    extra_headers={
        "X-Agent-ID": "my-first-agent",
        "X-Session-ID": "session-001",
    },
    messages=[{"role": "user", "content": "What is the capital of France?"}],
)
 
print(message.content[0].text)

curl


curl http://localhost:4000/openai/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: my-first-agent" \
  -H "X-Session-ID: session-001" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "What is the capital of France?"}]
  }'

The X-Agent-ID and X-Session-ID headers are optional but strongly recommended. They enable per-agent cost attribution, kill switch targeting, and session forensics in the dashboard.

3. View events in the dashboard

Open http://localhost:3000 in your browser. You should see:

Agents — my-first-agent listed with token counts and cost
Events — the request and response recorded with full lineage
Sessions — session-001 with the complete prompt/response trail

The dashboard polls the management API every 5 seconds, so events appear within seconds of each request.

4. Query the management API directly

You can also query the management API directly to verify the event was recorded:


curl -H "Authorization: Bearer $GOVRIX_API_KEY" \
  http://localhost:4001/api/v1/agents

This returns the list of all registered agents with their accumulated token and cost totals.

Next steps

Configuration — tune upstream URLs, ports, and budget caps
API Reference — all 17 management API endpoints