--- title: "Pi provider templates" description: "Which model providers can Orbi run on?" --- Orbi can run with the model providers represented by its Pi `models.json`-shaped templates and an OpenAI-compatible endpoint. Issue #309 ships one complete `pi_providers` file per provider in [`templates/pi-providers`](https://github.com/orbi-build/orbi/tree/main/templates/pi-providers). Each file is valid JSON in Pi's `models.json` shape: copy the whole file to `.orbi/pi-providers.json`, or copy its single entry into the `providers` object of an existing file. Set the two selectors in `orbi.toml`: ```toml pi_providers = ".orbi/pi-providers.json" pi_provider = "z-ai" pi_model = "glm-5.3-flash" ``` ## Catalog | Provider | Template | Environment variable | Model | Status | #305 link | | --- | --- | --- | --- | --- | --- | | Google Gemini | `gemini.json` | `GOOGLE_API_KEY` | `gemini-3.8-flash` | Tested 2026-09-04: full Pi chain passed in 7s | [#305](https://github.com/orbi-build/orbi/issues/305) | | z.ai GLM | `z-ai.json` | `ZAI_API_KEY` | `glm-5.3-flash` | Tested 2026-09-04: real task #303 reached PR #304 | [#305](https://github.com/orbi-build/orbi/issues/305) | | OpenRouter free | `openrouter.json` | `OPENROUTER_API_KEY` | `google/gemma-4-31b-it:free` | Observed 2026-09-08: real Gemma request returned upstream-shared-pool HTTP 429; North Mini Code returned HTTP 200 | [#305](https://github.com/orbi-build/orbi/issues/305) | | DeepSeek | `deepseek.json` | `DEEPSEEK_API_KEY` | `deepseek-flash` | Used for Orbi's own deliveries since 2026-09-22 (e.g. [#1328](https://github.com/orbi-build/orbi/issues/1328)); [pricing](https://api-docs.deepseek.com/quick_start/pricing) | [#305](https://github.com/orbi-build/orbi/issues/305) | | xAI | `xai.json` | `XAI_API_KEY` | `grok-4.20-0309-reasoning` | Model ID verified against xAI docs 2026-09-09; not quota-tested | [#305](https://github.com/orbi-build/orbi/issues/305) | | Groq Free Plan | `groq.json` | `GROQ_API_KEY` | `groq/compound` | Free Plan limits verified 2026-09-04; real request/usage/429 not tested | [#305](https://github.com/orbi-build/orbi/issues/305) | | Local Qwen | `local-qwen.json` | None (dummy key `local`) | `Qwen3.8-27B` | Local zero-cost example; requires a local OpenAI-compatible server | [#305](https://github.com/orbi-build/orbi/issues/305) | | Cloudflare Workers AI (`cf-workers`) | `cloudflare-workers-ai.json` | `CLOUDFLARE_API_TOKEN` | `@cf/meta/llama-3.1-8b-instruct-fp8` | Hosted free allocation; quota must be checked in the account | [#318](https://github.com/orbi-build/orbi/issues/318) | | GitHub Models | `github-models.json` | `GH_MODELS_TOKEN` | `openai/gpt-4.1-mini` | Historical snapshot; service retired and not available for live requests | [#319](https://github.com/orbi-build/orbi/issues/319) | A template being listed is not a promise of quota, availability, speed, or model support. The `Not tested` labels are intentional. ### DeepSeek: the configuration Orbi's own deliveries run on DeepSeek's [pricing page](https://api-docs.deepseek.com/quick_start/pricing) (checked 2026-09-26) lists two API model ids with a 1M context, `deepseek-flash` (DeepSeek-V4.1-Flash) and `deepseek-v4-pro`. The committed template pins `deepseek-flash` with the model's full `contextWindow` 1,000,000 and `maxTokens` 16,384, and Orbi's own deliveries have selected it since **2026-09-22** (e.g. source Issue [#1328](https://github.com/orbi-build/orbi/issues/1328)). Use the full window. Pi compacts a session once `contextTokens` exceeds `contextWindow` minus `reserveTokens` (16,384 by default), and keeps only about 20,000 recent tokens. A 131,072 window therefore compacted at roughly 114.7K tokens, and **32 of the 77 delivery sessions since 2026-09-22 (42%)** carry a `"type":"compaction"` entry. A compacted delivery loses the files it read and the test output it saw, so it re-reads and re-runs; the full 1M window avoids those extra rounds. Cached input is billed far below uncached input, which is why this default model stays cheap for Orbi's cache-heavy sessions; the pricing page carries the current numbers, which change. ### xAI: Grok 4.20 Reasoning The xAI model catalog was checked on **2026-09-09**. Select the exact reasoning variant from the template: ```toml pi_providers = ".orbi/pi-providers.json" pi_provider = "xai" pi_model = "grok-4.20-0309-reasoning" ``` The catalog reports a 1,000,000-token maximum prompt length for this model. This template uses that value as `contextWindow` and keeps `maxTokens` at 16,384 as a conservative request cap. xAI quota and a real request were **not tested**; consult the [official xAI model catalog](https://docs.x.ai/docs/models) and your account when configuring a run. ### OpenRouter `:free`: one key, multiple models OpenRouter exposes many zero-price models behind one OpenAI-compatible endpoint. This is a configuration guide, not a promise that a model will remain listed or that a request is free of rate limits. The catalog is dynamic; the [official zero-price catalog](https://openrouter.ai/models?max_price=0) is the source of truth. The `:free` catalog snapshot used for this guide was checked on **2026-09-08** and reported 16 models. Named examples from that snapshot were: `nvidia/nemotron-3-ultra-550b-a55b:free`, `nvidia/nemotron-3-super-120b-a12b:free`, `nvidia/nemotron-3.5-lightning:free`, `google/gemma-4-31b-it:free`, `cohere/north-mini-code:free`, `thinkingmachines/inkling:free`, `inclusionai/ling-3.0-flash-fin:free`, `poolside/laguna-s-2.1:free`, and `liquid/lfm-2.5-2.6b:free`. Model IDs are shown exactly as they must appear in `models[].id`; the catalog is dynamic, so re-check every ID before selecting it. Do not paste a key into the provider file. Copy the Issue #309 template, then add the exact model IDs you intend to select to its `models` list. Keep the same endpoint, API, and key reference: ```bash mkdir -p .orbi cp templates/pi-providers/openrouter.json .orbi/pi-providers.json printf '%s\n' 'OPENROUTER_API_KEY=replace-me' > .orbi/env chmod 600 .orbi/env ``` ```json { "providers": { "openrouter": { "baseUrl": "https://openrouter.ai/api/v1", "api": "openai-completions", "apiKey": "$OPENROUTER_API_KEY", "models": [ {"id": "google/gemma-4-31b-it:free", "name": "Gemma 4 31B (free)"}, {"id": "cohere/north-mini-code:free", "name": "North Mini Code (free)"} ] } } } ``` The template's selected model is `google/gemma-4-31b-it:free`. Select any ID that is actually present in your copied file; the Runner validates the provider, endpoint, API, model list, and `$OPENROUTER_API_KEY` reference before dispatch: ```toml pi_providers = ".orbi/pi-providers.json" pi_provider = "openrouter" pi_model = "cohere/north-mini-code:free" ``` Do not add `thinkingLevelMap` unless the selected model's current Pi/OpenRouter contract has been verified. If it is needed, use the model-specific mapping documented by that contract; this guide does not invent one. For task selection, prefer `cohere/north-mini-code:free` for small code/search tasks, `nvidia/nemotron-3-ultra-550b-a55b:free`, `nvidia/nemotron-3-super-120b-a12b:free`, or `nvidia/nemotron-3.5-lightning:free` for longer reasoning when available, and Gemma, Ling, or LFM for lightweight experiments. These are practical suggestions, not benchmark results. #### Limits, requests, and 429 status OpenRouter's official [rate-limit documentation](https://openrouter.ai/docs/api/reference/limits) states a shared free-model policy of approximately **20 requests/day** for accounts without the required credits and up to **1,000 requests/day** for eligible accounts; the exact policy, model availability, and account eligibility can change. These are policy-level limits, not per-model measurements. The 2026-09-08 snapshot did not provide a separately verified daily number for each of the 16 models, so each model's measured daily limit is **not tested**. On **2026-09-08**, two real requests using the original template and Pi 0.85.1 produced concrete evidence: `google/gemma-4-31b-it:free` returned HTTP **429** twice, about two minutes apart, with `temporarily rate-limited upstream` and `limit_source: upstream_provider_shared_pool`; `cohere/north-mini-code:free` returned HTTP **200** with `ok`. The 429 remedy was to retry later, bind a personal provider key, or switch provider route/model. This shows that a 429 can be transient upstream shared-pool limiting, not proof that the daily allowance is exhausted. A transient 429 is retried in-run with bounded backoff since [#321](https://github.com/orbi-build/orbi/issues/321) (the `pi_retry_429` journal lines — never silent); Orbi does not automatically rotate models — for a 429 that survives every retry, preserve the failed run evidence and manually select another configured model. Automatic quota classification (`quota_exhausted`) belongs to [#313](https://github.com/orbi-build/orbi/issues/313) and is not implemented by this documentation or template. ## Add a new provider 1. Copy the closest template and give it one provider id. Keep `baseUrl`, `api`, `apiKey`, and a non-empty `models` list together. The selected `pi_model` **must exactly match** one `models[].id`. 2. Use `openai-completions` for OpenAI-compatible endpoints. Google Gemini uses `google-generative-ai`; keep its `baseUrl` at `https://generativelanguage.googleapis.com/v1beta`. 3. Put the real key in `.orbi/env` (gitignored, mode `600`) and use only `$VAR` or `${VAR}` in the committed JSON: ```bash mkdir -p .orbi printf '%s\n' 'ZAI_API_KEY=replace-me' > .orbi/env chmod 600 .orbi/env ``` The installed `orbi@.service` loads this file through `EnvironmentFile`; it never belongs in Git or a template. Literal keys are a last-resort downgrade: keep the file gitignored and understand that the value can leak through local files and process tooling. 4. For a manual tick, systemd is not loading `.orbi/env`. Export it first, or source it into the current shell: ```bash set -a . .orbi/env set +a PYTHONPATH=src python3 -m orbi.runner --config orbi.toml ``` 5. Select only the provider/model in `orbi.toml`; do not maintain commented provider blocks there. Validate before a real task with `orbi check --config orbi.toml` — it sends no real request and fails fast when the selected provider, model, endpoint, API, or selected key reference is invalid. A bare `pi --print` is **not** this check: it runs Pi with its own agent directory (`~/.pi/agent`, or `PI_CODING_AGENT_DIR` when set) and never reads `pi_providers`, which reaches Pi only through the per-run agent directory Orbi materializes. The first real request happens in the first run; follow it with `orbi status --follow`. ### `thinkingLevelMap` Do not invent a complete map for a provider. Gemini's known-safe template form is exactly `{"off": null}`: other thinking levels use the provider default mapping. A copied `null` mapping for every level can send an unsupported value and produce a provider `400`. For another provider, omit the field unless its Pi provider contract has been verified. ### Google Gemini: AI Studio free tier Use Google's [AI Studio API key page](https://aistudio.google.com/app/apikey) to create an API key. Keep the key local: the committed template references `GOOGLE_API_KEY`, so the literal value never belongs in Git, an Issue, a PR, or a journal. 1. Create or select a key in AI Studio, then add it to the gitignored environment file used by Orbi: ```bash mkdir -p .orbi printf '%s\n' 'GOOGLE_API_KEY=replace-me' > .orbi/env chmod 600 .orbi/env ``` The installed systemd unit loads `.orbi/env`. For a manual tick, export it first as described in [Getting started](/getting-started#path-b-a-pi_providers-file-orbi-manages-the-selection). 2. Copy [`templates/pi-providers/gemini.json`](https://github.com/orbi-build/orbi/blob/main/templates/pi-providers/gemini.json) to `.orbi/pi-providers.json`. Its complete selected entry is: ```json { "providers": { "google": { "baseUrl": "https://generativelanguage.googleapis.com/v1beta", "api": "google-generative-ai", "apiKey": "$GOOGLE_API_KEY", "models": [ { "id": "gemini-3.8-flash", "name": "Gemini 3.8 Flash", "contextWindow": 1048576, "maxTokens": 65536, "thinkingLevelMap": {"off": null} } ] } } } ``` 3. Select the exact provider and model in `orbi.toml`: ```toml pi_providers = ".orbi/pi-providers.json" pi_provider = "google" pi_model = "gemini-3.8-flash" ``` The `api`, `baseUrl`, model ID, and `$GOOGLE_API_KEY` reference are part of the validated template. Keep Gemini's `thinkingLevelMap` exactly as `{"off": null}` unless the installed Pi/Gemini contract is re-verified; mapping every thinking level to `null` can cause an upstream `400`. #### Free-tier limits and observed behavior As checked on **2026-09-04**, AI Studio's Gemini API free tier is rate-limited by RPM, RPD, and TPM. The official [rate-limit page](https://ai.google.dev/gemini-api/docs/rate-limits) is dynamic, so this guide does not copy a changing promotional number. The real daily RPD/TPD ceiling for this account was **not measured**; treat it as **not tested**, not as unlimited. A local setup using provider `google` and model `gemini-3.8-flash` started a real Pi request in about 15 seconds. After a burst, the upstream returned HTTP `429` with `You exceeded your current quota`; after roughly 50 minutes it returned HTTP `200` again. This dated observation indicates transient rate limiting, not proof that the key was invalid or that the daily allowance was exhausted. It is one account's evidence, not a quota guarantee. Orbi never switches providers mid-session; a transient 429 is retried in-run with bounded backoff (Issue #321 — the `pi_retry_429` journal lines, never silent), and a 429 that survives every retry still fails the run. Preserve the failed run evidence, or manually select another configured provider for the next run: ```toml pi_providers = ".orbi/pi-providers.json" pi_provider = "z-ai" # or another provider in the catalog pi_model = "glm-5.3-flash" ``` Replace the provider file and matching environment variable, validate the exact provider/model/key again with `orbi check --config orbi.toml` (see [Add a new provider](#add-a-new-provider) step 5), and then run the first Issue — that run makes the first real request. Switching is manual; the automatic per-provider rotation tracked in [#313](https://github.com/orbi-build/orbi/issues/313) is not current behavior. ### z.ai GLM: experience/free quota Use this path when you have a z.ai account with an experience or free allowance. z.ai documents an OpenAI-compatible API; Orbi's template uses the direct endpoint `https://api.z.ai/api/paas/v4` and Pi's `openai-completions` API. See z.ai's [API quick start](https://docs.z.ai/guides/overview/quick-start) and [API-key management](https://z.ai/manage-apikey/apikey-list) for the current account and key-creation flow. The links and UI may change; do not paste the key into a repository, Issue, PR, or journal. 1. Create an API key in the z.ai console, then keep it in the local, gitignored environment file: ```bash mkdir -p .orbi printf '%s\n' 'ZAI_API_KEY=replace-me' > .orbi/env chmod 600 .orbi/env ``` The systemd service loads this file through `EnvironmentFile`. A manual tick does not: export it first with `set -a; . .orbi/env; set +a`, then run the command in [Getting started](/getting-started#6-run-one-tick-manually). 2. Copy [`templates/pi-providers/z-ai.json`](https://github.com/orbi-build/orbi/blob/main/templates/pi-providers/z-ai.json) to `.orbi/pi-providers.json`, or copy its provider entry. Select the exact IDs: ```toml pi_providers = ".orbi/pi-providers.json" pi_provider = "z-ai" pi_model = "glm-5.3-flash" ``` The complete `models` entry currently is: ```json { "id": "glm-5.3-flash", "name": "GLM 5.3 Flash", "contextWindow": 131072, "maxTokens": 32768 } ``` `reasoning` is an optional Pi model-catalog field indicating reasoning support. `thinkingLevelMap` maps Pi thinking levels to provider-specific values. The committed z.ai template intentionally omits both: this document does not assert a provider-specific reasoning or thinking-level mapping without verified Pi/z.ai contract evidence. Do not copy Gemini's `{"off": null}` mapping to z.ai. 3. Validate the selected entry before dispatching work. The Runner's `_load_pi_providers` check requires the provider, exact model ID, endpoint/API, and a non-empty `ZAI_API_KEY`; it does not test or promise quota availability. #### What is known about the free allowance - **Verified 2026-09-04:** a real Orbi delivery using `glm-5.3-flash` completed the task from Issue [#303](https://github.com/orbi-build/orbi/issues/303) through commit [`b81f77a`](https://github.com/orbi-build/orbi/commit/b81f77a) and PR [#304](https://github.com/orbi-build/orbi/pull/304). This proves one successful run, not a quota guarantee. - z.ai does not statically publish a universal experience/free upper limit in the material used for this guide. Exact allowance, reset time, concurrency and model availability depend on the account and current z.ai policy; **not measured here**. - No controlled measurement of exhaustion or rate-limit response is available for this guide; **rate-limit behavior: not tested**. Treat upstream HTTP authentication/rate-limit errors as the source of truth and avoid retry loops or invented numbers. #### Switch when the allowance is exhausted There is no automatic fallback. Keep the same `orbi.toml` selector fields, but change `pi_provider` and `pi_model` to match another provider from the [catalog](#catalog); replace the provider file/key, then validate again. For example, switch to the existing OpenRouter template and its selected model: ```toml pi_providers = ".orbi/pi-providers.json" pi_provider = "openrouter" pi_model = "google/gemma-4-31b-it:free" ``` Copy [`openrouter.json`](https://github.com/orbi-build/orbi/blob/main/templates/pi-providers/openrouter.json), set `OPENROUTER_API_KEY` in `.orbi/env`, and validate the selection with `orbi check --config orbi.toml` before dispatching. OpenRouter model availability and quota are **not tested or promised** beyond the dated evidence above; re-check the live catalog before selecting a model. ### Cloudflare Workers AI Cloudflare's OpenAI-compatible endpoint is account-scoped. Copy [`cloudflare-workers-ai.json`](https://github.com/orbi-build/orbi/blob/main/templates/pi-providers/cloudflare-workers-ai.json), replace `REPLACE_WITH_ACCOUNT_ID` in `baseUrl` with the Cloudflare account ID, and create an API token with both the `Workers AI - Read` and `Workers AI - Edit` permissions (the permissions required by Cloudflare's REST API guide). The template uses the custom Pi provider id `cf-workers` so Pi does not apply its native Cloudflare credential handling. Keep the token in `.orbi/env`: ```bash printf '%s\n' 'CLOUDFLARE_API_TOKEN=replace-me' >> .orbi/env chmod 600 .orbi/env ``` Select it in `orbi.toml`: ```toml pi_providers = ".orbi/pi-providers.json" pi_provider = "cf-workers" pi_model = "@cf/meta/llama-3.1-8b-instruct-fp8" ``` The model ID is the current FP8 variant documented in Cloudflare's [Workers AI model catalog](https://developers.cloudflare.com/workers-ai/models/llama-3.1-8b-instruct-fp8/); the endpoint path is from the [Workers AI configuration guide](https://developers.cloudflare.com/workers-ai/configuration/). Cloudflare's [official pricing page](https://developers.cloudflare.com/workers-ai/platform/pricing/) documents **10,000 Neurons per day at no charge**, resetting at **00:00 UTC** (information checked 2026-09-04). After the free allocation, further operations fail unless billing is enabled. Limits and pricing can change, so check the official pages before a run. #### Measure a real Orbi task Record the Workers AI account's Neurons usage immediately before dispatching one Issue and immediately after the PR is opened (same UTC day). The measured task consumption is `after - before`; retain the dashboard/API timestamps, model, Issue and PR URL, but never retain the token. Orbi's journal proves the selected provider/model, not Neurons usage. **This repository has not run a Cloudflare-account-backed Orbi task; the request and Neurons consumption are not tested and must not be inferred.** ```text journal: [] provider_config_loaded issue=OWNER/REPO# role=implement provider=cf-workers model=@cf/meta/llama-3.1-8b-instruct-fp8 elapsed= Cloudflare Workers AI usage: before= neurons at , after= neurons at , delta= PR: https://github.com/OWNER/REPO/pull/ ``` #### Hosted versus local Qwen Workers AI is hosted: Cloudflare provides inference and the account's Neurons allocation, so it is convenient for a machine without a capable GPU but depends on network access, account quota and Cloudflare model availability. `local-qwen` is self-hosted: it avoids provider quota and sends requests to a local OpenAI-compatible server, but the operator supplies the hardware, model runtime and electricity. Use Cloudflare for lightweight hosted execution; use local Qwen when data locality and predictable local availability matter. ### Local providers A local OpenAI-compatible server still needs a non-empty `apiKey` field to satisfy the provider shape; the local template uses the non-secret dummy value `local`. Its model id must match the server's advertised id (for llama.cpp, set it with `--alias`). ### GitHub Models: historical free-prototyping snapshot This section records the GitHub Models prototype configuration as it was documented on 2026-09-04. GitHub's official endpoint currently returns a retirement response (`410`); GitHub Models is not available for live requests. The template remains for historical/reference purposes and must not be presented as a working provider. The former free allowance was a GitHub Models service limit, not an Orbi or Copilot entitlement. The following is the historical setup (do not create a token or dispatch a live task against it while the service is retired): 1. Create a fine-grained personal access token in [GitHub token settings](https://github.com/settings/personal-access-tokens). Grant the token the **Models: read** permission. Keep it local; do not paste it into Git, an Issue, a PR, or a journal: ```bash mkdir -p .orbi printf '%s\n' 'GH_MODELS_TOKEN=replace-me' > .orbi/env chmod 600 .orbi/env ``` 2. Copy [`templates/pi-providers/github-models.json`](https://github.com/orbi-build/orbi/blob/main/templates/pi-providers/github-models.json) to `.orbi/pi-providers.json`, then select the exact IDs: ```toml pi_providers = ".orbi/pi-providers.json" pi_provider = "github-models" pi_model = "openai/gpt-4.1-mini" ``` The template uses `https://models.github.ai/inference`, Pi's `openai-completions` API, and `$GH_MODELS_TOKEN`. Validate the selected entry with the Runner before dispatching a task; validation checks shape and the key reference, not account access or quota. #### Model catalog and limits (checked 2026-09-04) The [official GitHub Models catalog](https://models.github.ai) was dynamic at the time of the snapshot. The following model IDs were listed when this guide was checked: `openai/gpt-4.1`, `openai/gpt-4.1-mini`, `openai/gpt-4o`, `openai/o4-mini`, `meta/llama-3.3-70b-instruct`, `meta/llama-4-scout-17b-16e-instruct`, `microsoft/phi-4`, `mistral-ai/mistral-small-2503`, `deepseek/DeepSeek-R1`, and `xai/grok-3-mini`. Availability can differ by account and can change without a repository change. `openai/gpt-4.1-mini` is the example pinned in the committed template. | Model | Daily free limit | Status | | --- | --- | --- | | `openai/gpt-4.1` | Not published as a stable per-model number on the checked dynamic page | Not measured | | `openai/gpt-4.1-mini` | Not published as a stable per-model number on the checked dynamic page | Not measured | | `openai/gpt-4o` | Not published as a stable per-model number on the checked dynamic page | Not measured | | `openai/o4-mini` | Not published as a stable per-model number on the checked dynamic page | Not measured | | `meta/llama-3.3-70b-instruct` | Not published as a stable per-model number on the checked dynamic page | Not measured | | `meta/llama-4-scout-17b-16e-instruct` | Not published as a stable per-model number on the checked dynamic page | Not measured | | `microsoft/phi-4` | Not published as a stable per-model number on the checked dynamic page | Not measured | | `mistral-ai/mistral-small-2503` | Not published as a stable per-model number on the checked dynamic page | Not measured | | `deepseek/DeepSeek-R1` | Not published as a stable per-model number on the checked dynamic page | Not measured | | `xai/grok-3-mini` | Not published as a stable per-model number on the checked dynamic page | Not measured | This repository has not made a real GitHub Models request or measured exhaustion, reset, or HTTP 429 behavior. The service is currently retired, so this historical snapshot is not a live-run guide. Treat every quota and model-availability claim as **not measured**; consult GitHub's current documentation before relying on any successor service. #### GitHub Models versus Copilot A GitHub Models PAT and its free prototyping allowance are separate from a GitHub Copilot subscription, Copilot requests, and Copilot premium-request allowance. Having Copilot does not establish GitHub Models quota, and GitHub Models usage does not consume Copilot subscription requests. Billing, eligibility, rate limits, and reset rules are controlled by the current GitHub Models terms; check the official pages rather than assuming the two products share a counter. ## Sign in with ChatGPT: use a ChatGPT Plus/Pro plan Pi's native `openai` provider supports **Sign in with ChatGPT**: an eligible ChatGPT Plus/Pro account authorizes the Pi CLI once, and Orbi then runs deliveries against the user's ChatGPT plan usage and credits — **not** OpenAI API billing. This needs no `pi_providers` file and no `OPENAI_API_KEY`; Orbi's per-run Pi agent directory reuses Pi's native `~/.pi/agent/auth.json`. No ChatGPT Plus/Pro account was available for this delivery. The login menu wording, the callback, the credential file, and the OAuth scopes were verified against the Pi CLI package (`@earendil-works/pi-coding-agent` **0.99.1**) and OpenAI's Sign in with ChatGPT documentation; the end-to-end sign-in, plan quota, model availability for a particular account, and the resulting Orbi run were **not tested**. Do not read the examples below as a promise of available capacity for your plan. This path needs **Pi ≥ 0.99.1**. The installed Pi in the documented environment is **0.85.1**, which has no Sign in with ChatGPT flow: 0.99.0 already carries the `openai` OAuth mode but not the bundled flow, and 0.99.1 is the first release that ships it complete (`dynamic_agent_client` registration, the `chatgpt.tokens.use.direct` scope, and the `/auth/callback` listener). Upgrade Pi first. ### First login: do this in order 1. Start an interactive Pi session with `pi`. 2. At the Pi prompt, run **`/login openai`**. Pi asks `Select authentication method for OpenAI:` — choose **Sign in with ChatGPT** (the subscription path; the other option is **Sign in with an API key**). A bare `/login` without the provider argument asks `Select authentication method:` first: choose **Sign in with an account**, which then lists the provider **OpenAI**. 3. Complete the consent in the browser and approve this app's access to your ChatGPT plan. 4. Verify the login before configuring Orbi: ```bash pi auth check --provider openai --model --json ``` A successful check reports: ```text {"status":"ready","provider":"openai","authType":"oauth"} ``` `"authType":"oauth"` proves the stored ChatGPT OAuth credential is in use. If it instead reports `"authType":"api_key"`, Pi found an `OPENAI_API_KEY`; a stored OAuth credential normally wins, but remove the variable from `.orbi/env` if you want an unambiguous subscription-only setup. This command refreshes expired OAuth credentials by default; do not use `--credentials` in a shared terminal or transcript. ### Minimal Orbi configuration Leave `pi_providers` **unset** — the `openai` provider is native to Pi. Do not create an `openai` entry in a provider JSON file. ```toml source_repos = ["OWNER/YOUR-REPO"] repo_dir = "/path/to/your-repo" deploy_home = "/path/to/orbi" workspace_root = "/path/to" base_branch = "main" max_concurrency = 1 # No pi_providers = ... line. pi_provider = "openai" pi_model = "" ``` ### Choose a model the account can use Model availability depends on the account, so read it from OpenAI's model list with the OAuth access token instead of guessing a slug: `GET https://api.openai.com/v1/models` returns a `models` array of the models the account may call, and the entries this flow supports carry `visibility: "list"`. Use that entry's `slug` as `pi_model`. ```bash ACCESS_TOKEN=$(jq -r '.openai.access' ~/.pi/agent/auth.json) curl -sS https://api.openai.com/v1/models \ -H "Authorization: Bearer $ACCESS_TOKEN" \ | jq -r '.models[] | select(.visibility == "list") | .slug' ``` `$ACCESS_TOKEN` is the OAuth access token Pi stored for the `openai` provider in `~/.pi/agent/auth.json` (field `access`); do not put a token into a shared shell history or a transcript. Set `pi_thinking` only to a level the chosen model actually supports. ### How this differs from the Codex OAuth section Both paths use a ChatGPT subscription and need no `pi_providers` file, but they are different providers and endpoints: - **Sign in with ChatGPT** uses Pi's native `openai` provider against the public Responses API at `https://api.openai.com/v1`. That is the path OpenAI documents for ChatGPT Plus/Pro plan usage, and the one to prefer for a new Orbi install. - **Codex OAuth** uses Pi's native `openai-codex` provider against `https://chatgpt.com/backend-api` (the Codex app-server route). It remains the correct path for an existing Codex setup. Use one provider per Orbi install; do not configure both selectors. ### Headless and server installs Pi listens for the OAuth redirect on `http://127.0.0.1:1455/auth/callback` and opens the system browser on the machine running Pi. When no browser can reach that listener (a remote VM, a container), Pi prompts: "Complete login in your browser, or paste the final redirect URL here:" — complete the sign-in in a browser, copy the final `http://127.0.0.1:1455/auth/callback?code=...` URL, and paste it into the Pi prompt. Alternatively, sign in once on a machine that has a browser and copy the credential file (Pi writes it with mode `0600`): ```bash ssh user@vm 'mkdir -p ~/.pi/agent' scp -p ~/.pi/agent/auth.json user@vm:~/.pi/agent/auth.json ``` Follow OpenAI's [self-hosted VM guidance](https://developers.openai.com/siwc/token-sharing-open-source/self-hosted-vms) for the host identity: Pi derives its host ID from the device ID in `~/.pi/agent/settings.json`, so keep each VM's own agent directory identity unless you deliberately want the copied host. The refresh token stays valid for 30 days and is replaced on each refresh, so the copied file keeps working while the VM renews it. ### Quota and billing boundary Per OpenAI's [Sign in with ChatGPT documentation](https://developers.openai.com/siwc/token-sharing-open-source): sign-in authorizes AI requests that count against the user's **ChatGPT plan and credits**, not OpenAI API billing, and OpenAI does not silently move a request to another billing path. For ChatGPT **Plus** the five-hour usage limit is shared across every app that uses the plan — usage in one app contributes to the same total — and it does not apply to Pro. Users review app usage, set each app's weekly limit (10%–100%), and choose whether it may use credits after plan limits at [ChatGPT Settings → Usage](https://chatgpt.com/settings/usage); Pi registers `agent_name_hint="Pi"`, so the app appears there as **Pi**. These are OpenAI's plan rules, not an Orbi guarantee; check the current documentation before relying on a quota. ### Failure paths and repair actions - **Plan usage limit reached.** OpenAI returns `subscription_sharing_usage_limit_exceeded` (HTTP `429`) or `subscription_sharing_usage_unavailable` (HTTP `503`). The Pi session fails, Orbi logs the error and marks the Issue `ai-blocked`. Repair: wait for the shared limit to reset, adjust the app's limit in ChatGPT Settings → Usage, or switch to another configured provider. Orbi never falls back to API billing. - **Permission not granted.** If the consent screen did not grant plan usage, Pi fails with `OpenAI OAuth grant did not include chatgpt.tokens.use.direct`. Repair: run `/login openai` again and approve the plan-usage permission. - **Stale or revoked session.** An expired refresh token (30 days idle), a disconnected app in ChatGPT settings, or an auth error in the Pi session means the credential must be renewed. Repair: run `/login openai` again. Switching providers does not repair a broken ChatGPT session. Never put the OAuth token or `auth.json` into the repository, an Issue, a PR body, or a journal. ### Evidence boundary This section documents the contract, not a verified run. The exact login wording, the `pi auth check` JSON shape, `http://127.0.0.1:1455/auth/callback`, the `0600` `~/.pi/agent/auth.json`, `agent_name_hint="Pi"`, and the `chatgpt.tokens.use.direct` scope were verified against `@earendil-works/pi-coding-agent` 0.99.1; the model-list endpoint, quota rules, and error codes come from OpenAI's Sign in with ChatGPT documentation. The sign-in, quota, model availability for a given account, and the resulting Orbi run are **not tested** here. After you sign in, retain only non-secret evidence of a real Issue run (the journal `provider_config_loaded` line, which carries the configured provider/model, plus the PR URL and elapsed time), never the tokens or the session JSONL. ## Codex OAuth: use a ChatGPT/Codex subscription This path uses Pi's native `openai-codex` provider and OAuth credentials. It does **not** use `OPENAI_API_KEY` and it does **not** need a second `pi_providers` JSON file. It is subscription/Codex quota, not OpenAI API billing. ### First login: do this in order 1. Start an interactive Pi session with `pi`. 2. At the Pi prompt, run **`/login codex`**. 3. Complete the Codex OAuth authorization in the browser. 4. Return to Pi and verify the login with the command supported by the current Pi CLI: ```bash pi auth check --provider openai-codex --model gpt-5.6-luna --json ``` A successful check reports `"status":"ready"` and `"authType":"oauth"`. This command refreshes expired OAuth credentials by default; do not use `--credentials` in a shared terminal or transcript. 5. Only after the check succeeds, configure Orbi and run a real Issue. ### Minimal Orbi configuration Delete `pi_providers` if it exists; leave it **unset**. Do not copy or create an `openai-codex` provider entry. Pi supplies the catalog from its own `models.json`, and Orbi's per-run agent directory reuses Pi's native auth. ```toml source_repos = ["OWNER/YOUR-REPO"] # The Orbi checkout supplies the CLI, prompts, labels, and systemd templates. repo_dir = "/path/to/your-repo" deploy_home = "/path/to/orbi" workspace_root = "/path/to" base_branch = "main" max_concurrency = 1 # No pi_providers = ... line. pi_provider = "openai-codex" pi_model = "gpt-5.6-luna" ``` Pi's catalog checked on **2026-09-08** lists this model as `openai-codex-responses` at `https://chatgpt.com/backend-api`, with reasoning enabled, text/image input, a 272,000-token context window, and a 128,000-token output limit. Its catalog thinking map supports `minimal → low`, `xhigh → xhigh`, and `max → max`; leave `pi_thinking` unset for the default, or set one of those verified levels. These are Pi request limits, not a promise about subscription quota. The 1,000,000-token context capability is a product-side capability of `gpt-5.6-sol`, not `gpt-5.6-luna`; Pi's current catalog also lists `sol` at 272,000 tokens, so Orbi's actual routing follows the Pi catalog. If selecting `sol`, verify the catalog again at that time. ### Quota and billing boundary The OAuth credential consumes the user's Codex/ChatGPT subscription allowance. It is separate from an OpenAI API key, API organization billing, and any `OPENAI_API_KEY` balance. Pi's catalog `cost` fields are routing metadata, **not a bill or quota counter**. Allowance, reset time, rate limits, model availability, and error messages depend on the account plan and can change. The 2026-09-05 real-run evidence was from one local account; the account plan and its exact allowance were not recorded, so this guide makes no universal quota claim. On exhaustion or throttling, expect an upstream auth/rate-limit failure in the Pi session and consult the account's current Codex UI/help; do not infer remaining quota from the catalog. ### Real Issue evidence to retain Run the first Issue in the user's own repository, then retain the non-secret evidence. A successful run should show all of these: ```text journal: [] provider_config_loaded issue=OWNER/YOUR-REPO# role=implement provider=openai-codex model=gpt-5.6-luna elapsed= PR: https://github.com/OWNER/YOUR-REPO/pull/ elapsed: result: PR opened (then review/merge according to the normal Orbi flow) ``` `provider_config_loaded` is logged before Pi is spawned, so it carries the configured provider/model; the run id is the `[]` journal prefix, not a field of its own on these startup lines, and the line ends with `elapsed=`, the time since this session's setup began. Read it back with `journalctl --user -u 'orbi@*' | grep '\[\] provider_config_loaded'`; `-u` takes a unit pattern, which `man journalctl` documents as `-u, --unit=UNIT|PATTERN`. A redacted, non-secret record from the completed Orbi run for this guide (2026-09-07) is: ```text journal: [f3e26f87] provider_config_loaded issue=… role=implement provider=openai-codex model=gpt-5.6-luna elapsed=… PR: https://github.com/orbi-build/orbi/pull/487 elapsed: 4m 06s (09:11:18Z–09:15:24Z) result: PR opened ``` This is evidence of one local account and does not establish a quota guarantee; the account plan and exact allowance were not recorded. Never paste the session JSONL wholesale: redact credentials and prompts that contain secrets. ### Switch providers when quota or auth fails Remove or replace only the selectors. For a provider from an Orbi template, add its file back because the fallback is no longer Pi-native: ```diff -# no pi_providers line -pi_provider = "openai-codex" -pi_model = "gpt-5.6-luna" +pi_providers = ".orbi/pi-providers.json" +pi_provider = "local-qwen" # or "z-ai" +pi_model = "Qwen3.8-27B" # or the model id in that file ``` Use the matching template and secret setup in this guide; never put an OAuth token or API key in the repository, an Issue, a PR body, or a journal. For an auth failure, fix/re-login with `/login codex` first; switching providers does not repair an expired Codex session. ## Groq Free Plan Copy [`groq.json`](https://github.com/orbi-build/orbi/blob/main/templates/pi-providers/groq.json) as `.orbi/pi-providers.json`, then set the selectors and key reference: ```toml pi_providers = ".orbi/pi-providers.json" pi_provider = "groq" pi_model = "groq/compound" ``` The template uses Groq's OpenAI-compatible endpoint (`api: "openai-completions"`) and `$GROQ_API_KEY`; put the key in the gitignored `.orbi/env`, never in the JSON or a commit. According to Groq's [rate-limit table](https://console.groq.com/docs/rate-limits), the Free Plan row for `groq/compound` is **30 RPM / 250 RPD / 70K TPM** (checked 2026-09-04). These are account limits, not an Orbi guarantee; check the official table again before relying on them. The [model catalog](https://console.groq.com/docs/models) lists a 131,072-token context window and 8,192-token maximum completion for this model. The low TPM makes short, bounded coding Issues and small fixes a better fit than long-context repository analysis. A quota hit is returned upstream as HTTP `429`; Orbi never switches provider mid-session. A transient 429 is retried in-run with bounded backoff ([#321](https://github.com/orbi-build/orbi/issues/321) — the `pi_retry_429` journal lines, never silent); a 429 that survives every retry still fails the run: preserve the Issue/worktree evidence, and manually select another configured provider for the next run. The planned per-provider budget and automatic run-boundary rotation is tracked in [#313](https://github.com/orbi-build/orbi/issues/313); it is not yet a promise of current behavior. Real Groq requests, usage measurements, and 429 responses are **not tested** in this guide; do not claim a successful Groq Issue run without recording redacted evidence. A model can also be present in Groq's live catalog but blocked by an organization policy. In that case a real request returns HTTP `403` with `model_permission_blocked_org` (not `429`): an organization administrator must enable the model at [Groq organization limits](https://console.groq.com/settings/limits), or you must select another configured provider. HTTP `429` means the account quota/rate limit was reached; follow the separate quota troubleshooting path above. See [Getting started](/getting-started#path-b-a-pi_providers-file-orbi-manages-the-selection) for the existing OpenAI-compatible setup and [Issue #305](https://github.com/orbi-build/orbi/issues/305) for the provider article series.