bansos-router

Free, keyless coding models for every coding harness, through one local daemon. Works without accounts or API keys.

Quick start

npm i -g bansos-router

Start the daemon and point your coding harness at it:

bansos start --bg       # detached daemon on 127.0.0.1:17070
bansos setup opencode   # configure any supported harness

For pi, install the companion extension (extensions/pi):

pi install npm:pi-bansos-router

Supported harnesses for bansos setup: claude-code, aider, opencode, codex, hermes, goose, openclaw, antigravity, jcode, 9router, continue, cline, roo, and omp. See docs/harnesses.md for harness-specific details.

OMP (Oh My Pi) can connect two ways, pick one:

• bansos setup omp writes a bansos provider into ~/.omp/agent/models.yml (start the daemon yourself with bansos start).
• The pi extension loads in OMP too (it is a pi fork): drop its built file into ~/.omp/agent/extensions/, which registers a bansosr provider and auto-manages the daemon.

Using both is harmless but redundant: the IDs differ (bansos vs bansosr), so you get two providers listing the same models. Prefer one.

Open http://127.0.0.1:17070 in your browser for the Web UI dashboard (model catalog, live latency ping, 1-click config generator, relay manager, playground).

Always-on local protections

These hold in every mode (not just strict):

• CORS only for loopback origins: a page served from a non-loopback origin gets no CORS headers, so it can neither read nor write the daemon.
• Host header validated: loopback clients must present a loopback (or own-interface) Host header; anything else gets 403. This blocks DNS rebinding where a hostile page resolves to 127.0.0.1.
• Relay probe & mutation are SSRF-guarded: probes may only target the active/saved relay or a public https:// host; literal loopback, private, and link-local IPs (e.g. 169.254.x metadata) are rejected unless explicitly saved. Relay URLs must be http(s):// without credentials.

Docker

Run the daemon in a container instead of installing globally:

docker build -t bansos-router .
docker run -d --name bansos -p 17070:17070 -v bansos-data:/home/node/.bansos bansos-router

The container runs as the non-root node user (uid 1000); state lives in /home/node/.bansos inside the container, which is what the volume above mounts.

Or with compose:

docker compose up -d

• Image is a multi-stage build on node:22-alpine (~58 MB compressed), CLI + daemon + Web UI included, zero runtime dependencies.
• The container runs the daemon in the foreground (Docker owns the lifecycle) bound to 0.0.0.0, with tini for correct signal forwarding and a healthcheck on /healthz.
• State persists across restarts in the bansos-data volume; point your harnesses at http://127.0.0.1:17070 as usual.
• docker compose logs -f replaces bansos logs inside the container.

CLI reference

Command	Purpose
bansos start [--bg] [--port N] [--bind H] [--unsafe-allow-non-loopback]	Run the daemon (foreground, or detached with --bg)
bansos logs [--activity]	Tail the daemon log in real time (every mode: daemon always logs to ~/.bansos/logs/bansosd.log); --activity prints the structured request feed shown in the web UI "Activity" tab
bansos stop [--all]	Stop the daemon recorded in state.json; --all stops every bansos daemon on the machine
bansos status [--json]	Daemon status (port, model count, alive models); reports every running daemon on the auto-bump range (17070-17090)
bansos models [--json]	List live catalog from /v1/models
bansos ping [model] [--json]	Probe live latency and rate-limit status of all models (or a specific model)
bansos refresh	Ask the daemon to re-run health checks now
bansos setup <harness...> [--model <id>] [--dry-run] [--undo]	Write, update, or undo harness configs
bansos relay <on|off|status|url|use|list|remove>	Manage relay egress
bansos doctor	Diagnose daemon reachability and harness config validity
bansos --version	Print version
bansos <command> --help / bansos help <command>	Per-command usage, defaults, exit codes, examples
bansosd	Alias for the daemon (e.g. bansosd --bg)

Strict security mode

Strict mode is opt-in and fail-closed. Add a security block to ~/.bansos/config.json and explicitly list every provider that may receive requests:

{
  "port": 17070,
  "bind": "127.0.0.1",
  "security": {
    "mode": "strict",
    "allowedUpstreams": ["zen"],
    "allowCrossProviderFailover": false
  }
}

With mode: "strict":

• Non-loopback binds rejected unless --unsafe-allow-non-loopback passed.
• Relay egress, probing, and mutation disabled across CLI, API, Web UI.
• Only exact upstreams in allowedUpstreams receive requests (empty list blocks all).
• Cross-provider failover disabled.
• Sensitive values and raw upstream errors suppressed from logs.
• DLP blocks pasted credentials: API keys, PATs, private keys, and credential assignments pasted into a request are blocked with HTTP 422 before they leave for an external upstream (zen/kilo/llm7). Loopback (self-hosted) gateways are exempt, since their own keys are legitimately part of the request body.

What it does

• One local daemon on 127.0.0.1:17070, started with bansos start. It speaks three wire protocols: OpenAI Chat Completions, Anthropic Messages, and OpenAI Responses (Codex CLI).
• Keyless free upstreams only: OpenCode Zen, KiloCode gateway, LLM7, and OVHcloud AI Endpoints (anonymous tier).
• bansos setup <harness> writes config for Claude Code, Aider, OpenCode, Codex, Hermes, Goose, OpenClaw, Antigravity, JCode, 9Router, Continue, Cline, and Roo Code.
• Web UI dashboard served at http://127.0.0.1:17070/ with model catalog explorer, live ping probes, 1-click harness setup generator, relay egress manager, and test playground. The catalog shows per-model capabilities (Think / Vision badges) and a live usage + activity tracker (requests, tokens, latency, error rate).
• The pi extension (pi-bansos-router) registers the bansosr provider, so every free model shows up in pi's /model picker. There is also a /bansosr command for status. If the daemon is not running when pi starts, the extension starts it and stops it again on exit.
• The catalog is health-checked: live :free models replace stale seeds on a timer. Relay egress can route around rate limits, and there is a per-IP rate limiter.
• If a model is rejected with 401/403/429/5xx, the daemon auto-fails over to the closest equivalent model on a different upstream (same reasoning level, context window, and effort capability), retrying up to two extra candidates before surfacing an error. Request duration (durationMs) is logged on every completion and rejection.
• A model that answers 429 is parked for a cooldown, so the next request starts on a fallback instead of spending another round trip to learn the same thing. Retry-After sets the duration when the upstream sends one, otherwise it is a minute, capped at fifteen. Parked models stay listed in /v1/models and are still used when nothing else qualifies.
• A 401/403 means the upstream will not serve that model from where the request egressed (OpenCode Zen, for instance, returns 403 This service is not available in your region when Cloudflare routes through a region its providers block). Retrying cannot help, so the model is parked for 30 minutes and the request fails over instead of returning the error. Send x-bansos-no-failover: 1 when you want the model's own status back. The upstream's own message is now logged alongside the status.

Available models

By default, bansos setup automatically configures intelligent defaults per harness:

• Claude Code: Maps tiers automatically (haiku -> fast non-reasoning, sonnet -> daily reasoning, opus -> highest-capacity reasoning).
• Multi-model harnesses (opencode, goose, openclaw, continue, 9router, jcode, omp): Registers all available models (or dynamic /v1/models provider) with the smart default (currently muse-spark-1.3-contributor-free) as primary.
• Single-model harnesses (aider, codex, hermes, antigravity, cline, roo): Same smart default. Pass --model <id> to pin a specific model. Context and max output are token counts. The seeded catalog is ~30 models and the live one changes as upstreams rotate free tiers; run bansos models or bansos ping to see what is alive right now.

OpenCode Zen

model id	reasoning	vision	context	max output
mimo-v2.5-free	✓	✓	200k	32k
nemotron-3-ultra-free	✓	✗	1M	128k
big-pickle	✓	✗	200k	32k
nemotron-3.5-lightning-free	✓	✗	262k	262k
ling-3.0-flash-fin-free	✓	✗	262k	32k
muse-spark-1.3-contributor-free	✓	✓	1M	131k
muse-spark-1.2-contributor-free	✓	✓	1M	131k

Muse Spark answers only on the Responses API (/v1/responses) and returns HTTP 500 on chat completions. bansos-router translates the upstream leg both ways, so Muse works from any harness — chat completions, Responses, and Anthropic clients all see their usual wire format, tool calls included.

KiloCode gateway

model id	reasoning	vision	context	max output
kilo-auto/free	✓	✗	256k	10k
stepfun/step-3.7-flash:free	✓	✓	262k	262k
nvidia/nemotron-3-ultra-550b-a55b:free	✓	✗	1M	65k
nvidia/nemotron-3-super-120b-a12b:free	✓	✗	262k	262k
nvidia/nemotron-3.5-lightning:free	✓	✗	1M	65k
nvidia/nemotron-3.5-content-safety:free	✓	✓	128k	8k
liquid/lfm-2.5-2.6b:free	✓	✗	65k	8k
poolside/laguna-s-2.1:free	✓	✗	262k	32k
cohere/north-mini-code:free	✓	✗	256k	64k
poolside/laguna-xs-2.1:free	✓	✗	262k	32k
nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free	✓	✓	256k	65k
inclusionai/ling-3.0-flash-sante:free	✓	✗	262k	32k
inclusionai/ling-3.0-flash-fin:free	✓	✗	262k	32k
dots-studio/dots-3-note-preview:free	✓	✓	512k	65k
thinkingmachines/inkling:free	✓	✓	1M	65k
thinkingmachines/inkling-small:free	✓	✓	1M	65k
openrouter/free	✓	✓	200k	65k

LLM7

model id	reasoning	vision	context	max output
codestral-latest	✗	✗	32k	8k
minimax-m2.7	✓	✗	180k	32k
mistral-Nemo-Instruct-2407	✗	✗	128k	16k
default	✗	✗	128k	8k
fast	✗	✗	128k	8k

OVHcloud AI Endpoints

model id	reasoning	vision	context	max output
ovh/gpt-oss-120b	✓	✗	131k	32k
ovh/gpt-oss-20b	✓	✗	131k	32k
ovh/Qwen3.5-397B-A17B	✓	✓	262k	65k
ovh/Qwen3.8-27B	✓	✓	262k	32k
ovh/Qwen3.6-27B	✓	✓	262k	65k
ovh/Qwen3.5-9B	✓	✓	262k	65k
ovh/Mistral-Small-3.2-24B-Instruct-2506	✗	✓	131k	16k
ovh/Meta-Llama-3_3-70B-Instruct	✗	✗	131k	16k

Notes:

• The tables above mirror the seeds in src/upstreams/*, which were verified against each upstream's live catalog and specs on 2026-09-03 (reasoning / vision / context flags, dead promos removed). On refresh the daemon serves the live catalog, which can differ slightly as upstreams rotate free tiers.
• Kilo's :free models are liveness-gated: the daemon re-checks the kilo catalog on a timer and drops models that are no longer offered free.
• Zen seeds are re-checked against GET /v1/models on refresh. The listing is not exhaustive (some servable promos are never listed), so an unlisted seed is probe-verified keyless before being kept; a retired promo (e.g. hy3-free, gone and answering 401) disappears automatically.
• LLM7 models are filtered dynamically by usage_based_only: false (tier turbo); default and fast are stable selectors. pro tier is paid-only and excluded.
• OVH's anonymous tier allows only 2 requests per minute per IP, so its models mostly serve as failover targets. The ovh/ prefix is local to bansos and stripped before the request leaves; a bare id like gpt-oss-120b resolves too.

Development

For contributors working from source:

git clone https://github.com/ihsan-ramadhan/bansos-router
cd bansos-router
npm install
npm run build      # builds Web UI (Vite) + CLI (esbuild), outputs dist/
npm link           # make `bansos`/`bansosd` available globally
npm run typecheck  # tsc --noEmit
npm test           # node:test

npm run dev        # run the bansos CLI from source
npm run dev:daemon # run the daemon from source
npm run dev:ui     # run Vite dev server for Web UI

Docs

• Architecture
• Wire protocols & translation
• Harness integration
• Upstreams, catalog & relay
• Contributing

License

MIT