pi-bansos

Free model provider for pi (browse packages). It adds a bansos provider with live free models from 2 upstreams — OpenCode Zen and KiloCode gateway — through a local OpenAI-compatible proxy.

Contents

• Features
• Models
• Install
• Update
• Usage
• Relay (optional)
• Data files
• Notes
• Uninstall
• License

Features

• Zero cost — all models free, no API key needed for supported upstreams
• 21 models from 2 sources — 8 OpenCode Zen + 13 KiloCode gateway
• Instant startup — the model catalog is cached locally and registered without waiting on upstream; it refreshes in the background
• Auto health-check — only catalog-listed models registered; dead ones skipped silently
• Local-only proxy — binds to 127.0.0.1, nothing exposed externally; one proxy per loaded extension, shared by every session that uses it (including OMP's in-process subagents)
• Optional relay egress with automatic failover — route through a Cloudflare Workers (one command, free, no card) or Vercel relay to dodge per-IP rate limits; a 429/403/unreachable relay cools down (escalating backoff) and the request rolls to the next healthy relay or goes direct — toggled live via /bansos
• OpenCode free-tier fingerprint kept current — auto-tracks the live opencode-ai UA version, generates spec-correct session/request IDs (verified against opencode's own Identifier), and ships the tool-pair payload the 1.19.0 gate expects
• Upstream 429/403 triage with reactive cooldowns — free-tier refusals are classified live: a quota 429 FreeUsageLimitError cools just that model (90 s base, escalating, upstream Retry-After honored up to one full quota day), an IP-flag 403 "abusive traffic" fails fast with a switch-egress hint instead of hammering a network no backoff can fix, and a fingerprint-gate 403 is surfaced as-is. The session gets a precise reason + Retry-After instead of a raw refusal replay.
• Auto port bump — if port 18080 is taken, automatically tries the next one (up to 18100)

Models

21 curated total: 8 OpenCode + 13 KiloCode. All models are free. The provider is one bansos entry, but model names show their upstream: OpenCode or KiloCode. The startup check only verifies catalog membership; upstream access can still change between startup and a request.

OpenCode Zen (10 models)

Sweep 2026-11-06: added crouton-alpha-free and pulse-alpha-free (catalog-listed; chat-verify pending — the probe egress is quota-held to UTC midnight). Core models (big-pickle, beam, mimo, deepseek, glm, lightning, super-vl) confirmed alive through a community gateway reading the same upstream, and independently by 9router PR #5381 on the new v3 wire. The 2026-11 gate turn: free-tier requests must now carry the v2 CLI dev wire — UA opencode/dev/<build>/opencode, x-opencode-client: opencode, per-request x-opencode-request, all four session headers, prompt_cache_key bound to the session — and no tool declaration may contain the substring terminal (textual gate; such tools are aliased to run_command on the wire automatically). Direct OpenCode requests now use a fresh TLS connection each time: keep-alive socket reuse was letting one flagged (ip, session) pair poison every request riding that connection into a 429 cascade.

Muse note: the muse-class models are 410-deprecated for now, but their Responses-API routing (/v1/responses) stays in place — if a muse-class id returns to the catalog it re-routes automatically, no code change needed.

KiloCode Gateway (8 models)

Keyless — 200 requests/hour per IP. No Authorization header is sent; the free gateway rejects placeholder tokens.

Sweep 2026-11-06: the gateway shed most of its free list — dropped recursive/flint-v1.0:free, xingchen-agi/xing4.0-29b-a4b:free, nvidia/nemotron-3-super-120b-a12b:free, nvidia/nemotron-3.5-content-safety:free and poolside/laguna-s-2.1:free (all gone from the live catalog). All 8 survivors chat-verified 200 today (nemotron-3-ultra needed one retry past a transient 503). Kilo's NVIDIA free endpoints may retain prompts or use them for training; do not send confidential data.

Rate limiting is separated internally by upstream: OpenCode uses its UTC-day local guard and its own upstream free quota; Kilo uses a rolling-hour local guard matching its documented 200/hour/IP limit.

Install

pi

Requires pi.

pi install npm:pi-bansos

OMP (Oh My Pi)

omp install pi-bansos
# same as: omp plugin install pi-bansos

Restart OMP after install. Then /model → bansos → pick a free model.

Update

There is no separate “update pi-bansos” product command. You refresh the npm package with the host tool (pi or OMP), then restart so the extension reloads.

pi

Official package docs (pi update):

# update only this package
pi update npm:pi-bansos
# same idea:
pi update --extension npm:pi-bansos

# or update every installed extension
pi update --extensions

Notes (from pi packages docs):

• Unpinned installs (pi install npm:pi-bansos) get the latest npm version on update.
• Pinned installs (pi install npm:pi-bansos@0.4.13) are skipped by pi update --extensions / pi update --all until you change the pin (install a newer @x.y.z or drop the pin).
• After update, restart pi (quit and start again) so the new extension code loads.

Free model catalog update (0.6.4)

Adds eight chat-verified models: OpenCode DeepSeek V4.1 Flash, GLM 5.3 Flash, Cat Jam, LL Alpha, and Nemotron 3.5 Super VL; KiloCode Nemotron 3.5 Super VL, Glyph Cluster, and Cat Jam. The curated list now has 32 models; the picker only shows those present in the upstream catalog (plus the existing pinned model). Muse keeps its Responses API configuration unchanged.

Update the package, then restart pi or OMP. /bansos refresh-models refreshes catalog membership only; it cannot add definitions missing from an older package.

Streaming fix (0.6.3)

If 0.6.1 reports malformed server-sent event JSON with default tools enabled, update to 0.6.3 (or later) and restart pi. Tool-alias rewriting now preserves SSE line endings and empty event separators, and decodes split UTF-8 characters incrementally. This does not resolve upstream model outages or rate limits (issue #12).

0.6.2 is the same fix in git history, but that version never became installable on npm (registry staging lock). Install pi-bansos@0.6.3.

Maintainers can run the chunk-boundary regression suite with bun test tests/stream-framing.test.ts (requires Bun; no extra dependencies).

OMP (Oh My Pi)

omp plugin upgrade only upgrades marketplace plugins (name@marketplace). npm plugins like pi-bansos are not that format.

Refresh npm plugins with install --force, or uninstall then install:

omp install pi-bansos --force
# same as: omp plugin install pi-bansos --force

# alternative
omp plugin uninstall pi-bansos
omp install pi-bansos

Restart OMP after. Check version: omp plugin list (should show pi-bansos@…).

Usage

pi   # or: omp
# /model → bansos → choose a free model

Startup is silent and instant: the model list comes from the local catalog cache (see Data files), so nothing blocks on the network. The TUI status bar shows relay: ON/OFF, or bansos: proxy down / bansos: no models when startup failed; /bansos status gives the details (proxy address or bind error, models found at startup). Hide or show the status-bar entry with /bansos hide / /bansos show. Rate-limit answers are precise: during a model's quota cooldown or a network IP-flag the proxy fails fast with Retry-After and the reason in the body (see Notes) instead of replaying the refusal to the upstream.

Commands

Run /bansos any time:

Environment variables

BANSOS_PORT=18081 pi   # custom proxy port (default 18080, bumps up to 18100)
BANSOS_DEBUG=1 pi      # print startup, relay and rate-limit diagnostics on stderr
BANSOS_OPENCODE_UA=x.y.z pi  # pin the opencode User-Agent version (default: auto-track npm latest, fallback 1.18.31)

Relay (optional)

By default pi-bansos talks to the free upstreams directly. If your IP gets rate-limited or blocked, switch on a relay — requests then go out through a relay worker instead of your own IP. Toggle it live from inside pi, no restart.

The relay on/off switch, the saved relay list, and the status-bar preference live in the state file (see Data files) and are remembered across restarts — you manage them only via /bansos, nothing in your shell. Each /bansos change re-reads the file at the moment it saves, applies only that change, writes it atomically, and then switches this process to the saved state — so settings changed meanwhile by another running pi/OMP process are kept, and that process's relay switch also takes effect here. Commands that only show state (status, list) don't re-read; other running processes pick up changes at their next session start or their next /bansos change. If saving fails, the change is not applied and the error is shown. Every relay you deploy, use, or url is kept in a saved list, so you can switch between them anytime without re-typing URLs. Any HTTP relay works (Vercel, Cloudflare, Deno, or your own). There is no built-in default — run /bansos deploy to create one or /bansos url <URL> to use your own.

Switching between saved relays (e.g. you deployed one and also have another):

/bansos list
  Saved relays (2):
  ★ https://relay-2026.your-subdomain.workers.dev  [deployed relay-2026]
    https://vercel-relay-yyyy.vercel.app            [manual]

/bansos            → Switch relay… → pick one → active (live, no restart)
/bansos use https://vercel-relay-yyyy.vercel.app   # or switch directly

/bansos deploy — one-command relay (Cloudflare or Vercel)

Deploys your own relay and activates it immediately. Pick a platform, paste an API token (used once, never stored), optionally name the project — the relay URL is saved and switched on when it goes live.

Cloudflare Workers (recommended) — free plan, no credit card, 100 K requests/day (one LLM turn = one relay request, so the daily ceiling is ~20–50× a heavy agentic day). Get a token at dash.cloudflare.com → My Profile → API Tokens → Create Token → Edit Cloudflare Workers template (or a custom token with Workers Scripts Edit + Account Settings Read). A free Cloudflare account is enough.

/bansos deploy
  Deploy relay to: Cloudflare Workers (recommended — free, IP diversity)
  Cloudflare API token: <paste>
  Project name (empty = auto):  relay-2026
  Resolving Cloudflare account…
  Uploading relay worker to Cloudflare…
  Reading workers.dev routing…
  ✓ Deployed & active: https://relay-2026.<your-subdomain>.workers.dev

The generated worker is hardened: it embeds a random 32-byte secret minted per deployment and answers 401 to any request without the matching x-relay-auth header (pi-bansos sends it automatically for relays it deployed), forwards only to the pi-bansos upstreams (https://opencode.ai, https://api.kilo.ai) with private-host and path checks, and caps request size at 32 MB. Deploy design adapted from trefeon/pi-freeflow (MIT).

Vercel — needs a Vercel account and token (vercel.com/account/tokens); Hobby plans cap fast-origin bandwidth (~10 GB), after which deployments return HTTP 402, so treat it as fallback.

/bansos deploy
  Deploy relay to: Vercel (needs an account; Hobby caps bandwidth)
  Vercel API token (vercel-…): <paste>
  Project name (empty = auto):  relay-2026
  Uploading relay to Vercel…
  Waiting for deployment to go live…
  ✓ Deployed & active: https://relay-2026-xxx.vercel.app

Both relays mask your IP behind the platform's edge IPs. Useful when your IP is rate-limited or flagged (OpenCode's newer 403 "abusive traffic from this IP" block is IP-level and passes with a different egress). If a relay's own egress gets flagged, pi-bansos cools it down (90 s, escalating) and rolls to the next healthy relay or goes direct. A relay is one fixed exit, not rotation — for more egress diversity deploy several and keep them in the saved list. The token input has no hidden/secret mode in the TUI, so it shows while typing — paste, deploy, done.

Data files

pi-bansos writes two files into the agent directory of the host that loaded it — pi and OMP each keep their own state:

Both live outside the package directory, so npm updates never wipe them. The host is detected from the extension's real install path, with a process-name fallback for symlinked installs (e.g. an OMP npm plugin symlinked into a repo checkout). If you use pi and OMP side by side, each has its own relay settings and catalog cache — deleting one leaves the other untouched.

Notes

• Free upstream models are best-effort: promos can expire, model IDs can change, and rate limits may apply
• pi-bansos health-checks against the cached/live catalog at startup so unavailable models are skipped instead of registered
• KiloCode gateway: 200 req/hr per IP, keyless
• Upstream refusals are triaged, not replayed: a quota 429 FreeUsageLimitError cools just that model (90 s base, escalating; upstream Retry-After honored, capped at one UTC quota day), an IP-flag 403 "abusive traffic from this IP address" fails fast with a switch-egress hint (/bansos deploy) while no relay is active, and a fingerprint-gate 403 FreeTierError is surfaced as-is. Any 2xx clears the cooldowns
• OpenCode's free limits are dynamic and metered per account/workspace/network — a shared or CGNAT IP can be flagged because of other users, so a 429 with zero personal usage is usually the network bucket, not the model
• Catalog specs (context, max output, modalities) come from the curated model lists in the extension; the cache only stores which IDs are alive

Uninstall

pi

pi remove npm:pi-bansos

OMP

omp plugin uninstall pi-bansos

License

MIT