​

Pi provider templates

pi_providers = ".orbi/pi-providers.json"
pi_provider = "z-ai"
pi_model = "glm-5.3-flash"

​

Catalog

​

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

​

Google Gemini: AI Studio free tier

1. 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.
2. 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}
           }
         ]
       }
     }
   }
   
3. 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

pi_providers = ".orbi/pi-providers.json"
pi_provider = "z-ai"       # or another provider in the catalog
pi_model = "glm-5.3-flash"

​

z.ai GLM: experience/free quota

1. 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.
2. 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.
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 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

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

​

Cloudflare Workers AI

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

pi_providers = ".orbi/pi-providers.json"
pi_provider = "cloudflare-workers-ai"
pi_model = "@cf/meta/llama-3.1-8b-instruct-fp8"

​

Measure a real Orbi task

journal: provider=cloudflare-workers-ai 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

​

Local providers

​

Codex OAuth: use a ChatGPT/Codex subscription

​

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

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"

​

Quota and billing boundary

​

Real Issue evidence to retain

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)

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

​

Switch providers when quota or auth fails

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

​

Groq Free Plan

pi_providers = ".orbi/pi-providers.json"
pi_provider = "groq"
pi_model = "groq/compound"