Pi provider templates

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. 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:

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
z.ai GLM	`z-ai.json`	`ZAI_API_KEY`	`glm-5.3-flash`	Tested 2026-09-04: real task #303 reached PR #304	#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
DeepSeek	`deepseek.json`	`DEEPSEEK_API_KEY`	`deepseek-flash`	Used for Orbi’s own deliveries since 2026-09-22 (e.g. #1328); pricing	#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
Groq Free Plan	`groq.json`	`GROQ_API_KEY`	`groq/compound`	Free Plan limits verified 2026-09-04; real request/usage/429 not tested	#305
Local Qwen	`local-qwen.json`	None (dummy key `local`)	`Qwen3.8-27B`	Local zero-cost example; requires a local OpenAI-compatible server	#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
GitHub Models	`github-models.json`	`GH_MODELS_TOKEN`	`openai/gpt-4.1-mini`	Historical snapshot; service retired and not available for live requests	#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 (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). 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:

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 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 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:

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

{
  "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:

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 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 (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 and is not implemented by this documentation or template.

Add a new provider

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.
Use openai-completions for OpenAI-compatible endpoints. Google Gemini uses google-generative-ai; keep its baseUrl at https://generativelanguage.googleapis.com/v1beta.
Put the real key in .orbi/env (gitignored, mode 600) and use only $VAR or ${VAR} in the committed JSON:
mkdir -p .orbi printf '%s\n' 'ZAI_API_KEY=replace-me' > .orbi/env chmod 600 .orbi/env
The installed [email protected] 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.
For a manual tick, systemd is not loading .orbi/env. Export it first, or source it into the current shell:
set -a . .orbi/env set +a PYTHONPATH=src python3 -m orbi.runner --config orbi.toml
Select only the provider/model in orbi.toml; do not maintain commented provider blocks there. Run the loader/runner validation before a real task. It fails fast when the selected provider, model, endpoint, API, or selected key reference is invalid.

`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 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.

Create or select a key in AI Studio, then add it to the gitignored environment file used by Orbi:
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.

Copy templates/pi-providers/gemini.json to .orbi/pi-providers.json. Its complete selected entry is:

{
  "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}
        }
      ]
    }
  }
}

Select the exact provider and model in orbi.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 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:

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, and then run one real pi --print check. Switching is manual; the automatic per-provider rotation tracked in #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 and API-key management 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.

Create an API key in the z.ai console, then keep it in the local, gitignored environment file:
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.
Copy templates/pi-providers/z-ai.json to .orbi/pi-providers.json, or copy its provider entry. Select the exact IDs:
pi_providers = ".orbi/pi-providers.json" pi_provider = "z-ai" pi_model = "glm-5.3-flash"
The complete models entry currently is:
{ "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.
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 through commit b81f77a and PR #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; replace the provider file/key, then validate again. For example, switch to the existing OpenRouter template and its selected model:

pi_providers = ".orbi/pi-providers.json"
pi_provider = "openrouter"
pi_model = "google/gemma-4-31b-it:free"

Copy openrouter.json, set OPENROUTER_API_KEY in .orbi/env, and run one real pi --print check 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, 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:

printf '%s\n' 'CLOUDFLARE_API_TOKEN=replace-me' >> .orbi/env
chmod 600 .orbi/env

Select it in orbi.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; the endpoint path is from the Workers AI configuration guide. Cloudflare’s official pricing page 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.

journal: provider=cf-workers model=@cf/meta/llama-3.1-8b-instruct-fp8 run_id=<run-id>
Cloudflare Workers AI usage: before=<n> neurons at <UTC>, after=<n> neurons at <UTC>, delta=<n>
PR: https://github.com/OWNER/REPO/pull/<number>

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

Create a fine-grained personal access token in GitHub token settings. Grant the token the Models: read permission. Keep it local; do not paste it into Git, an Issue, a PR, or a journal:
mkdir -p .orbi printf '%s\n' 'GH_MODELS_TOKEN=replace-me' > .orbi/env chmod 600 .orbi/env
Copy templates/pi-providers/github-models.json to .orbi/pi-providers.json, then select the exact IDs:
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 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. 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.

Start an interactive Pi session with pi.
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.
Complete the consent in the browser and approve this app’s access to your ChatGPT plan.
Verify the login before configuring Orbi:
pi auth check --provider openai --model <slug-from-your-model-list> --json
A successful check reports:
{"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.

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 = "<slug-from-your-model-list>"

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.

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

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 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: 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; 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 (journal provider=openai model=<slug> run_id=<id>, PR URL, 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.

Start an interactive Pi session with pi.
At the Pi prompt, run /login codex.
Complete the Codex OAuth authorization in the browser.
Return to Pi and verify the login with the command supported by the current Pi CLI:
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.
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.

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:

journal: provider=openai-codex model=gpt-5.6-luna run_id=<run-id>
PR: https://github.com/OWNER/YOUR-REPO/pull/<number>
elapsed: <duration>
result: PR opened (then review/merge according to the normal Orbi flow)

A redacted, non-secret record from the completed Orbi run for this guide (2026-09-07) is:

journal: provider=openai-codex model=gpt-5.6-luna run_id=f3e26f87
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:

-# 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 as .orbi/pi-providers.json, then set the selectors and key reference:

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, 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 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 — 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; 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, 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 for the existing OpenAI-compatible setup and Issue #305 for the provider article series.

Start here

Concepts

Model providers

Configure & run

Contribute

Reference

Releases

Pi provider templates

Catalog

DeepSeek: the configuration Orbi’s own deliveries run on

xAI: Grok 4.20 Reasoning

OpenRouter `:free`: one key, multiple models

Limits, requests, and 429 status

Add a new provider

`thinkingLevelMap`

Google Gemini: AI Studio free tier

Free-tier limits and observed behavior

z.ai GLM: experience/free quota

What is known about the free allowance

Switch when the allowance is exhausted

Cloudflare Workers AI

Measure a real Orbi task

Hosted versus local Qwen

Local providers

GitHub Models: historical free-prototyping snapshot

Model catalog and limits (checked 2026-09-04)

GitHub Models versus Copilot

Minimal Orbi configuration

Choose a model the account can use

How this differs from the Codex OAuth section

Headless and server installs

Quota and billing boundary

Failure paths and repair actions

Evidence boundary

Codex OAuth: use a ChatGPT/Codex subscription

Minimal Orbi configuration

Quota and billing boundary

Real Issue evidence to retain

Switch providers when quota or auth fails

Groq Free Plan

​Catalog

​DeepSeek: the configuration Orbi’s own deliveries run on

​xAI: Grok 4.20 Reasoning

​OpenRouter :free: one key, multiple models

​Limits, requests, and 429 status

​Add a new provider

​thinkingLevelMap

​Google Gemini: AI Studio free tier

​Free-tier limits and observed behavior

​z.ai GLM: experience/free quota

​What is known about the free allowance

​Switch when the allowance is exhausted

​Cloudflare Workers AI

​Measure a real Orbi task

​Hosted versus local Qwen

​Local providers

​GitHub Models: historical free-prototyping snapshot

​Model catalog and limits (checked 2026-09-04)

​GitHub Models versus Copilot

​Sign in with ChatGPT: use a ChatGPT Plus/Pro plan

​First login: do this in order

​Minimal Orbi configuration

​Choose a model the account can use

​How this differs from the Codex OAuth section

​Headless and server installs

​Quota and billing boundary

​Failure paths and repair actions

​Evidence boundary

​Codex OAuth: use a ChatGPT/Codex subscription

​First login: do this in order

​Minimal Orbi configuration

​Quota and billing boundary

​Real Issue evidence to retain

​Switch providers when quota or auth fails

​Groq Free Plan

Catalog

DeepSeek: the configuration Orbi’s own deliveries run on

xAI: Grok 4.20 Reasoning

OpenRouter `:free`: one key, multiple models

Limits, requests, and 429 status

Add a new provider

`thinkingLevelMap`

Google Gemini: AI Studio free tier

Free-tier limits and observed behavior

z.ai GLM: experience/free quota

What is known about the free allowance

Switch when the allowance is exhausted

Cloudflare Workers AI

Measure a real Orbi task

Hosted versus local Qwen

Local providers

GitHub Models: historical free-prototyping snapshot

Model catalog and limits (checked 2026-09-04)

GitHub Models versus Copilot

Sign in with ChatGPT: use a ChatGPT Plus/Pro plan

First login: do this in order

Minimal Orbi configuration

Choose a model the account can use

How this differs from the Codex OAuth section

Headless and server installs

Quota and billing boundary

Failure paths and repair actions

Evidence boundary

Codex OAuth: use a ChatGPT/Codex subscription

First login: do this in order

Minimal Orbi configuration

Quota and billing boundary

Real Issue evidence to retain

Switch providers when quota or auth fails

Groq Free Plan