> ## Documentation Index > Fetch the complete documentation index at: https://docs.rigbox.dev/llms.txt > Use this file to discover all available pages before exploring further. # Managed AI Proxy > Use Rigbox-provided AI credits without managing your own API keys. 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: 1. Intercepts the request from your workspace VM 2. Resolves the workspace from the VM's source IP on the compute bridge 3. Injects Rigbox's managed OpenRouter key (your VM never sees it) 4. Forwards the request to OpenRouter, which routes to the appropriate upstream provider for the requested model 5. Logs token usage and deducts from your credit balance 6. 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](#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](#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`: ```bash theme={null} rig workspace ai mode --workspace managed ``` Provider and model are account-level defaults — set them once with `rig ai defaults`: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} eval "$(rig proxy off)" ``` ## Check Your Credit Balance The fastest path is the CLI: ```bash theme={null} rig status ``` `rig status` prints your remaining credits, monthly total, current mode, and active workspaces. For programmatic access, see the [Credits API reference](/api-reference/ai/get-credits). ## View Usage Breakdown Get a daily breakdown of credit consumption across your workspaces. ```bash CLI theme={null} rig ai usage ``` ```json Response theme={null} { "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](/api-reference/ai/get-usage) 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.** ```bash Buffered theme={null} 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"}]}' ``` ```http Response headers + body theme={null} 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. ```bash theme={null} 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 ```bash theme={null} curl "http://172.16.0.1:9090/rig/v1/usage?subject=tenant-42&window=24h" ``` ```json theme={null} {"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](/api-reference/managed-proxy/get-subject-usage). ### 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: ```bash theme={null} 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: `;period=` | | `X-Rigbox-Subject-Rate` | repeatable | Sliding limit: `;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: ```json 429 subject_rate_limited theme={null} {"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}}} ``` ```json 402 subject_over_budget theme={null} {"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](/api-reference/managed-proxy/chat-completions). 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: 1. **API requests return HTTP 402** - the proxy rejects new managed AI calls until credits are available 2. **The UI shows an upgrade prompt** - you can upgrade to Pro or switch to [BYOK mode](/guides/byok) 3. **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:** ```bash theme={null} 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:** ```bash theme={null} # (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`: ```bash theme={null} 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: ```bash theme={null} # 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](/guides/ai-coding-tools) - use Rigbox credits with Claude Code, Codex, OpenCode, and Kilocode * [App Catalog](/guides/catalog#cli-shape-catalog-reference) - one-click install of the four CLI-shape agent recipes * [Bring Your Own Keys](/guides/byok) - use your own API keys for unlimited usage * [Setup Scripts](/guides/setup-scripts) - automate SDK installation in new workspaces * [Service Specs](/guides/service-specs) - run AI-powered services as background daemons