Quickstart

Get observability, governance, and intelligent routing for your AI agents in 5 minutes.

What is RelayPlane?

RelayPlane is a cost optimization proxy that sits between your AI agents and LLM providers. Every request is:

  • Recorded in the Learning Ledger with full context
  • Evaluated against your policies (budgets, allowlists, approval gates)
  • Routed to the best provider based on capabilities and cost
  • Explained with human-readable decision chains

1. Install the Proxy

1npm install @relayplane/proxy

2. Start the Proxy

Max plan / Claude Code users: skip this step, no API key needed.
1# Set the API keys you have (any one is enough)
2export ANTHROPIC_API_KEY=your-key
3export OPENAI_API_KEY=your-key
4export OPENROUTER_API_KEY=your-key
5
6# Start the proxy (the npm package is @relayplane/proxy)
7npx @relayplane/proxy start
8# or, after npm install -g @relayplane/proxy:
9relayplane start

The proxy starts on http://localhost:4100 by default.

3. Point Your Client at the Proxy

RelayPlane is OpenAI-compatible. Just change the base URL:

1import Anthropic from '@anthropic-ai/sdk';
2
3const client = new Anthropic({
4  baseURL: 'http://localhost:4100',  // Point to RelayPlane (the SDK adds /v1/messages)
5});
6
7const response = await client.messages.create({
8  model: 'claude-sonnet-5',
9  max_tokens: 1024,
10  messages: [{ role: 'user', content: 'Hello!' }],
11});
12
13console.log(response.content);
Every request is now recorded in the local ledger with tokens and cost. View your runs at http://localhost:4100/dashboard or curl localhost:4100/v1/telemetry/runs. OpenAI SDK users: set OPENAI_BASE_URL=http://localhost:4100 instead.

4. Add Context Headers

Add headers to identify your agents and sessions:

1const response = await client.messages.create({
2  model: 'claude-sonnet-5',
3  max_tokens: 1024,
4  messages: [{ role: 'user', content: 'Hello!' }],
5}, {
6  headers: {
7    'X-RelayPlane-Workspace': 'ws_production',
8    'X-RelayPlane-Agent': 'support-bot',
9    'X-RelayPlane-Session': 'session_abc123',
10  },
11});

5. See Every Routing Decision

Every response carries the decision in headers, and the ledger keeps the cost:

1curl -i http://localhost:4100/v1/chat/completions \
2  -H "Content-Type: application/json" \
3  -d '{"model":"relayplane:auto","messages":[{"role":"user","content":"Reply with PONG"}]}'
4
5# Headers on the response:
6x-relayplane-requested-model: relayplane:auto
7x-relayplane-routed-model: claude-sonnet-5
8x-relayplane-provider: anthropic
9x-relayplane-complexity: simple
10x-relayplane-routing-mode: auto
11
12# The ledger entry, with cost:
13curl "http://localhost:4100/v1/telemetry/runs?limit=1"

6. Put a Cap on It

1relayplane cap set --day 10      # 429 budget_exceeded once today's spend would pass $10
2relayplane budget status         # what the running proxy is enforcing
3relayplane kill                  # halt ALL routed traffic until: relayplane resume

Next Steps