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.

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, AI SDK requests are routed through that bridge-local proxy, which fronts an OpenRouter gateway. The proxy:

Intercepts the request from your workspace VM
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. rig proxy on is still available inside the workspace shell to print equivalent export statements for use in 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. 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.

Credit Tiers

Every Rigbox account comes with AI credits that reset monthly.

Tier	Credits / Month	Best For
Free	250	Trying out the platform, small experiments
Pro	2,000	Active development, prototyping, demos

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

Provider and model are account-level defaults — set them once with rig ai defaults:

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

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)"

This command:

Prints shell export statements for OPENROUTER_BASE_URL and OPENROUTER_API_KEY (plus a small set of compatibility variables for SDKs that prefer provider-native names)
Uses managed-by-rigbox placeholder API keys where SDKs require a non-empty key and don’t read OPENROUTER_API_KEY
Routes subsequent AI SDK calls in that shell through the Rigbox proxy

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

To deactivate:

eval "$(rig proxy off)"

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 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 the credits endpoint always reflects the latest usage.

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.

Next Steps

AI Coding Tools - use Rigbox credits with Claude Code, Codex, OpenCode, and Kilocode
App Catalog - one-click install of the four CLI-shape agent recipes
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

Getting Started

Concepts

Deploying & hosting

AI, automation & data

CLI Reference

Integrations & tools

Build on Rigbox

How It Works

Endpoints

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

Next Steps

​How It Works

​Endpoints

​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

​Next Steps

How It Works

Endpoints

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

Next Steps