Quickstart Guide

This guide walks you through installing Govyn, adding your first LLM provider, creating a budget policy, and routing your first agent request through the proxy. The entire process takes under five minutes. By the end, you will have a working governance proxy that tracks costs, enforces budget limits, and logs every LLM request your agents make.

Prerequisites

Before you begin, make sure you have:

No database, Redis, Docker, or cloud account is required. Govyn runs as a single process with a YAML configuration file.

Step 1: Install and initialize

Run the init command to create a new Govyn project in your current directory: 

npx govyn init

This creates a govyn.yaml configuration file with sensible defaults. The file is the single source of truth for your proxy configuration — providers, policies, and server settings all live here.

If you prefer a global installation, you can install Govyn as a package first: 

npm install -g govyn
govyn init

Both approaches produce the same result. The npx method avoids a global install and always uses the latest version.

Step 2: Add your provider API key

Open govyn.yaml and add your LLM provider credentials under the providers section.

For OpenAI: 

providers:
  openai:
    api_key: sk-your-openai-key-here

For Anthropic: 

providers:
  anthropic:
    api_key: sk-ant-your-anthropic-key-here

You can configure multiple providers in the same file. The proxy routes each request to the correct provider based on the model name — models starting with gpt- go to OpenAI, models starting with claude- go to Anthropic, and so on.

For production deployments, use environment variable references instead of hardcoded keys. Replace the key value with $OPENAI_API_KEY or $ANTHROPIC_API_KEY, and Govyn will read the value from your environment at startup. This keeps secrets out of your configuration files and version control.

Step 3: Define your first policy

Add a budget limit to prevent runaway costs. This is the most common first policy — it ensures no single agent can spend more than a fixed amount per day. 

policies:
  - name: daily-budget
    type: budget
    rule:
      daily_limit: 5.00
      action: block

This policy does three things:

  1. Tracks the total cost of all LLM requests made by each agent, across all providers and models.
  2. When an agent's daily spend reaches $5.00, blocks all subsequent requests for the rest of the day.
  3. Returns a structured JSON error to the agent explaining why the request was blocked and which policy triggered the block.

The action: block setting means requests that exceed the budget are rejected with an error. You can also use action: warn to log a warning without blocking, which is useful during initial rollout when you want to observe spending patterns before enforcing limits.

You can add more policies later — model allowlists, rate limits, loop detection, and approval workflows. For now, a single budget policy is enough to demonstrate the proxy in action.

Step 4: Start the proxy

Start the Govyn proxy server: 

npx govyn start

The proxy starts on http://localhost:4000 by default. You should see output confirming the server is running, the configured providers, and the active policies. If you need a different port, set the port field in govyn.yaml.

Verify the proxy is running by checking the health endpoint: 

curl http://localhost:4000/health

You should receive a JSON response confirming the proxy is healthy and ready to accept requests.

Step 5: Point your agent at the proxy

The final step is to change your agent's LLM client configuration. Instead of calling the provider API directly, point it at the Govyn proxy. This requires changing two values: the base URL and the API key.

Here are examples for the most common client libraries.

OpenAI Python

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000/v1",
    api_key="your-govyn-proxy-token",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello, world!"}],
    extra_headers={"X-Govyn-Agent": "my-first-agent"},
)

print(response.choices[0].message.content)

Anthropic Python

import anthropic

client = anthropic.Anthropic(
    base_url="http://localhost:4000",
    api_key="your-govyn-proxy-token",
)

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, world!"}],
    extra_headers={"X-Govyn-Agent": "my-first-agent"},
)

print(message.content[0].text)

Node.js (OpenAI SDK)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:4000/v1",
  apiKey: "your-govyn-proxy-token",
});

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello, world!" }],
  headers: { "X-Govyn-Agent": "my-first-agent" },
});

console.log(response.choices[0].message.content);

The key changes in each example:

This pattern works with any client library or framework that lets you set a custom base URL — LangChain, CrewAI, OpenAI Agents SDK, AutoGen, and any HTTP client. See the Integration Guides for framework-specific examples.

Step 6: Verify it works

After sending your first request through the proxy, verify that Govyn logged it correctly: 

curl http://localhost:4000/api/logs?limit=1

You should see a JSON response containing your request details: 

[
  {
    "id": "log_abc123",
    "agent": "my-first-agent",
    "model": "gpt-4o-mini",
    "provider": "openai",
    "input_tokens": 12,
    "output_tokens": 28,
    "cost_usd": 0.000042,
    "policy_result": "allowed",
    "created_at": "2025-01-15T10:30:00Z"
  }
]

The log entry confirms that your request was routed through Govyn, the agent was identified, token counts and cost were tracked, and the policy evaluation result was recorded. Every subsequent request from this agent will be logged in the same way.

You can also check the agent's current budget status: 

curl http://localhost:4000/api/budget/status?agent=my-first-agent

This returns the remaining daily and monthly budget for the agent, based on the policies you configured.

What happens when you exceed the budget

When an agent's spending reaches the daily limit defined in your budget policy, the proxy blocks all subsequent requests from that agent for the rest of the day. Instead of forwarding the request to the provider, Govyn returns a structured JSON error: 

{
  "type": "policy_violation",
  "message": "Daily budget limit of $5.00 exceeded. Current spend: $5.12.",
  "policy": "daily-budget",
  "agent": "my-first-agent"
}

The response includes:

This structured error format is consistent across all policy types — budget limits, rate limits, model restrictions, and loop detection. Your agents can inspect the type field to determine the appropriate response: retry later, fall back to a cheaper model, or escalate to a human.

Budget counters reset at midnight UTC by default. Monthly budget limits (if configured) reset on the first of each month.

Complete configuration example

Here is a full govyn.yaml with two providers and three policies — a budget limit, a model allowlist, and a rate limit. This configuration is a solid starting point for most teams. 

# govyn.yaml
port: 4000

providers:
  openai:
    api_key: $OPENAI_API_KEY
  anthropic:
    api_key: $ANTHROPIC_API_KEY

policies:
  - name: daily-budget
    type: budget
    rule:
      daily_limit: 5.00
      monthly_limit: 50.00
      action: block

  - name: model-allowlist
    type: model_filter
    rule:
      allowed:
        - gpt-4o-mini
        - gpt-4o
        - claude-sonnet-4-20250514
        - claude-haiku-4-20250414

  - name: rate-limit
    type: rate_limit
    rule:
      max_requests: 100
      window: 60

This configuration:

Next steps

Your Govyn proxy is running and enforcing governance policies. Here are the recommended next steps to expand your setup:

Frequently asked questions

What are the prerequisites for installing Govyn?

You need Node.js 18 or later and an API key from at least one LLM provider (OpenAI, Anthropic, or any OpenAI-compatible endpoint). No database, Redis, Docker, or cloud account is required. Govyn runs as a single process with a YAML configuration file.

How long does it take to set up Govyn?

The initial setup takes under five minutes. Run npx govyn init to generate the configuration, add your provider API key, define a policy, and start the proxy with npx govyn start. You can send your first proxied request within minutes of starting.

Does Govyn work with streaming responses?

Yes. Govyn fully supports Server-Sent Events (SSE) streaming for both OpenAI and Anthropic providers. Streaming responses are passed through to the agent in real time with no buffering. Token counting and cost tracking work with streaming responses — Govyn extracts usage data from the stream events inline.

Can I use environment variables for API keys in govyn.yaml?

Yes. Use the $VARIABLE_NAME syntax in govyn.yaml to reference environment variables. For example, api_key: $OPENAI_API_KEY reads the value from the OPENAI_API_KEY environment variable at startup. This avoids hardcoding secrets in configuration files and is the recommended approach for production deployments.

What happens when an agent exceeds its budget limit?

The proxy returns a structured JSON error with HTTP status 429. The response includes the policy name, a human-readable message explaining the budget limit and current spend, and the agent identity. The agent receives a clear, programmatic signal that the request was blocked — not a generic error. Budget counters reset at midnight UTC daily.

Can I run Govyn alongside my existing LLM setup?

Yes. You can migrate agents one at a time. Point individual agents at the Govyn proxy URL while others continue calling the provider directly. There is no all-or-nothing requirement. This makes it easy to evaluate Govyn with a single agent before rolling it out across your entire team.

Does Govyn add latency to LLM requests?

Govyn adds sub-millisecond latency per request. Policy evaluation happens in-memory with no external calls or database lookups in the critical path. The overhead is negligible compared to LLM inference time, which typically ranges from hundreds of milliseconds to several seconds.

What port does Govyn run on by default?

Govyn runs on port 4000 by default. You can change this by setting the port field in govyn.yaml to any available port number. For example, port: 8080 starts the proxy on port 8080.

Back to documentation Integration guides