Managed AI Proxy

The managed AI proxy lets your workspace code call supported AI providers without putting provider API keys in the VM. Rigbox holds managed provider keys on your behalf, injects them at request time, and tracks usage against your credit balance.

Before you begin

Use the v0.13 CLI and authenticate. Run workspace-management and recipe commands from your local terminal. Commands identified as running inside a workspace require its console terminal or SSH session. Replace example resource IDs with the values returned for your account. Start the target workspace first and verify its identity with rig workspace ls. AI calls require managed credits or an appropriately configured provider account.

How It Works

Every workspace can reach the proxy at http://172.16.0.1:9090 from inside the VM. When managed mode is active, SDK requests configured to use this endpoint pass through that bridge-local proxy, which fronts an OpenRouter gateway. The proxy:

Receives the request addressed to the proxy by your workspace code
Resolves the workspace from the VM’s source IP on the compute bridge
Injects Rigbox’s managed OpenRouter key (your VM never sees it)
Forwards the request to OpenRouter, which routes to the appropriate upstream provider for the requested model
Logs token usage and deducts from your credit balance
Returns the response to your code

OpenRouter acts as a single gateway in front of every supported model family, so you only point your SDK at one endpoint regardless of which provider’s model you ask for. Pick the upstream provider by choosing the model slug (e.g. anthropic/claude-sonnet-4, openai/gpt-4o, google/gemini-2.5-pro).

Managed workspaces inject OPENROUTER_BASE_URL=http://172.16.0.1:9090/v1 and OPENROUTER_API_KEY at workspace boot, so SDKs and CLI tools that read OpenRouter env vars work out of the box. For tools that read the OpenAI variables instead, rig proxy on prints the matching export statements for your shell, scripts, or CI.

Endpoints

The proxy speaks two HTTP shapes — OpenAI-compatible (used by most SDKs and tools) and an Anthropic-shaped passthrough for Claude Code. Both terminate on the same OpenRouter gateway behind the scenes.

Endpoint	Shape	Notes
`http://172.16.0.1:9090/v1/chat/completions`	OpenAI	Default route for everything OpenAI-compatible. Pick the upstream model with the `model` field (`anthropic/...`, `openai/...`, `google/...`, etc.).
`http://172.16.0.1:9090/v1/embeddings`	OpenAI	Embedding models.
`http://172.16.0.1:9090/v1/models`	OpenAI	List models available to your account.
`http://172.16.0.1:9090/v1/messages`	Anthropic	Native Anthropic Messages-API passthrough used by Claude Code. Anthropic clients reach it with the proxy root as their base URL. Streams via byte forwarding; credit metering for streaming responses on this endpoint is currently deferred.
`http://172.16.0.1:9090/rig/v1/usage`	Rigbox	Per-subject AI spend over a rolling window. See Per-subject cost and budgets.
`http://172.16.0.1:9090/brave`	Brave Search	Web Search API when configured for your environment.

OpenAI-shape responses now carry the settled rigbox-credit cost of each call (X-Rigbox-Cost-* headers + usage.cost_micro/cost_credits), and multi-tenant apps can attribute, read, and cap cost per end-user. See Per-subject cost and budgets.

A small set of free-tier models is also exposed through a free alias when Rigbox has the matching managed key. They consume credits at zero rate but otherwise behave identically.

Base URLs for clients

Clients take a base URL and add the endpoint path themselves, so the base URL depends on the API shape:

Client	Base URL variable	Value	The client adds
OpenAI-compatible SDKs and tools	`OPENAI_BASE_URL` (or `OPENROUTER_BASE_URL`)	`http://172.16.0.1:9090/v1`	`/chat/completions`, `/embeddings`, …
Anthropic SDKs and Claude Code	`ANTHROPIC_BASE_URL`	`http://172.16.0.1:9090`	`/v1/messages`

Don’t add /v1 to an Anthropic base URL: the client would request /v1/v1/messages. The Claude Code catalog item sets ANTHROPIC_BASE_URL to the proxy root for you.

Credit Tiers

Use rig status and your account’s credit response to inspect the current balance and renewal information. Included credits depend on your plan; purchased credits and included credit buckets can have different renewal behavior. Credits map roughly to API cost - one credit equals approximately $0.01 of upstream provider spend. The exact mapping depends on the model and token count.

Activate Managed Mode

With the CLI

Set a workspace to managed mode with rig workspace ai mode:

rig workspace ai mode --workspace <workspace_id> managed

The command suggests the environment for agents that don’t read the OpenRouter variables, with each client’s base URL:

✓ my-project → managed

  Point your agent's provider env at the proxy (Rigbox credits). Suggested:
    rig workspace env set OPENAI_BASE_URL=http://172.16.0.1:9090/v1 OPENAI_API_KEY=managed-by-rigbox -w my-project
    rig workspace env set ANTHROPIC_BASE_URL=http://172.16.0.1:9090 ANTHROPIC_API_KEY=managed-by-rigbox -w my-project

  OpenAI-compatible clients take the /v1 base; Anthropic clients add /v1/messages themselves.
  The proxy intercepts and injects your real upstream key.

  If you turn the proxy off inside the workspace (rigbox proxy off), calls fail until you turn it
  back on or switch to byok with a real key.

Run inside the workspace, rig workspace ai mode managed changes that workspace and prints the same suggestions without -w. Provider and model are account-level defaults. rig ai defaults with no flags shows them; pass flags to change them:

rig ai defaults
rig ai defaults --provider google --model google/gemini-2.5-pro

Inside a workspace, rig ai defaults shows the defaults but can’t change them; change them from your machine.

Inside a Workspace VM

Managed workspaces already inject OPENROUTER_BASE_URL and OPENROUTER_API_KEY into every login shell, so most tools work without any setup step. The rig proxy on helper is a convenience for scripts or CI where you want the exports printed explicitly:

eval "$(rig proxy on)"

It prints export statements for the proxy’s root and its OpenAI-compatible /v1 base, with the managed-by-rigbox placeholder key that the proxy replaces:

export OPENAI_API_KEY='managed-by-rigbox';
export OPENAI_BASE_URL='http://172.16.0.1:9090/v1';
export RIGBOX_AI_PROXY_URL='http://172.16.0.1:9090';

Tools that read those variables use the proxy; explicit SDK settings may override them. For Anthropic clients, set ANTHROPIC_BASE_URL to the proxy root as described in Base URLs for clients.

Use rig proxy status to see the configured endpoints, current shell state, and credit balance.

To deactivate:

eval "$(rig proxy off)"

rig proxy off unsets RIGBOX_AI_PROXY_URL, and unsets a provider variable only while it still points at the proxy: a base URL such as OPENAI_BASE_URL or ANTHROPIC_BASE_URL whose value is the proxy address, or a key such as OPENAI_API_KEY or ANTHROPIC_API_KEY that holds the managed-by-rigbox placeholder. Your own keys and base URLs stay set, and so do the workspace’s OPENROUTER_BASE_URL and OPENROUTER_API_KEY.

Check Your Credit Balance

The fastest path is the CLI:

rig status

rig status prints your remaining credits, monthly total, current mode, and active workspaces. For programmatic access, see the Credits API reference.

View Usage Breakdown

Get a daily breakdown of credit consumption across your workspaces.

rig ai usage

{
  "usage": [
    {
      "date": "2026-04-07",
      "workspace_id": "ws_abc123",
      "workspace_name": "my-ml-project",
      "provider": "google",
      "model": "google/gemini-2.5-pro",
      "credits_used": 42,
      "requests": 15
    },
    {
      "date": "2026-04-06",
      "workspace_id": "ws_abc123",
      "workspace_name": "my-ml-project",
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "credits_used": 108,
      "requests": 23
    }
  ]
}

See the AI Usage API reference for full response schema and query parameters.

Per-subject cost and budgets

If your app fronts many end-users through a single workspace — a multi-tenant SaaS, an agent platform, a shared chatbot — you can attribute managed-AI cost to each end-user (“subject”), read their spend, and cap it. The proxy is the mechanism (accurate cost, attribution, enforcement); your app owns the policy (which tiers exist, the amounts, the windows) and asserts the subject id over the already-IP-attested channel. This covers the OpenAI-shape endpoints (/v1/chat/completions, /v1/completions, /v1/responses, /v1/embeddings).

Read the settled cost of a call

The settled rigbox-credit cost rides on the response — no second lookup. 1 credit ≈ $0.01; 1,000,000 microcredits = 1 credit. cost_micro is the exact integer; cost_credits is the convenience float. The fields are best-effort: present only when the upstream model reports a cost, so don’t treat their absence as zero.

curl -i "$OPENROUTER_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","max_tokens":16,
       "messages":[{"role":"user","content":"hi"}]}'

X-Rigbox-Cost-Micro: 360
X-Rigbox-Cost-Credits: 0.000360

{"usage":{"prompt_tokens":12,"completion_tokens":3,"cost":3.6e-06,
          "cost_micro":360,"cost_credits":0.00036}}

For streaming ("stream": true), the same cost_micro / cost_credits are spliced into the final usage chunk:

data: {"usage":{"completion_tokens":2,"cost_micro":300,"cost_credits":0.0003}}
data: [DONE]

Attribute a call to a subject

Tag any call with X-Rigbox-Subject (it wins) or the OpenAI user body field. Trimmed; empty = unattributed; capped at 256 characters.

curl "$OPENROUTER_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "X-Rigbox-Subject: tenant-42" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'

Read a subject’s rolling spend

curl "http://172.16.0.1:9090/rig/v1/usage?subject=tenant-42&window=24h"

{"subject":"tenant-42","window_seconds":86400,
 "credits":0.00072,"credits_micro":720,
 "input_tokens":8,"output_tokens":10,"requests":1}

window accepts 30s / 15m / 5h / 7d or a bare number of seconds (default 86400). It’s a rolling window scoped to your workspace — you can only read your own subjects, and they’re isolated from each other. Attribution is forward-only. This read alone is enough to enforce policy yourself (read spend → decide whether to call); the next section is for letting the proxy do it. See the Get Subject Usage API reference.

Enforce budgets and rate limits

Declare the policy inline on each request and the proxy checks it against the subject’s recorded spend before the call runs:

curl "$OPENROUTER_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "X-Rigbox-Subject: tenant-42" \
  -H "X-Rigbox-Subject-Budget: 50;period=30d" \
  -H "X-Rigbox-Subject-Rate: 5;window=1h" \
  -H "X-Rigbox-Subject-Rate: 100req;window=1m" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'

Header	Cardinality	Meaning
`X-Rigbox-Subject-Budget`	at most one	Total spend cap: `<amount>;period=<window>`
`X-Rigbox-Subject-Rate`	repeatable	Sliding limit: `<amount>;window=<window>`

Amount — a bare number is credits (5 = 5 credits); a req suffix is a request count (100req).
Window — 5h / 30m / 3600 / 7d.
Enforcement requires X-Rigbox-Subject; with no subject, the limit headers are ignored.

On breach the call is rejected before any spend, with a Retry-After header and a structured body. OpenAI SDKs still read error.message / error.code; error.details is the rich payload for your UX:

{"error":{
  "code":"subject_rate_limited",
  "message":"Subject 'tenant-42' hit a rate limit: 5 credits per 3600s.",
  "details":{
    "reason":"subject_rate_limited","subject":"tenant-42",
    "limit":{"kind":"credits","amount":5.0,"window_seconds":3600},
    "used":{"credits":5.0,"credits_micro":5000000},
    "resets_at":"2026-06-15T13:00:00Z","retry_after":3600}}}

{"error":{
  "code":"subject_over_budget",
  "message":"Subject 'tenant-42' is over its budget: 50 credits per 2592000s.",
  "details":{
    "reason":"subject_over_budget","subject":"tenant-42",
    "limit":{"kind":"credits","amount":50.0,"window_seconds":2592000},
    "used":{"credits":50.3,"credits_micro":50300000},
    "resets_at":"2026-07-15T06:04:15Z","retry_after":2592000}}}

A budget breach returns 402 subject_over_budget, a rate breach 429 subject_rate_limited (budget is evaluated first if several trip), and a malformed limit header 400 subject_limit_malformed. The full schema is in the Chat Completion API reference.

Per-subject budgets are advisory app policy, not a hard wall. The hard cap is your workspace’s own credit balance (enforced atomically). Under concurrency a subject can overshoot a budget by roughly (in-flight − 1) × per-request cost, never beyond the workspace balance. resets_at / retry_after are a conservative upper bound (the window length). Because your app asserts the subject id and its limits, this guards against honest tenant over-spend, not a compromised app process.

/v1/messages (Anthropic) and the audio endpoints are not yet covered by per-subject attribution or enforcement.

What Happens When Credits Run Out

When your credit balance reaches zero:

API requests return HTTP 402 - the proxy rejects new managed AI calls until credits are available
The UI shows an upgrade prompt - you can upgrade to Pro or switch to BYOK mode
Existing services keep running - only new AI API calls are blocked; your workspace and non-AI services are unaffected

If you have a long-running agent or automated pipeline, it will start receiving 402 errors once credits are exhausted. Consider monitoring your balance programmatically using the credits endpoint.

End-to-End Example

Here is a complete flow: activate managed mode, make an AI call from inside the workspace, then check remaining credits. Step 1 - Activate managed mode for a workspace:

rig workspace ai mode --workspace ws_abc123 managed
rig ai defaults --provider google --model google/gemini-2.5-flash-lite

Step 2 - Inside the workspace VM, configure the shell and make a call:

# (Optional — managed workspaces export these at login already.)
eval "$(rig proxy on)"

curl -sS "$OPENROUTER_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash-lite",
    "messages": [
      {"role": "user", "content": "Explain microVMs in one paragraph."}
    ]
  }' | jq .

Step 3 - Check remaining credits: rig status prints your balance directly. For the raw payload, query the endpoint with rig api:

rig api GET /v1/users/me/credits
# {"remaining": 1795, "total": 2000, "mode": "managed"}

Credit deduction happens synchronously - the balance is updated before the proxy returns the response to your code, so a completed request’s settled usage can be checked after its response.

Switching Providers and Models

Because the managed gateway is OpenRouter, you can switch the upstream provider and model at any time by changing the model field on your request — there’s no environment change, no proxy restart, and no separate “configure provider” step:

# Same endpoint, different upstream model
curl -sS "$OPENROUTER_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "hi"}]}'

The account-level AI defaults (set with rig ai defaults) define the default provider and model used by tools that don’t ask for one explicitly, and are also surfaced by rig proxy status.

Verify and troubleshoot

Inside the workspace, inspect rig proxy status, then make one small request with your chosen tool. Verify the configured endpoint and check the corresponding Rigbox or provider usage. After changing keys or mode, start a fresh shell and restart processes that retained their old configuration. Never print a provider key to verify it. For failures, start with runtime logs, health checks, or resource exhaustion.

Next Steps

AI Coding Tools - use Rigbox credits with Claude Code, Codex, OpenCode, and Kilocode
App Catalog - install the built-in coding agents with one command
Bring Your Own Keys - use your own API keys for unlimited usage
Setup Scripts - automate SDK installation in new workspaces
Service Specs - run AI-powered services as background daemons

Start here

Deploy applications

Configure applications

Workspaces and storage

AI and tools

Operate and troubleshoot

Examples

CLI reference

Build on Rigbox

Before you begin

How It Works

Endpoints

Base URLs for clients

Credit Tiers

Activate Managed Mode

With the CLI

Inside a Workspace VM

Check Your Credit Balance

View Usage Breakdown

Per-subject cost and budgets

Read the settled cost of a call

Attribute a call to a subject

Read a subject’s rolling spend

Enforce budgets and rate limits

What Happens When Credits Run Out

End-to-End Example

Switching Providers and Models

Verify and troubleshoot

Next Steps

​Before you begin

​How It Works

​Endpoints

​Base URLs for clients

​Credit Tiers

​Activate Managed Mode

​With the CLI

​Inside a Workspace VM

​Check Your Credit Balance

​View Usage Breakdown

​Per-subject cost and budgets

​Read the settled cost of a call

​Attribute a call to a subject

​Read a subject’s rolling spend

​Enforce budgets and rate limits

​What Happens When Credits Run Out

​End-to-End Example

​Switching Providers and Models

​Verify and troubleshoot

​Next Steps

Before you begin

How It Works

Endpoints

Base URLs for clients

Credit Tiers

Activate Managed Mode

With the CLI

Inside a Workspace VM

Check Your Credit Balance

View Usage Breakdown

Per-subject cost and budgets

Read the settled cost of a call

Attribute a call to a subject

Read a subject’s rolling spend

Enforce budgets and rate limits

What Happens When Credits Run Out

End-to-End Example

Switching Providers and Models

Verify and troubleshoot

Next Steps