@askalf/dario 3.6.0 → 3.7.0

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <h1 align="center">dario</h1>
-  <p align="center"><strong>Use your Claude subscription inside your local tools and scripts — without moving to API billing or rebuilding your workflow around a separate stack.</strong></p>
+  <p align="center"><strong>A local LLM router. One endpoint on your machine, every provider behind it, your tools don't need to change.</strong></p>
 </p>
 
 <p align="center">
@@ -14,9 +14,8 @@
 <p align="center">
   <a href="#quick-start">Quick Start</a> &bull;
   <a href="#who-this-is-for">Who it's for</a> &bull;
+  <a href="#backends">Backends</a> &bull;
   <a href="#why-switch">Why switch</a> &bull;
-  <a href="#how-it-works">How it works</a> &bull;
-  <a href="#from-standalone-to-askalf">Standalone → askalf</a> &bull;
   <a href="#trust--transparency">Trust</a> &bull;
   <a href="#faq">FAQ</a>
 </p>
@@ -25,191 +24,137 @@
 
 ## What it is
 
-dario is a local process that turns your Claude Max or Pro subscription into an API endpoint that any tool on your machine can use. It talks to Anthropic the same way Claude Code does, so your subscription's rate limits are what you spend against — not a separate API billing tier.
+Dario runs on your machine and gives every tool you use one local URL that reaches **every LLM you use.** Point Cursor, Continue, Aider, LiteLLM, your own scripts — anything that speaks the Anthropic or OpenAI API — at `http://localhost:3456`, and dario routes each request to the right backend:
 
-Install it once, log in once (using your existing Claude Code credentials if you have them), and from that point on every tool that speaks the Anthropic API or the OpenAI chat completions API — Cursor, Continue, Aider, LiteLLM, your own scripts, whatever — can reach Claude through `http://localhost:3456`.
+- **Claude Max / Pro subscriptions** — OAuth-backed, billed against your plan instead of API pricing. Multi-account pooling if you have more than one.
+- **OpenAI** — your API key, routed to `api.openai.com` straight through.
+- **Any OpenAI-compat endpoint** — OpenRouter, Groq, a local LiteLLM, Ollama's openai-compat mode, self-hosted vLLM. Set the backend's `baseUrl` once, done.
 
-**Single-account mode is the default.** You don't need an account anywhere, you don't need to wait for anything, and nothing phones home. Install and run.
+Your tool sees one base URL. `gpt-4` goes to OpenAI. `claude-opus-4-6` goes to your Claude subscription. `llama-3-70b` goes to Groq. None of your tools have to know about any of it.
 
-**Pool mode** (new in v3.5.0) lifts multi-account routing into dario itself. Add two or more Claude subscriptions with `dario accounts add`, and dario starts selecting per request by the account with the most headroom, marking exhausted accounts rejected until they reset. No hosted platform required — you run the pool on your machine, against your own subscriptions. See [Multi-Account Pool Mode](#multi-account-pool-mode) below.
-
-**Multi-provider routing** (new in v3.6.0) lets dario speak to more than just Claude. Configure an OpenAI-compat backend (OpenAI, OpenRouter, Groq, local LiteLLM, Ollama's openai-compat mode) with `dario backend add openai --key=... [--base-url=...]`, and GPT-family model names at `/v1/chat/completions` route to that backend while Claude model names keep flowing through the Claude subscription path. Point your tool at `http://localhost:3456` once and use any model from any provider. See [Multi-Provider Routing](#multi-provider-routing) below.
-
-Separately, [askalf](https://askalf.org) is the hosted platform that does the things a local proxy on your machine can't — browser and desktop control, scheduling, persistent memory, 24/7 hosted fleets. Different problem, different tool. Dario does not depend on askalf, and askalf is not required to use any dario feature.
+**No account anywhere is required.** Single-backend Claude dario works with nothing but `dario login`. Multi-backend dario works with nothing but local config files. Nothing phones home. Zero runtime dependencies. ~2,000 lines of TypeScript.
 
 ---
 
 ## Who this is for
 
 **Best fit:**
-- Power users already paying for Claude Max or Pro who want Claude available inside their local stack — editors, terminals, scripts, internal tools — without moving to API billing.
-- Small teams that work in terminals and IDEs, not in hosted agent stacks, and want Claude as a drop-in provider for whatever tools they already use.
-- Anyone who wants Claude Code's billing behavior on their own requests, from their own code.
+
+- **Developers using multiple LLMs across multiple tools** who are tired of juggling base URLs, API keys, and per-tool provider configs.
+- **Claude Max or Pro subscribers** who want their subscription usable anywhere that speaks the Anthropic or OpenAI API — without paying API rates for every request.
+- **Teams running local or hosted OpenAI-compat servers** (LiteLLM, vLLM, Ollama, Groq, OpenRouter) who want one stable local endpoint in front of them that every tool can reuse.
+- **Power users running multi-agent workloads on Claude subscriptions** who want multi-account pooling with headroom-aware routing on their own machine, against their own subscriptions, without a hosted platform.
 
 **Not a fit:**
-- You need vendor-managed production SLAs on every request. Use the Anthropic API directly.
-- You need high-scale agent orchestration, multi-account pooling, or session-level classifier shaping. That's [askalf](https://askalf.org), which dario bridges into.
-- You want a hosted chat UI. Use claude.ai.
+
+- You need vendor-managed production SLAs on every request. Use the provider APIs directly.
+- You need a hosted multi-tenant routing platform with a dashboard. Try [askalf](https://askalf.org), a separate product in the same family — different problem, different tool.
+- You want a chat UI. Use claude.ai or chatgpt.com.
 
 ---
 
 ## First use case
 
-> Use Claude in your local automation and developer workflows the way you'd normally reach for an API — but backed by the subscription you already pay for.
-
-You install dario, point your existing tool at `http://localhost:3456`, and that tool now sees Claude. The tool doesn't know it's going through a proxy; from its perspective dario *is* the Anthropic API. Your subscription handles the billing. Your Max plan limits are what count against usage.
+> I install dario, point every tool I already use at `http://localhost:3456`, and every LLM I have access to works through that one URL.
 
 Flow on a fresh machine:
 
-1. `npm install -g @askalf/dario`
-2. `dario login` — detects your installed Claude Code credentials, or runs its own OAuth flow if you don't have CC installed
-3. `dario proxy` — starts the local server on port 3456
-4. Set two environment variables in the tool you already use:
-   ```bash
-   ANTHROPIC_BASE_URL=http://localhost:3456
-   ANTHROPIC_API_KEY=dario
-   ```
-5. That tool now uses your Claude subscription. Streaming works, tool use works, prompt caching works.
-
-No separate API key. No Extra Usage charges. No rebuilding your workflow around a new provider.
-
----
-
-## Why switch
-
-**Use dario if** you already pay for Claude Max or Pro and you want Claude inside the tools you already use, without paying API rates for every request or routing your work through a second hosted stack.
-
-**Use dario pool mode if** you're running multi-agent workloads and hitting per-subscription rate limits — add 2–N accounts with `dario accounts add` and dario handles headroom-aware routing across them, all on your machine, against your own subscriptions. No hosted stack to sign up for. See [Multi-Account Pool Mode](#multi-account-pool-mode).
-
-**Use dario multi-provider routing if** you want one local endpoint that speaks to Claude subscriptions *and* OpenAI / OpenRouter / Groq / a local LiteLLM / anything else OpenAI-compat. `dario backend add openai --key=...`, point your tool at `http://localhost:3456`, and every model from every provider flows through the same URL. See [Multi-Provider Routing](#multi-provider-routing).
-
-**Use the Anthropic API directly if** you need platform-native primitives, vendor-managed production usage, high-scale control, or SLAs your subscription tier doesn't cover. Dario isn't trying to replace the API — it's trying to unlock the subscription you already bought.
-
-**Don't use dario if** you want a subprocess bridge that shells out to `claude --print` under the hood. Those tools (openclaw-claude-bridge and similar) work well for single-team single-machine workloads that can accept a one-subscription rate ceiling and a one-machine deployment. Dario is the API-path alternative, which trades that simplicity for pooling-friendly behavior on the wire. Different tradeoffs, different tool.
-
----
-
-## Quick Start
-
 ```bash
 # Install
 npm install -g @askalf/dario
 
-# Log in (detects Claude Code credentials if installed)
+# Optional: log in to your Claude subscription (Max or Pro)
 dario login
 
+# Optional: add an OpenAI-compat backend
+dario backend add openai --key=sk-proj-...
+
 # Start the proxy
 dario proxy
 
-# Anthropic SDK
+# Use it — set these once, every tool that honors them just works
 export ANTHROPIC_BASE_URL=http://localhost:3456
 export ANTHROPIC_API_KEY=dario
-
-# or OpenAI-compatible tools
 export OPENAI_BASE_URL=http://localhost:3456/v1
 export OPENAI_API_KEY=dario
 ```
 
-Opus, Sonnet, Haiku — all models, streaming, tool use, prompt caching, extended thinking. **Zero runtime dependencies.** ~2,000 lines of TypeScript. Auto-launches under [Bun](https://bun.sh) when available for TLS fingerprint fidelity with Claude Code's runtime. **Auto-detects OAuth config from your installed CC binary** so dario stays in sync forever — Anthropic can rotate client IDs and dario picks them up on the next run.
-
----
-
-## How It Works
+Now from the same Cursor/Continue/Aider instance:
 
-Dario has two modes: **direct API mode** (the default) and **passthrough mode** (`--passthrough`).
+- `gpt-4o` → OpenAI, your key, straight through
+- `claude-opus-4-6` → Claude subscription, billed against your Max plan
+- `opus` → shortcut, same as above
+- `llama-3.1-70b` on OpenRouter → configure `dario backend add openrouter --key=sk-or-... --base-url=https://openrouter.ai/api/v1`, done
 
-### Direct API Mode — Template Replay
+One URL. Your tool doesn't know or care which provider is answering.
 
-This is the mode you want for almost every case. Dario takes each request you send it and replaces it with a Claude Code request: same 25 tool definitions, same 25KB system prompt, same field order, same beta headers, same metadata structure, same device identity. Only your conversation content is preserved. Anthropic's classifier sees what looks like a Claude Code session because, from the wire up, it *is* one — and that's what keeps your usage on subscription billing instead of Extra Usage.
-
-```
-┌───────────┐     ┌─────────────────────┐     ┌──────────────────┐
-│ Your App  │ ──> │   dario (proxy)     │ ──> │ api.anthropic.com│
-│           │     │   localhost:3456    │     │                  │
-│ sends     │     │                     │     │  sees a genuine  │
-│ its own   │     │  replaces request   │     │  Claude Code     │
-│ tools &   │     │  with CC template   │     │  request         │
-│ params    │     │  keeps only content │     │                  │
-└───────────┘     └─────────────────────┘     └──────────────────┘
-```
+---
 
-The details that matter:
+## Why switch
 
-- **Billing tag** reconstructed using CC's own algorithm extracted from the binary: `x-anthropic-billing-header: cc_version=<version>.<build_tag>; cc_entrypoint=cli; cch=<5-char-hex>;` where `build_tag = SHA-256(seed + chars[4,7,20] of user message + version).slice(0,3)`.
-- **Beta set** — CC's exact beta list in CC's order, minus any beta that would require Extra Usage to be enabled on your account.
-- **OAuth config** auto-detected from the installed CC binary at startup. When Anthropic rotates `client_id`, authorize URL, or scopes, dario picks up the new values on the next run without needing a new release. Falls back to hardcoded CC 2.1.104 prod values if CC isn't installed. Cache at `~/.dario/cc-oauth-cache-v3.json`, keyed by binary fingerprint.
-- **Session ID** rotates per request via `x-claude-code-session-id`, matching how `claude --print` behaves. A persistent session ID across rapid requests is a behavioral signal.
-- **Framework scrub** — framework identifiers and known fingerprint tokens (`OpenClaw`, `sessions_*` tool prefixes, orchestration tags, etc.) are stripped from both the system prompt and message content before the request goes upstream.
-- **Bun auto-relaunch** — when Bun is installed, dario relaunches under it so its TLS fingerprint matches CC's runtime. Without Bun, dario runs on Node.js and works fine; the TLS fingerprint is the only difference.
+**Use dario if** you use more than one LLM provider, or more than one tool, or both — and you're tired of configuring each tool with a different base URL and API key per provider.
 
-### Passthrough Mode — `--passthrough`
+**Use dario if** you pay for Claude Max or Pro and you want that subscription reachable from every tool on your machine, without paying API rates or opening a second billing surface.
 
-For tools that need exact Anthropic protocol fidelity with nothing injected. This mode does an OAuth token swap and nothing else: no billing tag, no template, no device identity.
+**Use dario pool mode if** you're running multi-agent workloads on Claude subscriptions and hitting per-account rate limits. Add 2–N accounts with `dario accounts add` and dario routes across them by per-account headroom, all on your machine, against your own subscriptions. See [Multi-Account Pool Mode](#multi-account-pool-mode).
 
-```bash
-dario proxy --passthrough
-```
+**Use a provider API directly if** you need vendor-managed production SLAs or high-scale orchestration primitives the providers ship themselves. Dario isn't trying to replace their APIs — it's trying to put one local shim in front of all of them so your tools don't care which is which.
 
-Use it when the upstream tool already builds a Claude-Code-shaped request on its own and you just need the token auth.
-
-### Detection scope
-
-Dario is a **per-request layer**. Every request it sends upstream is designed to be indistinguishable from a Claude Code request, and the per-request scrubbing hardened in v3.4.5 makes that meaningfully harder to fingerprint than it was when v3.0 first shipped. What dario cannot do at the per-request level is defend against Anthropic's session-level behavioral classifiers — those operate on cumulative per-OAuth aggregates (token throughput, conversation depth, streaming duration, inter-arrival timing) and no amount of per-request hardening reaches them. The practical answer to that problem is *distributing* load across multiple subscriptions so no single account accumulates enough signal to trip the classifier — which is what pool mode (below) does.
+**Don't use dario if** you want a subprocess bridge that shells out to `claude --print` under the hood (openclaw-claude-bridge and similar). That's a valid answer for single-team single-machine workloads that can accept a one-subscription rate ceiling and a one-machine deployment — different tradeoffs, different tool.
 
 ---
 
-## Multi-Account Pool Mode
-
-*New in v3.5.0.* Dario can manage multiple Claude subscriptions and route each request to the account with the most headroom. Single-account dario is unchanged and remains the default — pool mode activates **only** when `~/.dario/accounts/` contains 2+ accounts.
+## Quick Start
 
 ```bash
-# Add accounts to the pool. Each runs its own OAuth flow.
-dario accounts add work
-dario accounts add personal
-dario accounts add side-project
-
-# List them
-dario accounts list
+# Install
+npm install -g @askalf/dario
 
-# Start the proxy — pool mode activates automatically
-dario proxy
-```
+# Claude subscription path (detects Claude Code credentials if CC is installed,
+# runs its own OAuth flow otherwise)
+dario login
 
-### How it routes
+# OpenAI or any OpenAI-compat provider (optional, additive)
+dario backend add openai --key=sk-proj-...
 
-Each incoming request picks the account with the highest **headroom**:
+# Start the proxy
+dario proxy
 
-```
-headroom = 1 - max(util_5h, util_7d)
+# Point anything that speaks the Anthropic or OpenAI API at localhost:3456
+export ANTHROPIC_BASE_URL=http://localhost:3456
+export ANTHROPIC_API_KEY=dario
+export OPENAI_BASE_URL=http://localhost:3456/v1
+export OPENAI_API_KEY=dario
 ```
 
-The response's `anthropic-ratelimit-unified-*` headers are parsed back into the pool so the next request sees fresh utilization. An account that returns a 429 is marked `rejected` and routed around until its window resets. When every account is exhausted, incoming requests queue for up to 60 seconds waiting for headroom to reappear, with backoff-aware draining.
+Opus, Sonnet, Haiku, GPT-4o, o1, o3, o4, plus anything the configured OpenAI-compat backend serves. Streaming, tool use, prompt caching, extended thinking. **Zero runtime dependencies.** Auto-launches under [Bun](https://bun.sh) when available for TLS fingerprint fidelity with Claude Code's runtime on the Claude path.
 
-Accounts can use different plans — mix Max and Pro accounts freely. The pool doesn't care about tier, only headroom.
+---
 
-### Why pool over per-request tricks alone
+## Backends
 
-Per-request template replay is necessary but not sufficient for multi-agent workloads. Anthropic's classifier operates on cumulative per-OAuth-session aggregates (see the [FAQ entry](#faq) on multi-agent reclassification), and no amount of per-request hardening reaches that layer. The practical answer is *distribution* — spread load so no single account accumulates enough signal to trip anything. Pool mode is the piece that does that, and the headroom-aware selection means you don't have to think about which account is which; dario picks.
+Dario's routing is organized around **backends**, each with its own auth and its own target. v3.6.0 ships two backends, with more coming.
 
-### Inspection endpoints
+### 1. Claude subscription backend (built in)
 
-```bash
-# Live pool snapshot — per-account utilization, claim, status
-curl http://localhost:3456/accounts
+OAuth-backed Claude Max / Pro, billed against your plan instead of the API. Activated by `dario login`.
 
-# Pool analytics — per-account / per-model stats, burn-rate, exhaustion predictions
-curl http://localhost:3456/analytics
-```
+**What it does:**
 
-### Known scope for v3.5.0
+- Every request is replaced with a Claude Code template before it goes upstream — 25 tool definitions, 25KB system prompt, exact CC field order, exact beta headers, exact metadata structure. Only the conversation content is preserved. Anthropic's classifier sees what looks like a Claude Code session because, from the wire up, it *is* one — and that's what keeps your usage on subscription billing instead of Extra Usage.
+- **Billing tag** reconstructed using CC's own algorithm: `x-anthropic-billing-header: cc_version=<version>.<build_tag>; cc_entrypoint=cli; cch=<5-char-hex>;` where `build_tag = SHA-256(seed + chars[4,7,20] of user message + version).slice(0,3)`.
+- **OAuth config** auto-detected from the installed CC binary at startup. When Anthropic rotates `client_id`, authorize URL, or scopes, dario picks up the new values on the next run without needing a release.
+- **Multi-account pool mode** — see below. Automatic when 2+ accounts are configured.
+- **Framework scrubbing** — known fingerprint tokens (`OpenClaw`, `sessions_*` prefixes, orchestration tags) stripped from system prompt and message content before the request leaves your machine.
+- **Bun auto-relaunch** — when Bun is installed, dario relaunches under it so the TLS fingerprint matches CC's runtime. Without Bun, dario runs on Node.js.
 
-Pool mode v3.5.0 ships **headroom-aware selection across requests**. It does not yet retry a single in-flight request against a different account when that request 429s — that ships in v3.5.1 along with analytics recording wiring. Across-request routing is already effective: a 429 on one request immediately marks that account rejected, and the next request goes somewhere else.
+**Passthrough mode** (`dario proxy --passthrough`) does an OAuth swap and nothing else — no template, no identity, no scrubbing. Use it when the upstream tool already builds a Claude-Code-shaped request on its own and you just need the token auth.
 
----
+**Detection scope.** The Claude backend is a per-request layer. Template replay and scrubbing are designed to be indistinguishable from Claude Code at the request level. What they *cannot* defend against is Anthropic's session-level behavioral classifier, which operates on cumulative per-OAuth aggregates (token throughput, conversation depth, streaming duration, inter-arrival timing). The practical answer to that is **pool mode** — distributing load across multiple subscriptions so no one account accumulates enough signal to trip anything. See the [FAQ entry](#faq) for the full mechanism.
 
-## Multi-Provider Routing
+### 2. OpenAI-compat backend (v3.6.0+)
 
-*New in v3.6.0.* Dario is no longer Claude-only. Configure an OpenAI-compat backend once, and GPT-family model names at `/v1/chat/completions` route to that backend while Claude model names keep flowing through the Claude subscription path. Works with **any** OpenAI-compat provider — OpenAI, OpenRouter, Groq, a local LiteLLM instance, Ollama's openai-compat mode, whatever — via a configurable `--base-url`.
+Any provider that speaks the OpenAI Chat Completions API. Activated by:
 
 ```bash
 # OpenAI itself (default base URL)
@@ -221,74 +166,77 @@ dario backend add groq --key=gsk_... --base-url=https://api.groq.com/openai/v1
 # OpenRouter
 dario backend add openrouter --key=sk-or-... --base-url=https://openrouter.ai/api/v1
 
-# Local LiteLLM / Ollama / any openai-compat server
+# Local LiteLLM / vLLM / Ollama openai-compat mode
 dario backend add local --key=anything --base-url=http://127.0.0.1:4000/v1
-
-# Inspect
-dario backend list
 ```
 
-### How it routes
+Credentials live at `~/.dario/backends/<name>.json` with mode `0600`.
 
-After the proxy starts, every request at `/v1/chat/completions` is checked:
+**How it routes.** When the OpenAI-compat backend is configured, each request at `/v1/chat/completions` is checked:
 
 | Request model | Route |
 |---|---|
-| `gpt-*`, `o1-*`, `o3-*`, `o4-*`, `chatgpt-*`, `text-davinci-*`, `text-embedding-*` | OpenAI-compat backend (if configured) |
-| `claude-*` (or the shortcut `opus`/`sonnet`/`haiku`) | Claude subscription path |
-| Anything else on `/v1/chat/completions` | Claude subscription path with existing OpenAI-compat translation |
+| `gpt-*`, `o1-*`, `o3-*`, `o4-*`, `chatgpt-*`, `text-davinci-*`, `text-embedding-*` | OpenAI-compat backend |
+| `claude-*` (or `opus` / `sonnet` / `haiku`) | Claude subscription backend |
+| Anything else | Claude backend with OpenAI-compat translation |
 
-Point any tool that speaks the OpenAI Chat Completions API at `http://localhost:3456/v1` once, and both GPT and Claude models work through the same base URL. Cursor, Continue, Aider, any OpenAI SDK — they don't need to know anything changed.
+Dario's passthrough for the OpenAI-compat backend is literal: client request body goes upstream as-is, only the `Authorization` header is swapped for the configured API key and the URL is pointed at `baseUrl + /chat/completions`. Response body streams back unchanged.
 
-### Why this matters
+### Coming in a follow-up
 
-Dario's earlier layers (template replay, framework scrubbing, pool routing) keep the Claude subscription path defensible against Anthropic's classifier. Multi-provider routing changes the *game board*: when dario also speaks OpenAI and OpenAI-compat, a squeeze on the Claude side stops being an existential issue — traffic for affected workloads shifts to another backend, and dario is still useful. The moment Anthropic ships their own "bring your subscription to the API" feature, dario's Claude backend simplifies and keeps working. Either way, dario is still the local router between every model and every tool on your machine.
+- **Anthropic → OpenAI request translation** for `/v1/messages` requests with GPT-family model names (tool_use format, streaming delta conversion).
+- **Multiple simultaneous openai-compat backends** with per-model routing rules (`gpt-*` → OpenAI, `llama-*` → Groq, `mixtral-*` → OpenRouter).
+- **Fallback rules.** "If Claude 429s, use Gemini." v3.6.0 ships the routing plumbing; fallback logic layers on top.
 
-### Not yet in this release
+---
 
-- **Cross-format translation** (Anthropic → OpenAI). Requests at `/v1/messages` with GPT-family model names fall through to the existing Claude-side handling (which maps them to Claude equivalents). Full Anthropic → OpenAI request translation, including tool_use format conversion, lands in a follow-up.
-- **Per-model routing rules.** v3.6.0 supports one active openai-compat backend. Per-model selection (`llama-*` → Groq, `mixtral-*` → OpenRouter) ships next.
-- **Fallback rules.** "If Claude 429s, use Gemini" is a follow-up goal. v3.6.0 ships the routing plumbing; fallback logic layers on top.
+## Multi-Account Pool Mode
 
----
+*New in v3.5.0, for the Claude subscription backend.* Dario can manage multiple Claude subscriptions and route each request to the account with the most headroom. Single-account Claude dario is unchanged — pool mode activates **only** when `~/.dario/accounts/` contains 2+ accounts.
 
-## Dario and askalf
+```bash
+dario accounts add work
+dario accounts add personal
+dario accounts add side-project
+dario accounts list
+dario proxy
+```
 
-Dario is fully useful on its own — single-account mode is the default, pool mode (above) scales to as many Claude subscriptions as you want to add, and neither mode requires an account anywhere. Everything dario does is open-source and self-hosted.
+Each request picks the account with the highest headroom:
 
-[askalf](https://askalf.org) is the hosted platform built on top of the same OAuth and billing infrastructure, targeting the things a local proxy can't deliver by design:
+```
+headroom = 1 - max(util_5h, util_7d)
+```
 
-| | dario | askalf |
-|---|---|---|
-| **Accounts** | 1 (single) or N (pool mode) | Managed pool, no setup |
-| **Rate limits** | Distributed across your own pool | Distributed across the hosted fleet |
-| **Browser / desktop control** | No | Yes — full computer use |
-| **Scheduling** | No | Cron, webhooks, triggers |
-| **Persistent memory** | No | Per-agent context and state |
-| **Hosted dashboard** | No | Yes |
-| **Runs where** | Your machine | Hosted |
-| **Price** | Free | Paid |
+The response's `anthropic-ratelimit-unified-*` headers are parsed back into the pool so the next selection sees fresh utilization. An account that returns a 429 is marked `rejected` and routed around until its window resets. When every account is exhausted, requests queue for up to 60 seconds waiting for headroom to reappear.
+
+Accounts can mix plans — Max and Pro accounts can sit in the same pool; dario doesn't care about tier, only headroom.
+
+**Pool inspection endpoints:**
 
-Pool mode in dario covers the "I want multi-account routing on my own machine with my own subscriptions" case. askalf covers the "I want someone else to run this, with a dashboard, and 24/7 fleet capabilities my own machine can't give me" case. Dario is and will remain open-source and free.
+```bash
+curl http://localhost:3456/accounts     # per-account utilization, claim, status
+curl http://localhost:3456/analytics    # per-account / per-model stats, burn rate, exhaustion predictions
+```
 
-**[Join the askalf waitlist →](https://askalf.org)**
+**Scope.** v3.5.0 ships headroom-aware selection *across* requests — a 429 on one request marks the account rejected and the next request goes to a different one. Retrying a single in-flight request against a different account when that request 429s (inside-request failover) ships in v3.5.1 along with analytics recording wiring.
 
 ---
 
 ## Commands
 
 | Command | Description |
-|---------|-------------|
-| `dario login` | Log in (detects CC credentials or runs its own OAuth flow) |
+|---|---|
+| `dario login` | Log in to the Claude backend (detects CC credentials or runs its own OAuth flow) |
 | `dario proxy` | Start the local API proxy on port 3456 |
-| `dario status` | Show OAuth token health and expiry |
-| `dario refresh` | Force an immediate token refresh |
-| `dario logout` | Delete stored credentials |
+| `dario status` | Show Claude backend OAuth token health and expiry |
+| `dario refresh` | Force an immediate Claude token refresh |
+| `dario logout` | Delete stored Claude credentials |
 | `dario accounts list` | List accounts in the multi-account pool |
-| `dario accounts add <alias>` | Add a new account to the pool (runs OAuth flow) |
+| `dario accounts add <alias>` | Add a Claude account to the pool (runs OAuth flow) |
 | `dario accounts remove <alias>` | Remove an account from the pool |
 | `dario backend list` | List configured OpenAI-compat backends |
-| `dario backend add <name> --key=<k> [--base-url=<u>]` | Add an OpenAI-compat backend |
+| `dario backend add <name> --key=<key> [--base-url=<url>]` | Add an OpenAI-compat backend |
 | `dario backend remove <name>` | Remove an OpenAI-compat backend |
 | `dario help` | Full command reference |
 
@@ -296,23 +244,23 @@ Pool mode in dario covers the "I want multi-account routing on my own machine wi
 
 | Flag / env | Description | Default |
 |---|---|---|
-| `--passthrough` / `--thin` | Thin proxy — OAuth swap only, no template injection | off |
-| `--preserve-tools` / `--keep-tools` | Keep client tool schemas instead of remapping to CC tools | off |
-| `--model=<name>` | Force a model (`opus`, `sonnet`, `haiku`, or full ID) | passthrough |
+| `--passthrough` / `--thin` | Thin proxy for the Claude backend — OAuth swap only, no template injection | off |
+| `--preserve-tools` / `--keep-tools` | Keep client tool schemas instead of remapping to CC tools (Claude backend) | off |
+| `--model=<name>` | Force a model (`opus`, `sonnet`, `haiku`, or full ID). Applies to the Claude backend. | passthrough |
 | `--port=<n>` | Port to listen on | `3456` |
 | `--host=<addr>` / `DARIO_HOST` | Bind address. Use `0.0.0.0` for LAN, or a specific IP (e.g. a Tailscale interface). When non-loopback, also set `DARIO_API_KEY`. | `127.0.0.1` |
 | `--verbose` / `-v` | Log every request | off |
 | `DARIO_API_KEY` | If set, all endpoints (except `/health`) require a matching `x-api-key` or `Authorization: Bearer` header. Required when `--host` binds non-loopback. | unset (open) |
-| `DARIO_CORS_ORIGIN` | Override the browser CORS `Access-Control-Allow-Origin`. Useful for browser clients reaching dario over a mesh network. | `http://localhost:${port}` |
+| `DARIO_CORS_ORIGIN` | Override browser CORS origin | `http://localhost:${port}` |
 | `DARIO_NO_BUN` | Disable automatic Bun relaunch | unset |
-| `DARIO_MIN_INTERVAL_MS` | Minimum ms between requests (rate governor) | `500` |
+| `DARIO_MIN_INTERVAL_MS` | Minimum ms between Claude-backend requests (rate governor) | `500` |
 | `DARIO_CC_PATH` | Override path to the Claude Code binary for OAuth detection | auto-detect |
 
 ---
 
 ## Usage
 
-### Python
+### Python (Anthropic SDK)
 
 ```python
 import anthropic
@@ -330,6 +278,29 @@ msg = client.messages.create(
 print(msg.content[0].text)
 ```
 
+### Python (OpenAI SDK — same proxy, different provider)
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://localhost:3456/v1",
+    api_key="dario",
+)
+
+# gpt-4o routes to the configured OpenAI backend
+msg = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+# claude-opus-4-6 routes to the Claude subscription backend — same SDK, same URL
+claude_msg = client.chat.completions.create(
+    model="claude-opus-4-6",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+```
+
 ### TypeScript / Node.js
 
 ```typescript
@@ -347,38 +318,44 @@ const msg = await client.messages.create({
 });
 ```
 
-### OpenAI-compatible (Cursor, Continue, LiteLLM, Aider, …)
+### OpenAI-compatible tools (Cursor, Continue, Aider, LiteLLM, …)
 
 ```bash
 export OPENAI_BASE_URL=http://localhost:3456/v1
 export OPENAI_API_KEY=dario
 ```
 
-Any tool that accepts an OpenAI base URL works as-is. Claude model names pass through directly; GPT-style names (`gpt-4`, `gpt-5.4`, etc.) map to their closest Claude equivalents so tools with hardcoded OpenAI model lists work without code changes.
+Any tool that accepts an OpenAI base URL works. Use Claude model names (`claude-opus-4-6`, `opus`, `sonnet`, `haiku`) for the Claude backend, or GPT-family names for the configured OpenAI-compat backend.
 
 ### curl
 
 ```bash
+# Claude backend via Anthropic format
 curl http://localhost:3456/v1/messages \
   -H "Content-Type: application/json" \
   -H "anthropic-version: 2023-06-01" \
   -d '{"model":"claude-opus-4-6","max_tokens":1024,"messages":[{"role":"user","content":"Hello!"}]}'
+
+# OpenAI backend via OpenAI format
+curl http://localhost:3456/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer dario" \
+  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello!"}]}'
 ```
 
 ### Streaming, tool use, prompt caching, extended thinking
 
-All supported in both Anthropic and OpenAI SSE formats. Tool-use streaming emits `input_json_delta` events. Prompt caching works as-is. Extended thinking is routed through `reasoning_effort` in OpenAI format or the native `thinking` field in Anthropic format.
+All supported. Claude backend: full Anthropic SSE format plus OpenAI-SSE translation for tool_use streaming. OpenAI-compat backend: streaming body forwarded byte-for-byte.
 
 ### Library mode
 
-Dario is also importable:
-
 ```typescript
-import { startProxy, getAccessToken, getStatus } from "@askalf/dario";
+import { startProxy, getAccessToken, getStatus, listBackends } from "@askalf/dario";
 
 await startProxy({ port: 3456, verbose: true });
 const token = await getAccessToken();
 const status = await getStatus();
+const backends = await listBackends();
 ```
 
 ### Health check
@@ -387,43 +364,36 @@ const status = await getStatus();
 curl http://localhost:3456/health
 ```
 
-```json
-{
-  "status": "ok",
-  "oauth": "healthy",
-  "expiresIn": "11h 42m",
-  "requests": 47
-}
-```
-
 ---
 
 ## Endpoints
 
 | Path | Description |
-|------|-------------|
-| `POST /v1/messages` | Anthropic Messages API |
-| `POST /v1/chat/completions` | OpenAI-compatible Chat API |
-| `GET /v1/models` | Model list (works with both SDKs) |
+|---|---|
+| `POST /v1/messages` | Anthropic Messages API (Claude backend) |
+| `POST /v1/chat/completions` | OpenAI-compatible Chat API (routes by model name) |
+| `GET /v1/models` | Model list (Claude models — OpenAI models come from the OpenAI backend directly) |
 | `GET /health` | Proxy health + OAuth status + request count |
-| `GET /status` | Detailed OAuth token status |
+| `GET /status` | Detailed Claude OAuth token status |
+| `GET /accounts` | Pool snapshot (pool mode only) |
+| `GET /analytics` | Per-account / per-model stats, burn rate, exhaustion predictions (pool mode only) |
 
 ---
 
 ## Trust & Transparency
 
-Dario handles your OAuth tokens. Here's why you can trust it:
+Dario handles your OAuth tokens and API keys locally. Here's why you can trust it:
 
 | Signal | Status |
 |---|---|
-| **Source code** | ~2,000 lines of TypeScript across 7 files — small enough to audit in one sitting |
+| **Source code** | ~2,500 lines of TypeScript across 10 files — small enough to audit in one sitting |
 | **Dependencies** | 0 runtime dependencies. Verify: `npm ls --production` |
 | **npm provenance** | Every release is [SLSA-attested](https://www.npmjs.com/package/@askalf/dario) via GitHub Actions |
 | **Security scanning** | [CodeQL](https://github.com/askalf/dario/actions/workflows/codeql.yml) runs on every push and weekly |
-| **Credential handling** | Tokens never logged, redacted from errors, stored with `0600` permissions |
-| **OAuth flow** | PKCE (Proof Key for Code Exchange) — no client secret |
-| **Network scope** | Binds to `127.0.0.1` by default. `--host` allows LAN/mesh with `DARIO_API_KEY` gating. Upstream traffic goes only to `api.anthropic.com` over HTTPS |
-| **SSRF protection** | Only `/v1/messages` and `/v1/complete` proxy upstream — hardcoded allowlist |
+| **Credential handling** | Tokens and API keys never logged, redacted from errors, stored with `0600` permissions |
+| **OAuth flow** | PKCE (Proof Key for Code Exchange), no client secret |
+| **Network scope** | Binds to `127.0.0.1` by default. `--host` allows LAN/mesh with `DARIO_API_KEY` gating. Upstream traffic goes only to the configured backend target URLs over HTTPS |
+| **SSRF protection** | `/v1/messages` hits `api.anthropic.com` only; `/v1/chat/completions` hits the configured backend `baseUrl` only — hardcoded allowlist |
 | **Telemetry** | None. Zero analytics, tracking, or data collection |
 | **Audit trail** | [CHANGELOG.md](CHANGELOG.md) documents every release |
 
@@ -440,21 +410,21 @@ cd $(npm root -g)/@askalf/dario && npm ls --production
 ## FAQ
 
 **Does this violate Anthropic's terms of service?**
-Dario uses your existing Claude Code credentials with the same OAuth tokens CC uses. It authenticates you as you, with your subscription, through Anthropic's official API endpoints.
+Dario's Claude backend uses your existing Claude Code credentials with the same OAuth tokens CC uses. It authenticates you as you, with your subscription, through Anthropic's official API endpoints.
 
-**What subscription plans work?**
+**What subscription plans work on the Claude backend?**
 Claude Max and Claude Pro. Any plan that lets you use Claude Code.
 
 **Does it work with Team / Enterprise?**
 Should work if your plan includes Claude Code access. Not widely tested yet — open an issue with results.
 
 **Do I need Claude Code installed?**
-Recommended, not required. With CC installed, `dario login` picks up your credentials automatically. Without CC, dario runs its own OAuth flow against Anthropic's authorize endpoint.
+Recommended for the Claude backend, not strictly required. With CC installed, `dario login` picks up your credentials automatically. Without CC, dario runs its own OAuth flow against Anthropic's authorize endpoint.
 
 **Do I need Bun?**
-Optional, recommended. Dario auto-relaunches under Bun when it's available so the TLS fingerprint matches CC's runtime. Without Bun, dario runs on Node.js and works fine; the TLS fingerprint is the only difference. Install: `curl -fsSL https://bun.sh/install | bash`.
+Optional, recommended for Claude-backend requests. Dario auto-relaunches under Bun when available so the TLS fingerprint matches CC's runtime. Without Bun, dario runs on Node.js and works fine; the TLS fingerprint is the only difference.
 
-**First time setup on a fresh account.**
+**First time setup on a fresh Claude account.**
 If dario is the first thing you run against a brand-new Claude account, prime the account with a few real Claude Code commands first:
 ```bash
 claude --print "hello"
@@ -462,17 +432,20 @@ claude --print "hello"
 ```
 This establishes a session baseline. Without priming, brand-new accounts occasionally see billing classification issues on first use.
 
-**What happens when my token expires?**
-Dario auto-refreshes tokens 30 minutes before expiry. `dario refresh` forces an immediate refresh if something goes wrong.
+**What happens when Anthropic rotates the OAuth config?**
+Dario auto-detects OAuth config from the installed Claude Code binary. When CC ships a new version with rotated values, dario picks them up on the next run. Cache at `~/.dario/cc-oauth-cache-v3.json`, keyed by the CC binary fingerprint. Falls back to hardcoded CC 2.1.104 prod values if CC isn't installed.
 
-**What happens when Anthropic rotates the OAuth client_id or URL?**
-Dario auto-detects OAuth config from your installed Claude Code binary. When CC ships a new version with rotated values, dario picks them up on the next run — no dario release needed. Cache at `~/.dario/cc-oauth-cache-v3.json`, keyed by the CC binary fingerprint. If CC isn't installed, dario falls back to hardcoded CC 2.1.104 prod values.
-
-**I'm hitting rate limits. What do I do?**
-Claude subscriptions have rolling 5-hour and 7-day usage windows. Check utilization with Claude Code's `/usage` command or the [statusline](https://code.claude.com/docs/en/statusline). Dario's rate-limit errors include utilization percentages and reset times so you can see exactly when capacity returns.
+**I'm hitting rate limits on the Claude backend. What do I do?**
+Claude subscriptions have rolling 5-hour and 7-day usage windows. Check utilization with Claude Code's `/usage` command or the [statusline](https://code.claude.com/docs/en/statusline). For multi-agent workloads, add more accounts and let pool mode distribute the load: `dario accounts add <alias>`.
 
 **My multi-agent workload is getting reclassified to overage even though dario template-replays per request. Why?**
-Because reclassification at high agent volume is not a per-request problem. Anthropic's classifier operates on cumulative per-OAuth-session behavioral aggregates — token throughput, conversation depth, streaming duration, inter-arrival timing, thinking-block volume. Dario can make each individual request indistinguishable from Claude Code and still hit this wall on a long-running agent session, because the wall isn't at the request level. Thorough diagnostic work on this was contributed by [@belangertrading](https://github.com/belangertrading) in [#23](https://github.com/askalf/dario/issues/23), including the per-request v3.4.3 and v3.4.5 hardening that landed as a result. For the session-layer shaping itself — multi-account pooling, session rotation, workload distribution that keeps any single account from concentrating the behavioral signal — that's what [askalf](https://askalf.org) is built for. Different layer, different tool.
+Reclassification at high agent volume is not a per-request problem. Anthropic's classifier operates on cumulative per-OAuth-session aggregates — token throughput, conversation depth, streaming duration, inter-arrival timing, thinking-block volume. Dario's Claude backend can make each individual request indistinguishable from Claude Code and still hit this wall on a long-running agent session, because the wall isn't at the request level. Thorough diagnostic work on this was contributed by [@belangertrading](https://github.com/belangertrading) in [#23](https://github.com/askalf/dario/issues/23), including the v3.4.3/v3.4.5 hardening that landed as a result. The practical answer at the dario layer is **pool mode** — distribute load across multiple subscriptions so no single account accumulates enough signal to trip anything. See [Multi-Account Pool Mode](#multi-account-pool-mode).
+
+**Can I route non-OpenAI providers through dario?**
+Yes — anything that speaks the OpenAI Chat Completions API. `dario backend add groq --key=... --base-url=https://api.groq.com/openai/v1`, `dario backend add openrouter --key=... --base-url=https://openrouter.ai/api/v1`, or point at a local LiteLLM / vLLM / Ollama-openai-compat server with `--base-url=http://localhost:4000/v1`. v3.6.0 supports one active OpenAI-compat backend at a time; per-model routing to multiple OpenAI-compat backends ships in a follow-up.
+
+**Does dario work with only the OpenAI backend, no Claude subscription?**
+Yes. Don't run `dario login`, just run `dario backend add openai --key=...` and `dario proxy`. Claude-backend requests will return an authentication error; OpenAI-compat requests will work normally. Dario becomes a local OpenAI-compat shim with no Claude involvement.
 
 **Why "dario"?**
 It's a name, not an acronym. Don't overthink it.
@@ -493,15 +466,19 @@ Longer-form writing on how dario works and why it works that way:
 
 ## Contributing
 
-PRs welcome. The codebase is ~2,000 lines of TypeScript across 7 files:
+PRs welcome. The codebase is ~2,500 lines of TypeScript across 10 files:
 
 | File | Purpose |
 |---|---|
-| `src/proxy.ts` | HTTP proxy server, rate governor, billing tag, response forwarding |
-| `src/cc-template.ts` | Template engine, tool mapping, orchestration & framework scrubbing |
+| `src/proxy.ts` | HTTP proxy server, request handler, rate governor, Claude backend dispatch |
+| `src/cc-template.ts` | CC request template engine, tool mapping, orchestration & framework scrubbing |
 | `src/cc-template-data.json` | CC request template data (25 tools, 25KB system prompt) |
 | `src/cc-oauth-detect.ts` | OAuth config auto-detection from the installed CC binary |
-| `src/oauth.ts` | Token storage, PKCE flow, auto-refresh |
+| `src/oauth.ts` | Single-account token storage, PKCE flow, auto-refresh |
+| `src/accounts.ts` | Multi-account credential storage and independent OAuth lifecycle |
+| `src/pool.ts` | Account pool, headroom-aware routing, failover target selection |
+| `src/analytics.ts` | Rolling request history, per-account / per-model stats, burn-rate |
+| `src/openai-backend.ts` | OpenAI-compat backend credential storage and request forwarder |
 | `src/cli.ts` | CLI entry point, command routing, Bun auto-relaunch |
 | `src/index.ts` | Library exports |