Skip to content
hakkisagdicPublic

About

Forge an API key out of any coding CLI. Serve Command Code, opencode, Claude Code, Qoder and Copilot behind one OpenAI-compatible /v1 endpoint — with failover, streaming, sessions and Cloudflare named tunnels. Zero dependencies.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

183 Commits

Folders and files

Repository files navigation

keysmith

Forge an API key out of any coding CLI.

You already pay for Command Code, opencode, Claude Code, Qoder, Kiro, Copilot — and their credentials are logins, not keys. Apps that only speak Authorization: Bearer cannot use them. keysmith runs each CLI once per request, reads its event stream, and serves the result as an OpenAI-compatible endpoint:

POST /v1/chat/completions   { "model": "cmd/evren/glm-5.3", ... }        →  cmd -p …
POST /v1/chat/completions   { "model": "evren/gpt-4.1", ... }            →  direct HTTP
POST /v1/chat/completions   { "model": "cheap", ... }                    →  alias chain, in order

One config file, one port, one key. Zero dependencies — Node 20+ and nothing else.

git clone https://github.com/hakkisagdic/keysmith.git && cd keysmith
node src/cli.js init                 # writes ~/.config/keysmith/config.json (0600) + one API key, shown to your terminal only
node src/cli.js add agy              # attach a built-in profile (a tool-less one: see "Agents that could act on this machine")
node src/cli.js add evren --base-url https://your-gateway/v1 --key '{json:~/.local/share/opencode/auth.json#evren.key}'
node src/cli.js doctor               # is each adapter actually alive, and what does it cost
node src/cli.js serve --tunnel       # http://127.0.0.1:8787/v1 (+ Cloudflare tunnel)

Point anything at it:

curl -N http://127.0.0.1:8787/v1/chat/completions \
  -H "Authorization: Bearer $KEYSMITH_KEY" -H 'content-type: application/json' \
  -d '{"model":"agy/gemini-3.8-flash-low","stream":true,"messages":[{"role":"user","content":"one-line haiku"}]}'

Should you actually do this?

Honest tradeoffs, because a CLI behind an HTTP port is not free:

HTTP adapter (a real API) CLI adapter (a rented agent)
Tokens you're billed the ones you sent yours plus the harness's own system prompt
Latency first token in a few hundred ms process spawn + agent boot, typically +1–3 s
Tool calls forwarded verbatim the CLI runs them itself, it will not hand them back
Concurrency many low — one process is one agent
State stateless the CLI keeps a session on disk; keysmith maps it

Command Code is the clearest case: every call carries roughly a 16 000-token agent prompt that is billed to you. That is the price of renting its harness — the upside is that a subscription you already pay for becomes usable from a phone app, a IDE plugin, or a script that only knows /v1. keysmith reports what the upstream actually charged, never what you wished it charged; keysmith usage is the place to see it.

So: prefer an HTTP adapter when you have one. Use a CLI adapter for the credentials that would otherwise be trapped inside a terminal. And keep an alias chain that mixes both — that is the interesting part.

What it gives you

Route Notes
POST /v1/chat/completions OpenAI Chat Completions, streaming and not
POST /v1/messages Anthropic Messages, for Claude Code and friends
POST /v1/responses OpenAI Responses (Codex-style input arrays + UHP stateful previous_response_id)
GET /v1/responses/:id UHP / Responses API stored response lookup
GET /.well-known/uhp, GET /v1/uhp Universal Harness Protocol (2026-10-19) discovery (unauthenticated)
GET /v1/harnesses UHP harness catalogue (GET /v1/harnesses/:id, GET /v1/harnesses/:id/models)
POST /v1/embeddings forwarded to HTTP adapters only
GET /v1/models the whole catalogue, namespaced; ?refresh re-queries
GET /v1/keysmith/routes adapters, aliases, limits and any unusable alias leg (alias_warnings) as JSON
GET /v1/keysmith/usage whole-log audit statistics (?by=…&since=…&until=…), spend caps, and ?tail=N recent entries
GET / status page in a browser: post the key once through its form, a cookie opens it for an hour
GET /healthz keyless liveness probe for a supervisor

Everything under /v1 needs Authorization: Bearer <key> or x-api-key (?api_key= is off by default; when enabled via auth.allowQueryApiKey: true, it is accepted only from direct loopback clients with no cf-connecting-ip or x-forwarded-for header). A key can carry a scope — the adapters, models and aliases it may reach — and every route above answers it with that share only; see Keys with a scope.

Universal Harness Protocol (UHP) & HarnessRouter Relay

Keysmith natively speaks the Universal Harness Protocol (UHP 2026-10-19) in both directions:

  1. As a UHP Server: Any UHP client or SDK can discover capabilities at GET /.well-known/uhp (or GET /v1/uhp), inspect attached harnesses at GET /v1/harnesses (filtered by the caller key's scope), route to a specific harness via metadata.harness_id or x-harness-id, chain stateful multi-turn sessions on POST /v1/responses with previous_response_id (GET /v1/responses/:id), enforce Idempotency-Key deduplication (409 idempotency_conflict on payload mismatch), and propagate W3C traceparent / tracestate headers.
  2. As a UHP Upstream Relay (harnessrouter profile): Connect a running HarnessRouter Community Edition (http://127.0.0.1:8000/api/harness/v1) or Cloud (https://api.harnessrouter.ai/v1) instance as an upstream HTTP adapter:
keysmith add harnessrouter                                                # local CE on 127.0.0.1:8000
keysmith add harnessrouter --base-url https://api.harnessrouter.ai/v1 --key '{env:HARNESSROUTER_API_KEY}'

Address models across any backend or custom harness:

  • harnessrouter/<model> (e.g. harnessrouter/claude-sonnet-4-6)
  • harnessrouter/<backend>/<model> (e.g. harnessrouter/claude/claude-sonnet-4-6, harnessrouter/gemini/gemini-2.5-pro)
  • harnessrouter/chrn_<id> (routes directly to a custom harness with metadata.harness_id)

When a request offers client tools to a wire: "uhp" adapter, Keysmith first forwards them natively over /v1/responses; if the upstream CLI backend ignores the tools and replies with plain text, Keysmith automatically falls back to EMULATE (fallback: "uhp_emulate"). 3. Traycer Multi-Provider Gateway (traycer HTTP profile): Attach your Traycer subscription (~/.traycer/cli/credentials or TRAYCER_BEARER_TOKEN) as an explicit-only multi-provider HTTP adapter:

keysmith add traycer

Keysmith discovers all 32 models from GET https://server.traycer.ai/api/traycer/models across five upstream providers (anthropic, openai, xai, meta, openrouter), sends x-traycer-account-context: PERSONAL, and routes each model to its native Traycer inference endpoint (/inference/anthropic/messages, /inference/openai/responses, or /inference/{xai,meta,openrouter}/chat/completions) with reasoning effort and client tool support via EMULATE (tool_mode: "emulate").

Models are namespaced

<adapter>/<upstream model> — only the first slash separates, because upstream ids contain slashes of their own (openrouter/deepseek/deepseek-v4-flash, oc/evren/glm-5.3). A bare id with no slash routes to the adapter of that name, so cmd alone means "cmd's default model".

keysmith models --refresh    # what this gateway exposes, and from where

Aliases: failover, and the cheapest route that works

"aliases": {
  "cheap": ["evren/deepseek-v4-flash", "ollama/qwen3:4b", "oc/evren/deepseek-v4-flash"]
}

Declared order wins. keysmith tries the next candidate only while nothing has reached the client — a half-delivered answer is never restarted, because the user already saw part of it. That makes aliases safe to point at a laptop's whole toolchain: a direct API first, a local model second, an agent CLI last.

Aliases are edited from the command line, so a live config never has to be opened (it holds the gateway key):

keysmith alias                                              # every alias and its legs
keysmith alias argon agy/gemini-4-argon-high google/gemini-4-argon   # set a chain
keysmith alias chat --prepend agy/gemini-4-argon-high       # a new first leg; the others keep their order
keysmith alias chat --append ollama/qwen3:4b                # a new last leg (a leg already there moves)
keysmith alias chat --drop ollama/qwen3:4b                  # take one out
keysmith alias cheap-public groq/openai/gpt-oss-120b mistral/codestral-latest cloudflare/@cf/meta/llama-3.1-8b-instruct-fast --allow-explicit-only
keysmith alias chat --delete

A leg has to name an attached adapter (--force saves one you have not attached yet), an alias cannot name another alias or share an adapter's name, a tool-capable adapter is always refused (whether marked unsafeTools or carrying an auto-approve flag), and an explicitOnly adapter is refused unless that alias opts in with --allow-explicit-only (aliasPolicy.<name>.allowExplicitOnly). After a change the same checks doctor runs are printed, so a model the adapter does not list is said then, not discovered as a slow failover later.

To expose a curated explicit-only failover chain without weakening other routes, pass --allow-explicit-only on that alias alone: modelsOnly still rejects unlisted models, doctor and keysmith alias flag any paid/priced leg on it, other aliases still skip explicitOnly legs, and exhausting the chain returns its error without falling through elsewhere. Separately, HTTP reachability probes (keysmith doctor and MCP keysmith_test) use each profile's cheap GET health path — such as Cloudflare's /client/v4/accounts/<account>/tokens/verify, with healthPath overriding the profile and /models as fallback — under a 15 s timeout, never reading response bodies or issuing paid chat calls.

The gateway reads its config once, when it starts. add, remove, set, alias and key add|scope|revoke change the file, not the running gateway: while one runs they say so, with the restart command (launchctl kickstart -k gui/$UID/dev.keysmith.gateway under launchd, keysmith stop && keysmith start otherwise), and keysmith status says when the config is newer than the gateway. Until then a new alias is a 404, a disabled adapter keeps answering, a revoked key keeps working and a key keeps the scope it had.

Which is also why a typo in a chain is invisible at request time: a leg naming an adapter you do not have gets skipped, and a leg naming a model the adapter never heard of gets rejected upstream and failover'd — both look like a slightly slow provider, while quietly answering from a route you did not choose and did not price. So keysmith reads every alias leg off the config at startup and names the unusable ones in keysmith doctor, on the status page, in GET /v1/models (keysmith.errors) and in GET /v1/keysmith/routes (alias_warnings). A leg pointing at a dynamic catalogue (a CLI with no models declared) can't be checked without spawning it — that's what keysmith doctor --probe-models is for.

Per-adapter knobs that shape a route: priority (orders the flat listing), disabled, timeoutMs, maxConcurrent (a semaphore, so five browser tabs cannot fork five agents), stripSystemPrompt, maxPromptChars, headers, modelMap, modelParams, defaultModel, explicitOnly, and toolMode (whether a CLI leg takes tool requests, see Tool calls). One field of an attached adapter changes with keysmith set <adapter> <field> <value> (the value is JSON when it parses, a string otherwise; --unset removes the field; nothing is echoed back, since the field may be apiKey). A value the gateway would refuse to load — a modelParams that is not an object of fields, an args with an auto-approve flag, an http adapter without baseUrl — is refused before it replaces a working entry (--force saves it anyway, and says the adapter will not load); credentials are not resolved for that check, so a key only launchd can see is fine. What an entry has, and the rest of these commands: Changing an attached adapter.

Virtual models: automatic complexity & congestion routing

virtualModels lets clients send one model name such as auto/text (or auto/vision) while keysmith picks a concrete adapter/model per request:

"virtualModels": {
  "auto/text": {
    "classifier": "ollama-local/qwen3.8:8b",
    "tiers": {
      "simple": ["ollama-local/qwen3.8:8b"],
      "medium": ["ollama-local/qwen3.8:14b", "gemini-cli/gemini-2.5-flash"],
      "complex": ["claude-cli/claude-sonnet-4-6", "claude-api/claude-opus-4-6"]
    },
    "loadGate": { "maxLoadPerCore": 0.8, "maxMemoryPressure": "warn" },
    "stickySeconds": 120
  }
}

When the machine is congested (loadGate), keysmith skips the classifier and routes to the first remote candidate of medium (or tiers.congested). Otherwise a matching rules entry labels an obvious prompt without asking, else it asks classifier for a one-word label (simple|medium|complex, under classifierPrompt when set; defaulting to medium on failure; the call is held to the classifier adapter's spend cap and gets its own usage row), tries the tier's candidates in order, and falls through on 429 / quota / timeout / 5xx to the next candidate and the next tier up. Key scopes allowing auto/* are enforced against the concrete target at routing time, every routed request logs {virtual, label, chosen, fallbacks, reason, latency} in usage.jsonl, /v1/models lists virtual models, and keysmith route explain auto/text "<prompt>" dry-runs the decision without calling the target. See docs/adapters.md.

Sessions: multi-turn out of a stateless client

OpenAI clients resend history; CLIs are stateful. keysmith hands back an opaque kss_… id (in the body, in x-keysmith-session, and in the last SSE chunk) and maps it onto the upstream session — cmd --resume, opencode --session. Send it back on the next request and the CLI continues its own thread, which is also how you get prompt caching. Sessions live in memory: restart the gateway and clients start fresh.

Tool calls, thinking

A request that offers tools — tools (or the older functions) on /v1/chat/completions, tools on /v1/messages and on /v1/responses — walks its route in the order the route was declared, and each leg takes the tools the way it can:

  • An HTTP upstream on the face's own wire gets the client's body verbatim (passthrough): the openai wire on /v1/chat/completions, the anthropic wire on /v1/messages — so Claude Code's tool requests reach an Anthropic API key (claude-api) as Claude Code wrote them, server tools, thinking and its anthropic-beta features (an OAuth one aside) included, with the adapter's own key and model id. Its answer comes back byte for byte, its usage read into the row; a refusal before anything went out (a 429, a 529) hands the request to the next leg. Any other pairing — an openai-wire leg on /v1/messages, every HTTP leg on /v1/responses — has no verbatim relay, so there the leg is passed by.
  • A CLI with a toolMode answers through a tool engine. The CLI runs without tools of its own, as it does for text; the model writes its calls, and keysmith hands them to the client as tool_calls (tool_use blocks on /v1/messages, function_call items on /v1/responses), streamed or not, with keysmith's own ids. keysmith never runs a tool: the client does, behind its own approvals, and sends the result back on its next request.

On /v1/responses the tools are {"type": "function", "name", "parameters"}; a custom tool (a freeform one, such as Codex's apply_patch) and the hosted ones (web_search, file_search, computer_use_preview, code_interpreter, mcp, …) are what no CLI can honour. The history is read from input: function_call items are their assistant turn's calls, function_call_output items their results by call_id — a step's calls with their outputs after all of them, or each call followed by its output, read alike, as one assistant turn and its results; reasoning items are left out. keysmith stores no response, so send the whole input, as Codex's store: false requests do: a request that names previous_response_id, a conversation or an item_reference, or holds a function_call_output with no function_call before it, is a 400 (with tools or without), as OpenAI answers an id it does not have — never an answer built from what the request carries alone. A call goes out as a function_call item (an fc_ item id, keysmith's call_ call id) after the message item that holds the text before it; streamed, as response.output_item.added, response.function_call_arguments.delta and .done, response.output_item.done, and response.completed carries the whole output — the openai SDK's responses.create and responses.stream(...).get_final_response() read both (checked with openai 2.54.0). A failure after the stream started is an error event and response.failed. A request without tools is answered as it always was.

  • A CLI without one (toolMode absent or off: kiro and the profiles marked unsafeTools) is passed by.

A leg passed by is named in the request's usage row (skippedLegs: target, a reason code — tool_mode_off, wire_no_tools, unsupported_tools, credit_guard — and why in words), and keysmith doctor lists, per alias, how many legs carry a tool request on /v1/messages and on /v1/chat/completions, and which legs requests were passed by in the last 24 h.

Which built-in profile answers how: agy, opencode, codex, qoder and claude with auto — the MCP bridge, and EMULATE where the bridge cannot, through the same tool-less agent and argv as their text runs. Each answered a two-turn round trip live (2026-10-20, both ways: opencode on evren/deepseek-v4-flash, codex on gpt-5.6-luna, qoder on its default model; agy is the live acceptance's; 2026-11-03, the bridge: claude on Claude Code 2.1.303 with haiku at effort low on all three faces, see Claude Code). claude stays explicit-only: a tool request reaches it only by its name, never through an alias, since every request spends your Claude subscription. kiro not yet — its EMULATE argv (emulateArgs) is in the profile and checked against a stub of its stream, but no live run got past its overage limit, so keysmith set kiro toolMode emulate is yours to make once one does.

That is a change of order for a route that mixes the two: a CLI leg with a toolMode now takes tools where it stands in the chain. In argon (agy/gemini-4-argon-high, then google/gemini-4-argon) a tool request goes to agy first, and to Google when agy fails before answering. keysmith set agy toolMode off puts it back the way it was.

toolMode, per CLI adapter:

Mode What answers a tool request
off (absent) nothing: the leg is passed by
emulate EMULATE, below
mcp the MCP bridge, below, always: a tool_choice that forces a call is a 400 (MCP cannot make a model call a tool), so are the older functions (no call id to continue a session by), a bridge with no room a 503 with retry-after, a CLI with no bridge driver (agy, opencode, codex and qoder have one) a 503
auto the bridge where it can take the request, EMULATE otherwise, and EMULATE in the same request when the bridge fails before any call went out. tool_choice: "none" is a text answer; required or a named tool is EMULATE (MCP cannot make a model call a tool); tool names too long for the bridge, a bridge with no room, a CLI with no bridge driver, the older functions is EMULATE — with the reason in the usage row (fallback: name_too_long, bridge_full, no_bridge, legacy, or what made the bridge fail: unknown_agent, ready_timeout, …)

Any mode but off needs the entry's cwd: a tool engine runs the CLI only in an empty workspace keysmith owns, never in the gateway's own directory (an entry without one does not load; every built-in profile has one).

There is no mode that runs both engines at once and takes the faster: it would spend the CLI's quota twice per turn for what the fallback gives anyway.

EMULATE. The request's tools (their schemas as sent), the rules its tool_choice and parallel_tool_calls set, and the whole conversation — earlier calls and their results included — are written into one prompt that asks for exactly one JSON object back: {"tool_calls":[{"name":…,"arguments":{…}}]} or {"final":"…"}. The reply is read strictly: that object alone, or alone in one ```json fence. Prose around it, a second object, another key, a call the client's own schema refuses (unknown tool, missing or extra arguments, a wrong type), a final answer where tool_choice asks for a call, two calls where parallel calls are off — each is an invalid reply, asked for once more with the reason in front (not the reply), inside the same timeoutMs. A second invalid reply is a 502 tool_emulation_error that says why; a reply is never passed on as text in place of a call. On a stream nothing of the answer goes out until the JSON is whole and checked — the client gets keepalives meanwhile — and calls then arrive the way a provider streams them. Every turn renders the whole transcript again: no CLI session is resumed on this path, and no x-keysmith-session is handed back. A tool result is the least trusted text in the prompt: it is fenced with a per-request nonce no text of the request contains, and the prompt says it is data, not instructions. The most an instruction hidden in one can do is make the model write a call — checked against the client's schema, then the client's to approve, as a provider's would be.

The MCP bridge (agy, opencode, codex, qoder, claude; toolMode auto or mcp). The CLI runs with one MCP server whose tools are the request's own, and the model calls them the way it calls any tool. That server is keysmith: the CLI starts a shim (node src/bridge/shim.js) that relays to the gateway over a Unix socket — 0600, under ~/.local/share/keysmith/run/, no TCP, so no tunnel reaches it — with a token per session. A call the client's schema refuses goes back to the model with the reason, and the model tries again (three such calls in one turn fail it). A call that fits goes to the client as tool_calls, with keysmith's id, and the HTTP answer ends there, while the CLI waits in the same process on its call. The client runs the tool and sends the result in its next request, as it would to a provider: keysmith finds the session the call belongs to and gives the CLI the result as the call's MCP result, and what it does next — text, or its next call — is that request's answer. A turn after the first sends the CLI one tool result, not the transcript again. Text the model writes before a call stays in the answer that carries it. agy, codex, qoder and claude run the calls of one step one after another (asked for two at once, codex, qoder and Claude Code sent the second only after the first one's result), so a step with three calls is three HTTP turns of one call each, whatever parallel_tool_calls says. opencode sends them at once: the calls that arrive within 600 ms of each other go out in one answer, and the next request brings all their results (with parallel_tool_calls: false, one call per answer, the others waiting in the session).

How each CLI is given the server, and kept to it (src/bridge/agy.js, src/bridge/clis.js):

CLI The session's server What else it may call
agy a session agent .agents/agents/ks-b-<rid>.md with mcpServers as a list, every tool eager nothing: tools: [], no inherited MCP servers or customizations, no harness sections
opencode OPENCODE_CONFIG names the session's config: mcp.<server> (local, its timeout past toolResultTimeoutMs) and an inline agent (--agent ks-b-<rid>), merged under the workspace's deny-all opencode.json permission and tools "*" denied, <server>_* alone allowed; --pure: no plugin
codex -c mcp_servers.<server>.… on its command line, the token in a 0600 file the shim reads (KEYSMITH_BRIDGE_TOKEN_FILE), never in the argv; default_tools_approval_mode="approve" for that server alone (with approval_policy="never" an unapproved MCP call is refused), tool_timeout_sec past toolResultTimeoutMs the text argv's: no shell, read-only sandbox, no web search, no user config; --ephemeral, so no session on disk
qoder --mcp-config <file> --strict-mcp-config, --allowed-tools mcp__<server> --tools ""; --setting-sources project and --settings '{"disableAllHooks":true}' (with project settings alone, your plugin hooks still ran headless); --no-session-persistence; every inherited QODER_* variable left out
claude --mcp-config <file> --strict-mcp-config (the token in that 0600 file, never the argv), --allowedTools mcp__<server>, --permission-prompts none; MCP_TOOL_TIMEOUT past toolResultTimeoutMs --tools ""; --setting-sources "" (no settings file, no CLAUDE.md: with project, a CLAUDE.md in a parent directory of the workspace reached the prompt), --settings '{"disableAllHooks":true,"autoMemoryEnabled":false}' and CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 (auto-memory stays on under --setting-sources "": its MEMORY.md reached the prompt as instructions, with a section telling the model to keep memories with the Write tool, and a "remember this" request reached for Read), --disable-slash-commands; ENABLE_TOOL_SEARCH=false (no tool-search tool of Claude Code's own); --no-session-persistence; no CLAUDECODE/CLAUDE_CODE_* variable of a session the gateway was started in. Not --safe-mode: it turns --mcp-config's server off too

A request's tool names must fit under the model's 64-character limit behind the name the CLI gives a bridge tool: mcp_ks<rid6>_ on agy, ks<rid6>_ on opencode, mcp__ks<rid6>__ on codex, qoder and claude. A longer one is EMULATE's (fallback: "name_too_long").

A request continues a session only when it is the same conversation: its last assistant turn holds exactly the calls the session waits for and one result for each follows it, with nothing after the results, it comes with the same gateway key, for the same target, with the same tools and the same system and user turns. Anything else — another key presenting a valid id, an edited history, a session that is gone, a conversation that goes on after its calls were answered — runs on a new session whose prompt carries the conversation so far, earlier calls and fenced results written the EMULATE way (the cold path, "path": "cold" in the row; a result for a session that expired is logged as late). A result with text of the user's after it — a /v1/messages user turn that holds the tool_result and then a text block, as Claude Code-style clients send reminders; a user message after the tool message — is the cold path too: a waiting CLI can be given a call's result, not a user turn, and text folded into the result would reach the model as a tool's output, which it is told is data. The session that waited for that result is closed then. A second request carrying a result that another request is already answering is a 409. The older functions/function_call carry no call id a later request could continue, so auto answers them with EMULATE (fallback: "legacy") and mcp refuses them with a 400.

  • Clock. bridge.readyTimeoutMs (30 s): the CLI lists the bridge's tools within it, and until it has, nothing of the answer goes out — so a session that fails before that (an agent agy cannot find, a config opencode does not read, a shim that never connects, an exit) leaves the same request to EMULATE under auto. timeoutMs counts the CLI generating only, up to its next call or its end. bridge.toolResultTimeoutMs (300 s) is how long a session waits for the client's result; then the CLI is stopped and its files removed, and the result, when it comes, is answered on the cold path — a tool behind a slow human approval still works, at the price of a cold turn. opencode, codex and Claude Code are told to wait 30 s longer than that on a call (opencode's and codex's own default is 60 s; Claude Code's MCP_TOOL_TIMEOUT — a 2 s one cancelled a held call at 2 s), so keysmith's clock ends a session first. bridge.sessionMaxMs (30 min) and bridge.maxTurns (32 calls) cap a session; past them the conversation goes on on a new one. A client that leaves in the middle of a turn stops the CLI.
  • Room. Each waiting session is a live CLI process. Measured while a call waited: agy 1.4.2 about 1 GB, most of it the MCP servers of your own agy config, which agy starts for every run although the session's agent inherits none of them (they are not offered to the model: a one-tool turn cost ~1,300 input tokens); opencode 1.19.3 about 690 MB, qodercli 1.1.59 about 370 MB, Claude Code 2.1.303 about 230 MB, codex 0.163 about 110 MB (each with the ~50 MB shim). So bridge.maxSessions is 2 per adapter, limits.bridge.maxSessions 2 in all, and limits.bridge.maxSessionsPerKey 1 — a key that opens a session over its share gives up its oldest waiting one. With no room, auto is EMULATE and mcp a 503. A waiting session holds no process slot (maxConcurrent), so the CLI's text requests are not held up by clients running tools.
  • What the CLI may call. Its session has the request's tools as its only ones (the table above). A call in its stream to anything but the bridge's tools and the one harness tool each CLI keeps that runs nothing — agy's manage_task, opencode's invalid (its answer to a call of a tool it does not have), qoder's mcp_get (reads a tool's schema) — stops the run at once, whether a request is reading it or a call of its is with the client: the request is a 502 that is never answered another way — not by EMULATE, not by the route's next leg, an HTTP upstream included — the log says SECURITY … foreign tool and the usage row failure: "foreign_tool". A call that was with the client goes nowhere: the request that brings its result gets the same 502 (another key's request with that history is a new one). On codex any item that is not text, reasoning, its plan or a warning is such a call (a shell command, a file change, a web search, a sub-agent, an item type keysmith has never seen); on claude any tool_use block that is not the bridge's (Claude Code keeps no harness tool here); opencode reports a call only once it has finished, so there the tripwire comes after the fact of a call its config already denied. keysmith still runs no tool.
  • Long results. A result goes to the CLI whole, up to the adapter's maxPromptChars (over it, the request is a 400). Claude Code 2.1.303 writes an MCP result over about 50,000 chars to ~/.claude/projects/<workspace>/<session>/tool-results/, leaves it there after the session, and shows the model a 2 KB preview and the path — for it to Read, which is the tripwire's. So the bridge lists each tool to Claude Code with _meta: {"anthropic/maxResultSizeChars": maxPromptChars}: a 190,000-char result reached the model whole, and nothing was written there. Claude Code honours that only up to 500,000 chars, so on an entry whose maxPromptChars is higher the _meta says 500,000 and a longer result is a 400 (result_too_long) before it reaches Claude Code: raising the cap does not move it.
  • Files. agy: .agents/agents/ks-b-<rid>.md in its workspace (0600; it holds the session's token) and agy's schema cache for the server, ~/.gemini/antigravity-cli/mcp/ks<rid6>/. opencode, codex, qoder, claude: .keysmith-bridge/ks-b-<rid>.* in the workspace (a 0700 directory; each file 0600). All removed when the session closes, and every session is closed when the gateway stops. A gateway that was killed leaves them; the next keysmith serve removes the ones older than an hour. opencode keeps each run's session in its own storage, as it does for a text run; codex (--ephemeral), qoder and claude (--no-session-persistence) keep none.
  • What it rests on. Behaviour no document promises: agy 1.4.2's mcpServers as a list, its eager key, its mcp_<server>_<tool> names, the server/discover it asks first, its schema cache; opencode's OPENCODE_CONFIG merge and inline agents, codex's per-server default_tools_approval_mode, qoder's disableAllHooks, Claude Code's --setting-sources "", autoMemoryEnabled, CLAUDE_CODE_DISABLE_AUTO_MEMORY, MCP_TOOL_TIMEOUT, ENABLE_TOOL_SEARCH and a tool's anthropic/maxResultSizeChars. A CLI that changes one fails the readiness gate, and auto answers with EMULATE — except an approval codex stops honouring: its call is refused before it reaches keysmith, and the model answers in text without it.

The usage row of a bridge turn says which session answered and how it was reached: "bridge": {"session": "ks3f9a0c", "path": "new" | "attached" | "cold", "turn": 2}.

  • Tokens per turn. One CLI run answers several HTTP turns, and each answer's usage is its own share of the run, what the upstream charged — the harness's system prompt and the cache included (input with cached_tokens; on /v1/messages the uncached input_tokens with cache_read_input_tokens and cache_creation_input_tokens). claude reports each model step as Claude Code prints it (input and cache exact; the output count is the stream's first), and the answer that ends the run reports Claude Code's total less what the earlier answers did, so a session adds up to it exactly. codex and qoder report a run's tokens once, when it ends: the answer that hands a call out has no counts — its usage says "keysmith_usage": "unknown" and the reason, a count is null where the client's parser takes null and 0 only where it requires a number (Unknown usage on the wire), and its usage row is null, never a 0 — and the answer that ends the session carries the whole run — a session that ends otherwise (its clock, a client that never comes back) reports nothing of what it spent. A call that comes from a step an earlier answer reported (a serial driver's second call of one step) has no counts either, with that reason.

When no leg answers with tools. A leg that fails before anything reached the client hands the request to the next one; a call handed to the client is an answer, never retried elsewhere. If every leg could take the tools and each one refused (a 429, a 400), the client gets the refusal with the provider's status and message — not the same request again without its tools. A leg that cannot carry the tools is never asked for a text answer in their place: a client that offered tools (Claude Code) breaks on one without a word. So for tool_choice auto, required or a named tool the client gets an error — the last refusal of a leg that took the tools (its status kept: a 429 stays a 429), its message naming the legs passed by and why, or, when no leg of the route can carry them, a 400 invalid_request_error that names each leg and the reason (kiro/… cannot carry this request's tools — toolMode off …; on /v1/messages, in the Anthropic error shape). Only tool_choice none — the client asked for text — is answered as a plain completion by the legs not tried. A request without tools is answered as it always was. A tool no CLI can honour (an OpenAI custom tool, an Anthropic server tool such as web_search_*) passes every CLI leg by and is a 400 naming it when no HTTP leg relays it. A request that offers more than 128 tools (tools and the older functions together; OpenAI's own limit) is a 400 before any leg is asked, on both faces.

A streamed request holds its headers for limits.streamHoldMs (below). An EMULATE turn on Argon takes 9–44 s, so the stream usually opens before its answer is known; an HTTP leg that the route falls over to after that carries on in the open stream, as long as the client has had SSE comments only — once keysmith wrote a frame of its own (reasoning the client asked for), that leg is not asked at all, since its answer could not go out. A tool_emulation_error inside the hold is an HTTP 502, streamed or not; after the stream opened it is the stream's error frame (an error chunk and [DONE]; an error event on /v1/messages), which the openai SDK raises as an APIError with no status and does not retry on its own. x-keysmith-mode says passthrough, emulate or mcp — on a stream, the engine that was running when the headers went out, and none when the route fell back to a plain completion (tool_choice none). The usage row says which engine answered (toolMode), how many calls it handed over (toolCalls), retries, and why the engine is not the one auto picks first (fallback); never an argument or a result. What a tool engine spent is in the row even when it failed: a 502's row has its usage, toolMode and retries, and for the bridge why it failed (failure: foreign_tool, ready_timeout, invalid_calls, …); a bridge turn that spent a model step and then failed before any call (auto answering the same request with EMULATE) is counted in that answer's usage, the client's included; when a tool leg failed and a later leg answered (or failed too), usage and retries count every leg, and failedLegs names each tool leg that failed before — target, engine, status, failure, its own retries and usage. GET /v1/keysmith/routes lists each adapter's tool_mode, and the status page marks it.

keysmith set <adapter> toolMode auto (or emulate) on an adapter attached before toolMode existed fills in what the engine needs and the entry lacks — emulateArgs, bridge, and agy's keysmith-tools agent file — from the built-in profile that runs the same binary with the same parser; it never replaces a field the entry has. A CLI marked unsafeTools never takes a toolMode (a load error), and neither does an HTTP adapter.

An upstream's 429 and 503 keep their status on every path, with its retry-after when it sent one, so a client backs off the way it would talking to the provider directly. When failover moved on from a 429/503 and the next leg refused for a reason of its own, the client gets the 429/503: that is why the route failed. A streamed request holds its headers until the first event that is part of its answer (text, a call, reasoning, an error) — an engine asking its CLI again, or saying which engine runs, does not end the hold — for up to limits.streamHoldMs (10 s), so a refusal in that time keeps its status too; one that comes later — a CLI or a model slower than that, an error in the middle of an answer — is an SSE error frame on a 200. Auth failures stay 401/403; other upstream failures are a 502.

Gemini with tools: the google profile

keysmith add google                                              # reads {env:GOOGLE_API_KEY}
keysmith add google --key '{dotenv:~/project/.env#GOOGLE_API_KEY}'  # or where the key already lives

Google's own OpenAI-compatible endpoint (https://generativelanguage.googleapis.com/v1beta/openai), so google/gemini-3.8-flash is the API itself: tools, tool_choice, streaming and tool_calls go through verbatim, which the agy CLI adapter cannot do. The catalogue drops Google's models/ prefix (stripModelPrefix), so ids read the way requests send them.

Thought signatures. Gemini 3 returns an opaque signature with each step's function call — tool_calls[].extra_content.google.thought_signature, streamed or not — and refuses the next turn if a replayed call comes back without it (400 INVALID_ARGUMENT: Function call is missing a thought_signature in functionCall parts). Most OpenAI clients, LangChain's ChatOpenAI among them, rebuild the assistant message from the fields they know and drop it. With thoughtSignatures: true (on in the profile) the adapter reads the answer as it passes — the bytes reach the client unchanged — keeps each signature, and on the next request puts it back on a call that arrived without one. Only on the call it came with: Gemini's ids are short (call_10078), and two conversations, or two steps of one, draw the same id. So a signature is kept under the gateway key the request came with, the call id, the function name and the arguments (compared parsed, since clients re-serialize them); calls that agree on all of that are told apart by the conversation before them. A call that names no function, comes with another gateway key, or cannot be told apart gets nothing, and Gemini's 400 reaches the client. A signature the client did send is left alone. The store lives in the gateway's memory, one per upstream URL — every adapter on that endpoint shares it, so a failover leg to a second key can put back what the first leg saw: 4096 entries, 16 MiB, 6 hours, whichever comes first ("thoughtSignatures": {"maxEntries": …, "maxBytes": …, "maxAgeMs": …} to change them; the largest any adapter asks for wins), and it is never logged. A call the gateway never saw — before a restart, from another process — gets nothing, and Gemini's 400 reaches the client: Google's documented bypass value degrades the model, so keysmith does not send it.

Checked live on 2026-10-16 (gemini-3.6-flash): the replayed history without the signature was refused with that 400, and the same history through the adapter answered.

Quota. On the free tier each model allows about 20 requests a day per project — a 429 RESOURCE_EXHAUSTED that keysmith passes on as a 429 — and the count is the key's, shared with anything else that uses the same key, such as a direct google: client. A tool loop spends one request per step.

A CLI that emits thinking (cmd, Claude, opencode) keeps it to itself unless the request says "include_reasoning": true — then it arrives as delta.reasoning_content on /v1/chat/completions. The other two faces drop it.

Gemini 4 Argon at its highest effort

Two routes reach it, and they spell the effort differently:

  • agy puts the effort in the model id: agy/gemini-4-argon-low|medium|high. high is Argon's maximum — agy refuses --effort max and --effort xhigh for it. Through the tool-less keysmith-text agent, agy/gemini-4-argon-high answered "Reply with exactly: OK" in 3.2 s. A request with tools is answered too (toolMode: "auto" in the profile): the tool-less keysmith-tools agent writes the calls, EMULATE hands them over (see Tool calls).

  • google (the API) lists gemini-4-argon, takes tools, and takes OpenAI's reasoning_effort field. keysmith builds the body of a plain completion itself, so the effort goes in the adapter's modelParams, which is sent with that model and no other:

    keysmith set google modelParams '{"gemini-4-argon":{"reasoning_effort":"high"}}'

    On the tool relay the client's body goes upstream verbatim; modelParams fills in only what the client did not set, so a client that chose its own effort keeps it — in any spelling: reasoning_effort, reasoning: {effort}, or Google's thinking_config (under extra_body.google or google). Then no effort field from modelParams is added at all: Google's documentation says reasoning_effort and a thinking budget cannot be used together, and that 400 would count as the leg refusing the tools. high here matches agy's -high; the Google leg was not run live with it.

So one alias drives Argon both ways, agy first:

keysmith alias argon agy/gemini-4-argon-high google/gemini-4-argon

A plain request is answered by agy and fails over to the API. A request with tools goes to agy as well when its adapter has a toolMode (keysmith add agy brings auto), and to the API leg when agy fails before answering; an agy entry with no toolMode (one attached before it existed) passes tool requests to the API leg, as it always did. Each leg spends its own quota: your Antigravity login for agy, the API key's (free tier: about 20 requests a day per model) for google.

Reasoning effort on codex and Claude Code

A request's effort reaches the codex and claude CLIs: reasoning_effort or reasoning: {effort} on /v1/chat/completions and /v1/responses, output_config: {effort} on /v1/messages, streamed or not, text and tool runs alike — codex gets -c model_reasoning_effort="<level>", Claude Code --effort <level>. A client that cannot send one (OpenBot) names it in the model id, as agy does: codex/gpt-6-astra-xhigh, claude/sonnet-max. GET /v1/models lists those ids from each CLI's own catalogue — codex debug models, and Claude Code's answer to an initialize request (no prompt, nothing spent) — one per level the model takes, and a scoped key reaches them as its patterns are written (codex/gpt-6-astra* does, codex/gpt-6-astra does not).

curl -s localhost:8787/v1/chat/completions -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"model":"codex/gpt-6-astra","reasoning_effort":"xhigh","messages":[{"role":"user","content":"…"}]}'

A level the model does not take is a 400 that names the ones it does, from the catalogue (gpt-6-astra: low, medium, high, xhigh, max, ultra; gpt-6-luna has no ultra; Haiku 4.5 takes none) — never a guess, never the request without it. No effort named is the argv of before, so the CLI's own default. Other CLIs (agy, opencode, qoder) are handed no effort, as before, and the usage row says so (effortIgnored). An MCP bridge session keeps the effort it started at; a continuation at another one is a new session (the cold path). Details: docs/adapters.md.

Agents that could act on this machine

A CLI adapter runs an agent, and an agent has tools: a shell, file edits, MCP servers. Behind a tunnel, a request that can reach such an adapter can make it act on this machine. So every built-in CLI profile that can be made tool-less is: it runs in an empty directory keysmith owns (~/.local/share/keysmith/workspaces/<name>), with the CLI's own switches for "no tools", and no auto-approve flag. The ones that cannot are marked unsafeTools and ship disabled. Every CLI profile has its own workspace — under launchd the gateway's working directory is keysmith's source tree, and no agent runs there; keysmith add custom gives a hand-written adapter one too.

Profile How its tools are taken away Checked
agy --agent keysmith-text: an agent file with tools: [], no MCP, no customizations; stopAtToolCall for the one tool agy keeps. A tool request (EMULATE) runs --agent keysmith-tools, the same tools: [] agent with the JSON protocol as its prompt: the calls go to the client, agy runs none live, agy 1.3.3; the tool protocol probed on agy 1.4.2
agy, MCP bridge a tool request on the bridge runs --agent ks-b-<rid>, a session agent as tool-less as keysmith-tools whose one MCP server is keysmith (a Unix socket, a token per session) offering the request's tools and nothing else; each call goes to the client, never run by agy or keysmith; a call to any other tool stops the run (502, the tripwire) stub agy in the tests; the MCP shape (list, eager, mcp_<server>_<tool>, server/discover, a held tools/call) probed on agy 1.4.2; live, agy 1.4.2 on gemini-3.8-flash-low: two turns of one call through both faces on one agy process, nothing left after
opencode, codex, qoder, MCP bridge the text argv's tool-less switches, and one MCP server — keysmith, over the same socket and per-session token — offering the request's tools and nothing else: opencode an inline session agent that allows <server>_* alone (OPENCODE_CONFIG, over the workspace's deny-all opencode.json); codex that server approved alone (approval_policy="never" refuses any other call), the token in a 0600 file, never the argv; qoder --strict-mcp-config, no built-in tool, no hooks, no inherited QODER_*; each call goes to the client, never run by the CLI or keysmith; a call to any other tool stops the run (502, the tripwire) stub CLIs in the tests; live 2026-10-20 on opencode 1.19.3, codex 0.163.0, qodercli 1.1.59: two turns of one call on one process each, opencode's two calls of one step in one answer, and nothing — process, shim, session file — left after a session closed
kiro --agent keysmith-text: tools: [], mcpServers: {}, includeMcpJson: false, resources: []; --trust-tools= trusts nothing; stopAtToolCall argv and agent file accepted by kiro-cli 2.27.1; its first live run was refused for quota before any text
claude --tools "", --strict-mcp-config, --permission-prompts none, --disable-slash-commands, --safe-mode, --max-turns 1 — a request with an image the same, with --input-format stream-json and the prompt on stdin; an EMULATE run the text argv parsed by Claude Code 2.1.261; the image run live on 2.1.303 (sonnet), both faces
claude, MCP bridge the session's one MCP server (--mcp-config, --strict-mcp-config) offering the request's tools, allowed alone (--allowedTools mcp__<server>); --tools "", --permission-prompts none, --setting-sources "" (no settings file, no CLAUDE.md), hooks, auto-memory and skills off, ENABLE_TOOL_SEARCH=false, no session on disk, each tool listed with anthropic/maxResultSizeChars = maxPromptChars, at most 500,000 (a longer result is a 400; no result left in a file of Claude Code's); each call goes to the client, never run by Claude Code or keysmith; a call to any other tool stops the run (502, the tripwire) a stub Messages endpoint, Claude Code 2.1.303: the request offered the session's tools and nothing else, no CLAUDE.md in its prompt, two calls of one step sent one after the other; live the same day on haiku (effort low): a two-turn round trip on each face, two tools of one step in three turns, nothing — process, shim, session file — left after; then, against the stub, a canary MEMORY.md kept out of the prompt and a 190,000-char result reaching it whole, and live on haiku a 59,986-char result whose last line the model quoted and a "remember this" request answered in text
qoder --tools "", --strict-mcp-config parsed by qodercli 1.1.59
codex --disable shell_tool, --sandbox read-only, approval_policy="never", web_search="disabled", --disable goals, --ignore-user-config (no MCP servers from your config), plugins/apps/browser/computer-use off, agents.max_threads=1 a stub Responses endpoint, codex 0.163.0: gpt-5.5 is offered request_user_input and apply_patch (the read-only sandbox refuses it); gpt-6-* keep code mode's exec (no shell) and sub-agent tools no switch removes — capped at one sub-agent
opencode --agent keysmith-text (permission: {"*": deny}, tools: {"*": false}) and a workspace opencode.json denying every tool to any agent; no --auto; stopAtToolCall a stub OpenAI endpoint, opencode 1.18.27: no tools offered, a bash call the model made anyway ran nothing; its free tier (opencode/*) refuses this run with a 403
cmd — (cannot be done: a -p run approves its own tool calls) unsafeTools; Command Code 1.81.0's bundle
gemini — (never run from here) unsafeTools until a tool-less argv is checked against a real install
warp — (cannot be done, see below) unsafeTools

Two marks keep an adapter out of routes it was not asked for by name:

  • explicitOnly: true — the adapter answers a request that names it (claude/sonnet) and nothing else: never a general alias leg (keysmith alias refuses it unless the alias opts in with --allow-explicit-only; a hand-edited leg without opt-in is skipped and named in doctor, /v1/models and the routes endpoint), never probed by doctor --probe-models. For an adapter that spends something you keep for yourself; the claude profile ships it, and keysmith add <profile> --explicit-only sets it on any other.
  • unsafeTools: true — keysmith could not take the CLI's tools away. Everything explicitOnly does, and the profile ships disabled: true. Serving it is a decision with its own flag: keysmith set <id> disabled false --allow-unsafe-tools, and so is any later change to what it runs or how it is stopped — stopAtToolCall, args, resumeArgs, visionArgs, bin, env, cwd, parser, modelsFrom; only note, models, defaultModel, priority, timeoutMs, maxConcurrent, maxPromptChars and explicitOnly change without it, and turning it off never needs it. Its profile also sets stopAtToolCall: "always" where the parser can see tool calls: the run is stopped at the first one it reports, and a call before any text fails the request. That limits the damage, it is not a sandbox — the harness may have started the command by the time keysmith sees the call.

An argv with an auto-approve flag (--auto, --yolo, --dangerously-skip-permissions, --full-auto, --trust-all-tools, --permission-mode yolo, --sandbox danger-full-access, agy's --mode auto and --mode accept-edits, …) — in any of its templates: args, resumeArgs, emulateArgs, the bridge's args — does not load unless the entry is marked unsafeTools: the gateway reports it as a load error (doctor, /v1/models, the routes endpoint) and a request to it is a 503 naming the flag. An entry marked unsafeTools, in turn, never takes a toolMode other than off (a load error too): a CLI that kept its own tools is never handed a tool request. A config written by an older keysmith — the opencode profile used to pass --auto — stops there; keysmith add opencode --as <id> copies the tool-less argv over it. A re-add never drops a guard: explicitOnly, unsafeTools, disabled and a toolMode: "off" on the entry it replaces are kept, and it says so — taking one off is a keysmith set. The mark brings toolMode: "off" with it: a re-add that keeps unsafeTools over a profile with a tool engine (agy's auto), and keysmith set <id> unsafeTools true, turn the engine off and say so.

Warp (oz) is the unsafeTools one. oz agent run takes an agent profile by id; profiles are made in the Warp app, the default one lets the agent run commands and edit files, and the permission values a profile has only ask or allow — none denies. Nothing on oz's command line removes the tools. Every run is also recorded in your Warp account (a run_url on oz.warp.dev). /usr/local/bin/warp-cli is Cloudflare WARP, a VPN client — the profile uses the oz inside Warp.app.

Command Code (cmd) keeps its tools. A cmd -p run answers every tool confirmation itself with "allow" (Command Code 1.81.0: a headless run is autoAllow), and -p withholds only its interactive tools (ask_user_question, plan mode, todo_write, cron, taste) — shell, read, write and edit stay, and --max-turns 1 limits the turns after a call, not the call. So cmd is unsafeTools: it ships disabled, and when served it is stopped at its first tool_queued event, which comes before its permission check. A cmd adapter attached before this keeps serving until it is re-added (keysmith add cmd, which arrives disabled) or switched off (keysmith set cmd disabled true).

Claude Code: explicit-only, tools over MCP

The claude profile is explicit-only as shipped, so keysmith add claude puts it in no alias and no probe, and a re-add (to pin its bin, say) keeps it that way. That is what a setup whose own work runs on the same Claude subscription needs: every request to claude/… spends that subscription, and only a request that names it does.

Such a request may offer tools (toolMode: "auto", since 2026-11-03): Claude Code runs with one MCP server, keysmith's, whose tools are the request's, and with nothing of its own to call — no built-in tool, no settings file, no CLAUDE.md, no hooks, no skills, no tool search, no prompt, no session on disk; the token in a 0600 file. Each call it makes goes to the client as tool_calls (tool_use on /v1/messages, function_call on /v1/responses), streamed or not; the client's next request brings the result into the same Claude Code process, which answers or calls again; any other tool in its stream stops the run (the tripwire). Where the bridge cannot take a request (a forced tool_choice, no room), EMULATE answers through the tool-less text argv. Claude Code 2.1.303, live on haiku at effort low through a keysmith gateway:

Face Turns Latency Tokens (input / cached / output per turn)
/v1/chat/completions, not streamed call get_weather, then the answer 6.1 s, 3.5 s 4290 / 0 / 32, then 4396 / 4288 / 51
/v1/messages, streamed call, then the answer 3.5 s, 3.2 s 4288 / 0 / 32, then 4393 / 4286 / 50
/v1/responses, streamed (claude/haiku-low) call, then the answer 3.2 s, 2.5 s 4292 / 0 / 32, then 4399 / 4290 / 52
/v1/chat/completions, two tools in one step get_weather, get_time (no model step: null, with the reason), the answer 3.8 s, 0.02 s, 1.8 s 4313 / 0 / 32, then null, then 4559 / 4311 / 121

Claude Code's own prompt here is about 4.3k tokens, and it is cached after the first turn. A waiting session is about 230 MB of Claude Code and 50 MB of shim.

A claude entry attached before this keeps what it had — toolMode: "off", its argv without {effort}, no model listing — so its clients get what they always did. keysmith upgrade claude lists what the profile gained; --take args,resumeArgs,visionArgs,modelsFrom,toolMode --apply brings the effort, the listing and the tool engine (until every argv has {effort}, a request's effort is not applied, and the row says effortIgnored).

Images, PDFs, audio, video. An adapter takes the media its media lists (image, pdf, audio, video; vision: true is image), and a request that carries some reaches it as the thing itself: claude/<model> gets images and PDFs on Claude Code's stdin as one stream-json message, through the same tool-less switches; an HTTP upstream gets each user turn as a content array in its own wire — OpenAI image_url / input_audio / file / video_url, Anthropic image / document. The faces take each kind in their own shape (image_url, input_audio, file, video_url on /v1/chat/completions; image, document on /v1/messages; input_image, input_file, input_audio on /v1/responses), inline or as a URL, which keysmith fetches from the public internet only — never from this machine or its network, by address, by name or by redirect ("fetchMedia": false refuses URLs instead). The kind is read off the bytes. Per adapter, at most 20 images of 5 MB and 5 files of 20 MB (maxImages, maxImageBytes, maxFiles, maxFileBytes); every item is read before anything is sent, so a bad one is a 400 that costs nothing. A kind an adapter does not take reads as a label, [image omitted by keysmith], [PDF omitted by keysmith] … The claude, openai, anthropic, google and copilot profiles ship their media; an entry attached before this gets it with keysmith upgrade <id> --apply. Details: docs/adapters.md.

Ollaya (ollaya.dev) is out of scope: it is a local runtime for decision models — typed questions answered with calibrated probabilities over their options, on /v1/decisions and /v1/systemone — not a chat-completion API, so there is no /v1/chat/completions for an adapter to forward to.

Secrets stay out of the config

An adapter's apiKey is a reference, resolved at load and never written to a log:

"{env:OPENAI_API_KEY}"
"{file:~/.config/keys/copilot}"
"{json:~/.local/share/opencode/auth.json#evren.key}"
"{dotenv:~/project/.env#GOOGLE_API_KEY}"
"{exec:security find-generic-password -s copilot-api -w}"
"sk-live-…"

The {json:…} and {dotenv:…} forms are the ones that matter: they reuse a credential an agent or a project already keeps, so you never paste a key twice and nothing secret lands in this repo. {dotenv:…} reads one NAME=value (or export NAME=value, quoted or not) and executes nothing; a LaunchAgent does not see your shell's exports, so it is also how a gateway under launchd reaches a key a project's .env holds. A literal works too, but the file is 0600 for a reason.

A provider key is redacted the way the gateway key is: once an adapter has resolved it, every log line, usage row, error message (the client's included) and the status page show AIza…39 fp:… in its place, and anything shaped like a Google key (AIza + 35) is taken out even when nothing here registered it.

The gateway key, and what is logged

The key clients send (ks_…) is printed in full by keysmith init --reveal and keysmith key list|add --reveal only, and only when stdin and stdout are an interactive terminal; keysmith key add <label> --out <file> writes a new one to a new 0600 file instead. A terminal alone is not enough: a coding agent's terminal tool (tmux, expect, script) opens a real one, and what it reads lands in a transcript — --reveal is the word it has to type on purpose. Without it, piped, redirected or under launchd, those commands print the redacted form instead, and so does everything else keysmith writes:

ks_Q…35 fp:3f9a0c12      first 4 characters · length · first 8 hex of sha256(key)

keysmith key revoke fp:3f9a0c12 takes that fingerprint, and only that: a key on the command line is in shell history and in every local user's ps. A script that needs the key itself reads it from the config into a variable, never onto stdout:

KEY=$(jq -r '.auth.keys[0] | .key? // .' ~/.config/keysmith/config.json)   # a bare key, or one with a scope

An agent gets a key of its own instead, written to a file only it reads: keysmith key add <label> --deny … --out <file> (see Keys with a scope).

file (in ~/.local/share/keysmith/) written by holds
launchd-gateway.log launchd: serve's stdout + stderr start banner (address, adapters, the key redacted, tunnel URL); with KEYSMITH_VERBOSE=1, adapter failures, retries and skipped alias legs
keysmith.log keysmith start: the same stream the same, for a gateway started without launchd
usage.jsonl the gateway, one line per request (active UTC month) time, key ("fp:…"), label, scope/skipped, adapter, kind (http/cli), host (HTTP upstream host alone), account (credential name, never its value), model, face (chat/messages/responses/embeddings), status, ms, bytesIn/bytesOut, upstreamId, tag (x-keysmith-tag), token counts (input every input token charged, the cache's included, with cacheRead and cacheWrite beside it; or usage: null with a usageReason when the CLI or upstream reported none), cost ({usd, basis, listUsd?, reason?}), stream, client, error, retries/cutAt, and for tool requests toolMode, toolCalls, fallback, failure, failedLegs (see Tool calls)
usage.jsonl.YYYY-MM the gateway, on UTC month rollover closed calendar months of the audit log: the current UTC month always lives at usage.jsonl so tail -F ~/.local/share/keysmith/usage.jsonl keeps working, and when a new UTC month begins the finished file moves to usage.jsonl.YYYY-MM; nothing is ever deleted
.usage.jsonl.daily the gateway, on each metered request today's live per-key request and daily-cap refusal counts (0600, by fingerprint, never a key), so keysmith usage and /status see refusals that write no JSONL line
launchd-tunnel.log launchd: cloudflared cloudflared's own output

keysmith does not log prompts, answers, request headers or request URLs, and a request whose URL does not even parse is answered 400 without a word about it. The status page does not take ?api_key= at all: it asks for the key in a form, and keeps a cookie that opens that page alone, for an hour. Error messages can quote anything a CLI printed, so every log line and every usage row goes through the same redaction: the configured keys — as written, as JSON escapes them, and any run of 12 or more of their characters a cut left behind — and anything shaped like a minted key, whole or cut, come out as above. (Note: hashed keys stored as keyHash via keysmith key add --hash do not keep their plaintext secret in config.json, so registerSecrets cannot register their exact string; if a client echoes a custom hashed key into a prompt or upstream error message, exact-string redaction cannot redact it from logs, though standard ks_…-shaped tokens are still redacted by pattern.) Messages are redacted before they are shortened, streamed text (keysmith chat --stream, cloudflared's output) is redacted across the pieces it arrives in, and an error nothing caught is reported redacted too. The files are 0600 in a 0700 directory; serve, start and install-service tighten older ones, and the launchd agents run with Umask 077, so a log launchd re-creates after it was deleted or rotated is 0600 as well. Logs from a keysmith older than this still hold the key in full:

keysmith scrub-logs                 # the logs and their rotated copies, rewritten in place; counts only, never a key
keysmith scrub-logs path/to/file…   # and any other file the key reached: another KEYSMITH_DATA, a transcript

A scrub rewrites what it can reach. A key that was in a log may also be in copies it cannot — backups, rotated archives, an agent's transcript — so when scrub-logs finds a configured key it says to rotate it: keysmith key add --reveal in a terminal, move the clients over, keysmith key revoke fp:<old>, restart the gateway. keysmith status says when the running gateway is older than the code or the config on disk and needs that restart.

Keys with a scope: what each key may reach

A bare key in auth.keys reaches every adapter and every alias. That is what every key did before scopes, and what a key nobody scoped still does. A key can instead carry an allow list, a deny list, or both:

"auth": {
  "enabled": true,
  "keys": [
    "ks_…",
    { "key": "ks_…", "label": "ada",   "deny":  ["claude-api"] },
    { "key": "ks_…", "label": "scout", "allow": ["agy", "alias:argon"] }
  ]
}
pattern matches
claude-api an adapter id: every model of that adapter
agy/*, google/gemini-3.8-* a glob over adapter/model; * is any run of characters, / included
alias:argon, alias:* an alias, by name
  • No allow list means everything that is not denied. An allow list means only what it names, aliases included: an allow-listed key names each alias it may use (alias:argon).
  • deny wins over allow.
  • An alias is checked twice: the key may name it, and then each leg on its own. A leg outside the scope is skipped — never run, so its provider never hears of the request — and the next leg answers; the request is refused only when no leg is left. It is the leg that is checked, not the alias, so a leg added to an alias later cannot take a key past its scope.
  • A glob is checked against the model as requested and, when the adapter's modelMap rewrites it, as sent upstream. A bare adapter id (claude-api) is checked with its defaultModel; with none, a key whose scope covers only some of that adapter's models is refused — it has to name the model, since the upstream would otherwise pick one.
  • A glob is a string match on the id as written, not a spending limit. keysmith knows one other spelling and checks a deny against it too: an adapter with stripModelPrefix (Google's models/) answers google/models/gemini-4-argon as gemini-4-argon, so google/gemini-4-* keeps both out. What else an upstream treats as the same model — a dated snapshot and its undated alias, say — it cannot know. To keep a credit out, deny the adapter id (claude-api), or give the key an allow-list.
  • A request outside the scope is a 403 (permission_error) whose message names the adapter and never the key. Every face enforces it the same way: /v1/chat/completions (the tool relay included), /v1/messages, /v1/responses, /v1/embeddings.
  • What a scoped key can list is its share: /v1/models (an alias with only the legs it may run), /v1/keysmith/routes, /v1/keysmith/usage and the status page, whether it is opened by header or by the cookie its own login set. An adapter the key cannot reach is not even asked for its model list. Its usage is its own: the rows it wrote (for what it may still name), and a summary whose keys holds its own fingerprint only — never another key's requests, not even for a model both may name.
  • Every usage row says which key it came with and what the scope decided: "key": "fp:3f9a0c12", "scope": "unscoped" | "allowed" | "denied", and "skipped": […] for alias legs it left out. Opened by an unscoped key, the status page lists every key by fingerprint, label and scope, with its requests and refusals of the last 24 h.
  • It fails closed. An entry with a field keysmith does not know ("alow" would otherwise read as "no allow list"), a list that is not a list of patterns, or one key listed twice with two different scopes leaves that key reaching nothing — every request a 403 that says why — and doctor, key list, the gateway log and the status page name it. A key list whose entries are all unreadable opens nothing; it never turns into a keyless gateway.
  • A pattern that names nothing configured — "deny": ["Claude-API"] written by hand, when the adapter is claude-api — is not an error (it may name an adapter you add later), but it keeps nothing out, so serve, doctor, key list and the status page (to an unscoped key) warn about it, with a hint when a configured name differs only in case or _/-.
  • With auth.enabled false no key is asked for, so no scope applies: key add, key scope and key list say so.

From the command line, by fingerprint (a key on the command line is in shell history and ps):

keysmith key add ada --deny claude-api --out ~/.config/ada/keysmith.key   # a new key with a scope, in a new 0600 file
keysmith key add scout --allow agy,alias:argon     # comma-separated, or the flag repeated
keysmith key scope fp:3f9a0c12 --deny claude-api   # narrow a key that exists; --allow/--deny replace that list
keysmith key scope fp:3f9a0c12 --no-allow          # drop one list; --clear drops both (unscoped again)
keysmith key scope fp:3f9a0c12                     # show it
keysmith key list                                  # each key redacted, with its label and its scope
keysmith key who-can claude-api                    # the fingerprints that reach an adapter, and the ones kept out
keysmith key who-can alias:argon                   # …or an alias, or one adapter/model

key add prints the new key the way it always has: in full only with --reveal, to an interactive terminal (with its fingerprint, which key scope and key revoke take). --out <file> writes it to a new file, mode 0600, for an agent to read ({file:…} in its config, or KEY=$(cat …)). An existing file is not overwritten (--force replaces it), and when the file cannot be written no key is added. A pattern that names no configured adapter or alias is refused, because a deny-list typo keeps nothing out; --allow-unknown saves it anyway (for an adapter you are about to add). --force does not: a script that rotates an agent's key into the same file passes --force every time. Quote a glob, or the shell expands it. key add with neither a label nor a scope still writes a bare key. Passing --hash stores only the SHA-256 keyHash in config.json ({ "keyHash": "<sha256-hex>", … }) and shows the full key once at creation (key list marks hashed entries with hashed (sha256)). Key changes (key add, key scope, key revoke) signal a running keysmith serve instance with SIGHUP and are also reloaded automatically when config.json changes on disk.

explicitOnly and a scope answer different questions: explicitOnly keeps an adapter out of aliases for every key; a scope keeps one key away from an adapter however it asks for it.

A daily cap: how much a key may ask

A scope says what a key may reach; perDay says how often. It caps the requests a key may make in one local calendar day:

{ "key": "ks_…", "label": "ada", "deny": ["claude-api"], "perDay": 300 }
keysmith key add changelog --allow alias:cheap-public,groq/openai/gpt-oss-120b,mistral/codestral-latest,cloudflare/@cf/meta/llama-3.1-8b-instruct-fast --per-day 200 --out ~/.config/changelog/keysmith.key
keysmith key scope fp:3f9a0c12 --per-day 300   # cap it (the scope and the label stay as they are)
keysmith key scope fp:3f9a0c12 --no-per-day    # lift it; --clear drops the lists and leaves the cap
keysmith key list                              # … deny: claude-api · 300 requests/day
  • A request is counted once, when it comes in — before its body is read and before any adapter or alias leg is picked: one per request to /v1/chat/completions, /v1/messages, /v1/responses, /v1/embeddings or /v1/keysmith/usage, streamed or not, whatever it asks for. An alias that fails over to its second leg, a CLI asked again, a tool request that walks three legs: one request. A request that fails — upstream, or refused by the key's scope — is one too. Listing models or routes, and the status page, are not counted.
  • Over the cap, every face answers 429 (rate_limit_error) with a retry-after in seconds up to the next local midnight, when the count starts again at 0. The message names the cap and when it resets, never the key. The day's first refusal writes one usage row ("status": "limited") and a gateway log line; the refusals after it are counted on the status page and write nothing, so a client that keeps asking does not fill the disk.
  • The count survives a restart: at start it is rebuilt from today's rows in usage.jsonl (and the previous month's usage.jsonl.YYYY-MM when local midnight crosses a UTC month boundary; a request writes one row, stamped with its key's fingerprint). A request refused before its body was read — not JSON, no messages — costs nothing upstream and leaves no row, so it is not in the count a restart rebuilds.
  • Every key is counted, capped or not: keysmith usage lists each capped key's requests today beside its perDay cap, the status page (to an unscoped key) shows each key's requests today next to its cap, and a capped key sees its own count at the top of its page.
  • It fails closed like a scope: a perDay that is not a whole number ("300", -1) leaves the key reaching nothing, and one key listed twice with two different caps reaches nothing — otherwise an uncapped copy above a capped entry would quietly lift the cap. perDay: 0 refuses every request. Like every key change, a cap takes effect when the gateway restarts.

Recipe: an agent key that cannot reach claude-api

Say claude-api is an Anthropic HTTP adapter that spends a credit you use on purpose. An agent that gets a key of its own must not be able to spend it — not by naming it, and not through an alias that has, or later gains, a claude-api leg.

A scope binds only an agent that cannot read keysmith's config. The config is 0600 and its owner's; an agent that runs as the same OS user, with a shell, reads the unscoped key out of it the way the scripts above do (KEY=$(jq …)) and reaches claude-api with that. Run the agent as another OS user, in a sandbox, or in CI given its own key and nothing else — the --out file, or a secret holding it — and keep every unscoped key where the agent cannot read it.

keysmith key add ada --deny claude-api --out ~/.config/ada/keysmith.key
keysmith key who-can claude-api                          # ada's fingerprint is under "not reachable by"
launchctl kickstart -k gui/$UID/dev.keysmith.gateway     # or: keysmith stop && keysmith start

The agent reads its key from that file. Asked for claude-api/… it gets a 403 that names claude-api; asked for an alias whose first leg is claude-api, it is answered by the next leg, and its usage row says "skipped": ["claude-api/…"]; /v1/models does not list claude-api for it. For an agent that should reach only routes you name, use an allow-list instead, where an adapter added later stays out until you add it to the list:

keysmith key add ada --allow agy,alias:argon --out ~/.config/ada/keysmith.key

Batch jobs: work that can wait, at half the price

Off unless the config says "batch": { "enabled": true }; a gateway that is already running is not touched by any of this (it is a CLI command, nothing is served).

keysmith batch submit jobs.jsonl --adapter anthropic --name eval-1 --cap-usd 5 [--key fp:<8 hex>|<label>] [--cache]
keysmith batch status [eval-1]      # asks the upstream; a job is found again on disk after a restart
keysmith batch results eval-1       # writes jobs.results.jsonl, one line per request, same custom_id
keysmith batch cancel eval-1
  • Input: one JSON object per line, {"custom_id": "r1", "params": {"model": "...", "max_tokens": 1000, "messages": [...]}} (the Messages request, as the Message Batches API takes it). At most 100,000 requests or 256 MB.
  • Only an adapter on the anthropic wire takes a batch; any other is refused with a message. Gemini batches are not built.
  • Before anything is sent, keysmith estimates the most the batch can cost (every input token at the batch rate, every request answering with its full max_tokens, characters / 3.5 as tokens, rounded up) and refuses when it is above --cap-usd. A model with no entry in pricing is refused too: a cap cannot be checked without a price.
  • --key applies that key's allow/deny list and daily cap (perDay) to the batch, as a live request would. Without --key the owner of the config submits, unscoped.
  • A job name sends once: the job file under the data dir (batch/<name>.json) is created before the request goes out, so a second submit of the name sends nothing.
  • Cost: every result is billed at the entry's batchFactor (0.5 unless set) of the live price (a 1-hour cache write at the entry's cacheWrite1h, 2x the base input rate without one); usage.jsonl gets one row per request with batch: true, and batch results prints the real total beside the estimate. Requests that errored, expired or were canceled are not billed and get a zero row. Whether promotional credit pays for batches is not in Anthropic's documentation: the first small job shows it on the Console.
  • --cache puts one 1-hour cache_control mark on the system prompt when it is long enough to be cached (512 tokens for the 5.x models, up to 4,096 for others) and nothing carries a mark yet. Cache hits inside a batch are best-effort.
  • Anthropic keeps batch data for 29 days and zero data retention does not apply: send nothing secret or personal.

Example, the eval harness reference run (500 requests, Sonnet 5.5, capped at 3 USD):

keysmith batch submit eval/reference.jsonl --adapter anthropic --name eval-ref-1 --cap-usd 3 --cache
keysmith batch status eval-ref-1          # repeat until ended (most batches take under an hour)
keysmith batch results eval-ref-1
keysmith usage --by tag                   # batch/eval-ref-1 carries the real cost

Usage audit, pricing and spend caps

Every request writes one JSON line to usage.jsonl (0600 in a 0700 directory; every string redacted before encoding, and never a key, a prompt, an answer, a header or a request URL). Alongside ts, model, status, ms, usage (input — every input token the upstream charged, cache reads and writes included, on HTTP and CLI rows alike — with output, cacheRead and cacheWrite beside it), stream, client, error, key ("fp:…") and scope, each line records:

  • label — the gateway key's label from auth.keys, beside its fingerprint (key).
  • adapter, kind ("http" or "cli") and, for an HTTP adapter, host — the upstream hostname[:port] alone, with no path and no query.
  • account — which credential the adapter spent, named and never valued: an explicit account on the adapter config, else for {exec:security find-generic-password … -s NAME …} the keychain service NAME; for {env:NAME} the variable name NAME; for {file:PATH} path.basename(PATH); for any other {…} reference "exec" (with no text from it); and null for an unreferenced literal key or no key (never read from a CLI's stdout).
  • face — "chat", "messages", "responses" or "embeddings" (/v1/chat/completions, /v1/messages, /v1/responses — including the UHP server and relay — and /v1/embeddings).
  • bytesIn / bytesOut — the request and response body sizes in bytes.
  • upstreamId — the provider's request id when it returns one (such as Anthropic's request-id, OpenAI's x-request-id, or a UHP upstream's resp_… response id), to reconcile a line with the provider's console.
  • tag — the client's x-keysmith-tag request header (e.g. ao-review), kept when it is 1–40 characters of letters, digits, -, _ and ., dropped otherwise, and absent when not sent.
  • cost — {usd, basis} (pricing derives uncached input as input - cacheRead - cacheWrite at the input rate and prices cacheRead and cacheWrite at their own rates, uniformly across every adapter and parser):
    • "metered" for a per-token HTTP adapter matched by pricing (harnessrouter included), computed from input - cacheRead - cacheWrite, output, cacheRead and cacheWrite tokens;
    • "subscription" for a CLI adapter or a subscription-backed HTTP profile (traycer, usd: 0), with listUsd holding what those tokens would cost at the list rate pricing names for that model, when it names one;
    • "unpriced" with usd: null and reason when the row's token counts are unknown (usage: null with usageReason), or usd: 0 when no price entry matches (keysmith usage prints such a row as unpriced, with its tokens, not as $0.00).

One file per UTC calendar month. The active month is always written to ~/.local/share/keysmith/usage.jsonl, so tail -F ~/.local/share/keysmith/usage.jsonl keeps working across requests, rollovers and restarts. When the first line of a new UTC month is written, the closed month's usage.jsonl is atomically renamed to usage.jsonl.YYYY-MM and a fresh usage.jsonl starts the new month (and an entry dated in an older month goes straight to its usage.jsonl.YYYY-MM). Nothing is ever deleted.

Price table (pricing). Keyed by adapter/model glob in config.json, in USD per million tokens for input, output, cacheRead, cacheWrite (5-minute) and, optionally, cacheWrite1h (1-hour; 2x input when absent) and batchFactor (the Batch API's share of the price; 0.5 when absent). keysmith ships defaults for all 15 Claude models keysmith models lists, read from Anthropic's official pricing page, https://platform.claude.com/docs/en/about-claude/pricing, on 2026-11-17 (the batch discount is 50% on every model there). keysmith price list prints the table with that page and date beside each entry.

Glob input output cacheRead cacheWrite 5m cacheWrite1h
*/claude-fable-5-2* $8 $40 $0.2 $10 $16
*/claude-fable-5-1* $10 $50 $0.25 $12.5 $20
*/claude-fable-5* $10 $50 $1 $12.5 $20
*/claude-opus-5-5* $4 $20 $0.2 $5 $8
*/claude-opus-5*, 4-8, 4-7, 4-6, 4-5 $5 $25 $0.5 $6.25 $10
*/claude-sonnet-5-5* $2 $10 $0.1 $2.5 $4
*/claude-sonnet-5* $2 $10 $0.2 $2.5 $4
*/claude-sonnet-4-6*, 4-5 $3 $15 $0.3 $3.75 $6
*/claude-haiku-5-5* $0.1 $0.5 $0.01 $0.125 $0.2
*/claude-haiku-4-5* $1 $5 $0.1 $1.25 $2

claude-haiku-5-5 is priced by prompt length on that page: the rates above are for prompts up to 100K tokens; a request over 100K pays 5x on input and output, which one rate cannot tell apart. A model with no entry is shown as unpriced in keysmith usage (tokens counted, no dollars, not a $0.00) and keysmith doctor names it. Add an entry with keysmith price set:

keysmith price set '*/claude-haiku-4-5*' --input 1 --output 5 --cache-read 0.1 --cache-write-5m 1.25 [--cache-write-1h 2] [--batch-factor 0.5] [--dry-run]

It validates every number (0 or more, a plain decimal), copies the config to a dated backup, writes through a temp file and a rename, mode 0600. The running gateway keeps its table until it restarts.

A config entry overrides any default that matches the same target; a price never comes from the client:

"pricing": {
  "claude-api/claude-sonnet-5-5*": { "input": 2, "output": 10, "cacheRead": 0.1, "cacheWrite": 2.5 },
  "openai/gpt-5*":                 { "input": 1.25, "output": 10, "cacheRead": 0.125, "cacheWrite": 0 }
}

Statistics (keysmith usage and GET /v1/keysmith/usage). Reads every monthly log file in full — not the last 5,000 lines — and groups by one or two dimensions (key, label, adapter, model, account, tag, day, client), filtered by inclusive --since and --until bounds (an ISO date/timestamp such as 2026-10-01 — where --until YYYY-MM-DD includes that entire UTC day through 23:59:59.999Z — or a relative duration such as 7d, 24h), in table, csv or json format. Monthly log files, --by day and limits.spend use UTC calendar days and months, while per-key perDay request caps reset at local midnight:

keysmith usage                                             # whole log, grouped by model
keysmith usage --by adapter,model --since 7d               # two dimensions, last 7 days
keysmith usage --by label,tag --since 2026-10-01 --until 2026-10-31 --format csv
keysmith usage --by account --format json

Each group and the grand total report: requests, failures, refused, unknownUsage (rows whose token counts were unknown, counted apart so no token or USD total treats an unknown count as zero — a bucket with only unknown-usage rows reports null for token counts and USD), token counts (input — every input token charged, cache reads and writes included, on HTTP and CLI rows alike so keysmith usage totals add like with like — output, cacheRead, cacheWrite), meteredUsd, listUsd (kept apart from metered spend), and p50Ms / p95Ms latency. Percentiles are computed from a fixed log-spaced latency histogram (exact 1 ms resolution up to 100 ms, then 50 log-spaced buckets per decade up to 1,000,000 ms, ~4.7% bucket width, merged by adding bucket counts across cells and read identically by the endpoint, the status page and keysmith usage so their numbers agree within one bucket). GET /v1/keysmith/usage?by=adapter,model&since=7d takes the same parameters and answers JSON from bounded in-memory aggregates under the key's scope: windows of 48 hours or less (?hours=N for N <= 48, and the status page's 24h figures) answer from hourly cells rounded to the UTC hour (granularity: "hour", roundedToWholeHours: true), and wider windows answer from daily cells rounded to whole UTC days (granularity: "day", roundedToWholeDays: true, with since naming the earliest kept day when older days have aged out). ?tail=N returns recent rows from an in-memory ring bounded by both count (at most 2,000 rows, TAIL_RING_MAX) and byte size (at most 2 MiB, TAIL_RING_MAX_BYTES; tail above 2,000 is refused with HTTP 400). On a verbatim OpenAI-wire relay, keysmith reads usage from a non-streamed body or asks the upstream for stream_options: {"include_usage": true} on a stream (stripping any usage member, null included, that the client did not request and dropping a chunk only when nothing else is left before forwarding); an HTTP adapter entry may set "streamUsage": false for an upstream that refuses stream_options, in which case a streamed relay records usage: null with a usageReason.

Spend caps (limits.spend). Caps monthly metered USD (per UTC calendar month) by adapter id or by credential account (two adapters that reference the same credential share that account's cap):

"limits": {
  "spend": {
    "claude-api": 25.00,
    "anthropic-prod": 50.00
  }
}

A cap may instead be one total over a window of UTC days — a promotional grant that expires, whose spend would fall on paid credit after it: { "usd": 25, "since": "2026-11-12", "until": "2026-12-09" } counts the metered spend of every row from since 00:00Z up to until 00:00Z (until is the first day it no longer covers), across the month turn, with what requests in flight hold. It refuses once that total reaches the cap, and outside its window: before since it has not opened (retry-after until it does), from until on it has closed — it never resets, so its retry-after is an hour and a config change is what lifts it. A window that is not two UTC days with until after since refuses every request instead of capping nothing. keysmith usage and the status page show the window beside the spend (total 2026-11-12 … 2026-12-09, until excluded).

Each cap's month-to-date metered spend is kept in memory — seeded lazily once from the current UTC month's file on first use and again when the UTC month turns, and incremented as each new row is written, with adaptersSeen bounded to 200 characters per name (cut with …[truncated], as in the aggregates) and at most 1,000 distinct adapter names (MAX_ADAPTERS_SEEN) — so checking a cap reads no file on the request path. Once the recorded spend has reached or passed the cap, keysmith refuses the request with HTTP 429 (rate_limit_error) and a retry-after header in seconds until the UTC month turns, naming the cap, the current spend (for an unscoped key; a scoped key sees the cap and reset time without totals across keys), and when the month resets (YYYY-MM-01T00:00:00Z), in each face's error shape (/v1/chat/completions, /v1/messages, /v1/responses), and records the refusal as a line of its own; the gateway's log gets one ! spend cap hit — … line with the spend when a cap starts refusing, and another when what it says changes (another month, its window closed, another cap), not one per refused request. A request already in flight when the cap is crossed finishes. An unreadable month file is logged and surfaced on the status page, keysmith doctor and keysmith status, and makes its caps fail closed; keysmith usage and the status page show each cap beside its current spend.

The Kiro credit guard. Kiro reports no token counts, so a spend cap never sees what a kiro leg spends. Every adapter that runs kiro-cli (kiro, kiro-emu, whatever its id) is guarded by the plan's own meter instead: keysmith runs kiro-cli chat --no-interactive --trust-tools= --agent <the adapter's agent> /usage (no tool trusted, the adapter's tool-less agent), reads Credits (X of Y covered in plan), and holds the adapter back while X/Y is at or over its creditGuardThreshold (a share of the plan, 0.9 by default, above 0 and at most 1.25; keysmith set kiro creditGuardThreshold 0.95, 1 to hold it back only once the plan is spent, 1.12 to let it run into Kiro's overage up to 112% of the plan; on any other entry the key is a load error). Held back, a route passes the leg by (skippedLegs in the row: credit_guard, the share of the plan and the threshold) and the next leg answers; a request that names it gets a 429 rate_limit_error that says why and names the plan's reset date, with a retry-after of the time to that reset but at most 300 s (a reset weeks away would stop a client that honours it for weeks, while the threshold may be raised or the plan topped up in the meantime); a virtual model whose classifier it is labels the request medium without asking it. The reading is cached for ten minutes, and /usage runs at most once per ten minutes per Kiro login (adapters with the same binary and environment share one plan and one reading) across processes: an attempt is written to credit-guard.json (beside the usage log) before it runs, and the file is read again before the next one is decided, so the gateway and keysmith doctor never both read the plan inside the ten minutes. serve reads the plan at start and keeps it fresh in the background, so no request — a failover leg least of all — waits for a reading; only the very first reading of a login nothing is known of is waited for (at most 10 s). A reading that does not exit in 30 s is stopped (SIGTERM, then SIGKILL) and counts as failed. The meter only climbs until the plan resets, so a reading at or over the threshold keeps the adapter held back when the readings after it fail (a timeout, a login prompt, a new wording) — until one succeeds or the plan resets; a failure with no reading of this period never holds anything back. Every failure is logged to the gateway's stderr, and doctor and keysmith status show it (the newest reading failed). doctor shows each guarded adapter's state and the last reading, counts a held-back leg as not carrying tools, and warns of an alias where a guarded leg comes before a metered HTTP leg no limits.spend cap covers (from the threshold on, that leg pays for the kiro traffic); status shows the reading the gateway last kept (it runs no kiro-cli), and /v1/keysmith/routes has it as credit_guards.

Catalogue limits

An optional catalogue file tells keysmith what each source allows, so it refuses locally (429 with retry-after) before the provider does. Nothing changes until catalogue is set in config.json ("catalogue": "~/catalogue.json"); the file is re-read when it changes, and an unreadable or invalid one is logged once and ignored.

{
  "version": 1,
  "sources": [
    {
      "id": "tokenrouter",
      "reach": { "keysmith": "tokenrouter" },
      "limits": { "requestsPerMinute": 20, "requestsPerDay": 200, "tokensPerMonth": 5000000 },
      "models": [{ "id": "some-model", "tier": "free" }]
    }
  ]
}

Only reach.keysmith (the adapter id), limits and models[].tier are read; unknown fields are ignored. Over a limit the request is refused with a 429 and a retry-after of the time until the minute, UTC day or UTC month window opens again, and nothing is sent upstream. After an upstream 429 the adapter cools down for that response's retry-after, or 60 s without one, and requests in that time get a local 429. Counters live in memory (the month's tokens are seeded from the usage file at start). A usage row gets source and tier when the catalogue knows the model; without a catalogue the rows are unchanged.

Recording external usage

Work done outside the gateway can be counted next to it, with no server running:

keysmith usage record --source qoder --model some-model --tag job/1 --id r1 \
  --requests 1 --credits 2 --input 1200 --output 300 --ms 8000 --accepted true
keysmith usage record --from ~/runs.jsonl     # one JSON object per line, same field names

Each call appends one row with face: "external" (the adapter column is the --source), so keysmith usage --by adapter counts it. With --id a second call with the same id writes nothing (already recorded); a different --accepted for that id is added as an amending row.

Free models: discover and freeOnly

Set "discovery": { "enabled": true } in config.json, then keysmith discover tokenrouter asks the adapter's GET <baseUrl>/models and writes the models whose input and output price are both 0 to <data>/discovered/tokenrouter.json. The price fields default to pricing.prompt and pricing.completion; change them per adapter with "discovery": { "tokenrouter": { "inputPricePath": "...", "outputPricePath": "..." } }. A pricingUrl (a price table read instead of /models) must be https: an http or unreadable address is refused with one line and no list is written. With discovery off the command refuses; a 401 or 403 prints renew key: <adapter>. keysmith set tokenrouter freeOnly true then refuses any model not on that list (400); the file is re-read when it changes, so a new discover takes effect without a restart.

Publishing it safely

keysmith serve --tunnel is the whole point for remote clients, and a tunnel is transport, not authentication — the key still gates every request. Two modes:

brew install cloudflared
cloudflared tunnel login
keysmith tunnel setup llm.example.com          # prints what it will do
keysmith tunnel setup llm.example.com --yes    # tunnel create + route dns + ingress YAML

That is a named tunnel: stable hostname, survives restarts, ingress file you can keep in a repo. Without it, keysmith falls back to a quick tunnel and says so — a trycloudflare.com hostname is random and dies with the process, which is how a "working endpoint" becomes three dead entries in someone's client config. Use named tunnels for anything you paste into a client you will not reopen. Details: docs/tunnel.md.

Keep host: 127.0.0.1. There are no rate limits here, and a CLI adapter is a process spawner: an unauthenticated public gateway is a denial-of-wallet machine.

On macOS, keysmith install-service writes two LaunchAgents (~/Library/LaunchAgents/dev.keysmith.{gateway,tunnel}.plist) so the gateway — and the named tunnel, when configured — come back at login without a terminal. It embeds absolute binary paths and a PATH that can find your CLIs, written so they outlive the shell that ran it and follow the upgrades you make: an fnm multishell path (which dies with that shell) and a path in your default fnm version go through <fnm>/aliases/default/…, another fnm version through its own directory, a Homebrew keg (…/Cellar/node/26.12.0/…, gone after brew upgrade) through …/opt/<formula>/…. Re-running it replaces the loaded agents: it waits until launchd has let go of the old one before loading the new, and retries a load launchd refuses ("Bootstrap failed: 5") for up to 30 s, then says which agent is down and the launchctl bootstrap … that loads it. It stops the foreground keysmith start / tunnel run processes it is replacing — never launchd's own gateway, which writes the same pidfile — and lets launchd's throttled retry rebind the port. keysmith install-service --dry-run prints the agents it would write and touches nothing. keysmith uninstall-service reverses it. Quick tunnels are not persisted: a random hostname that changes every start earns nothing from a service.

The gateway agent is ProcessType: Interactive. Without it launchd runs the gateway, and every CLI the gateway spawns, at utility priority with throttled I/O; on a busy machine that tripled the wait for an agent's first token (9–30 s against 4–5 s, same code). An agent installed by an older keysmith keeps its old plist — run keysmith install-service again to rewrite it.

Changing an attached adapter

keysmith add copies a profile into your config; from then on the entry is yours, and these change it without opening the file that holds the gateway key:

Command What it does
keysmith set <adapter> its fields: = as its built-in profile has it, ≠ changed (the profile's value after it), + the profile has it and the entry does not, · the entry's own; then the common fields it does not set. A key is shown only as a reference ({env:…}), env and headers by name
keysmith set <adapter> <field> <value> one field; the value is JSON when it parses. --unset removes it
keysmith upgrade [<adapter>…] what its built-in profile gained since the entry was copied — a dry run. --apply writes it
keysmith enable | disable <adapter> set <adapter> disabled false|true
keysmith vision <adapter> on|off set <adapter> vision true|false: images on or off (off takes image out of media too), a CLI's visionArgs filled in from its profile when the entry lacks them
keysmith tools <adapter> off|emulate|mcp|auto set <adapter> toolMode …, the tool engine's templates filled in the same way

Each goes through set's checks: a value the gateway would not load is refused before it replaces a working entry, and an unsafeTools adapter is served, or changed in what it runs, only with --allow-unsafe-tools. A running gateway picks a change up when it restarts.

Fields people set often:

keysmith set claude models '["sonnet","opus"]'   # what /v1/models lists for it
keysmith set claude timeoutMs 600000             # a run may take ten minutes
keysmith set claude maxImages 5                  # images per request (20)
keysmith set claude maxImageBytes 2097152        # the largest image, decoded (5 MB)
keysmith set ollama media image                  # a local vision model: images go up as image_url
keysmith set google maxFileBytes 10485760        # the largest PDF, audio or video file, decoded (20 MB)
keysmith set agy maxConcurrent 4                 # processes at once
keysmith set codex explicitOnly true             # answers codex/… by name only: no alias, no probe
keysmith set copilot priority 10                 # first in the flat listing
keysmith set google modelParams '{"gemini-4-argon":{"reasoning_effort":"high"}}'

keysmith upgrade. A profile gains things — media on claude, openai, google…, a tool engine's templates on agy, opencode, codex and qoder — and an entry copied before that does not have them. upgrade compares each entry with the profile it was made from (a CLI by its binary and parser, an HTTP adapter by its baseUrl and wire) and says, per field:

  • + the profile has it and the entry does not: added;
  • ~ provenance and note: the profile's current text;
  • = the entry has another value: yours, kept. --take <field,…> replaces it with the profile's (← field … was: …). A file of workspaceFiles the entry lacks is added, one it has is kept the same way.

Nothing is written without --apply, and with no adapter named it looks at every entry that has a profile. Like a re-add it never loosens a guard (explicitOnly, unsafeTools, disabled), and a CLI marked unsafeTools gets no tool engine. Every entry is checked as set checks one before anything is written; one that fails stops them all. Read the dry run before --apply: an added toolMode: "auto" means that adapter starts answering requests that offer tools.

Built-in profiles

Profile Kind Status
cmd cli verified live against Command Code 1.66.0 — unsafeTools: a -p run approves its own tool calls, so it ships disabled, see above
opencode cli verified live against opencode 1.18.27; tool-less agent checked against a stub endpoint (no --auto); its free opencode/* models refuse the tool-less run (403); answers tool requests (toolMode: "auto": the MCP bridge, EMULATE where it cannot — both live round trips on opencode 1.19.3)
qoder cli verified with -p; its -o json/stream-json modes fail inside a nested agent session; tool-less flags parsed by 1.1.59; answers tool requests (toolMode: "auto": the MCP bridge with -o stream-json, EMULATE where it cannot — both live round trips on 1.1.59)
claude cli tool-less flags and stream-json shape checked against Claude Code 2.1.261; takes images and PDFs (media: stream-json on stdin; a scanned page transcribed live on 2.1.303 through both faces, a PDF document block checked against a stub); explicit-only as shipped; answers tool requests (toolMode: "auto": the MCP bridge, EMULATE where it cannot — the bridge's round trips live on 2.1.303); its models and their effort levels from Claude Code's initialize listing
agy cli verified live against Antigravity CLI 1.3.3 — your Google login, no key; runs as a tool-less text agent (~600-token prompt instead of ~20k), see docs/adapters.md; answers tool requests too (toolMode: "auto": the MCP bridge, EMULATE where the bridge cannot — see docs/adapters.md)
kiro cli Kiro CLI 2.27.1 — tool-less agent, stream-json, model list as JSON; the first live run was refused for quota before any text, see docs/adapters.md; tool requests pass it by (toolMode: "off"): its EMULATE argv is checked against a stub only
codex cli argv run against a stub Responses endpoint with codex 0.163.0 (read-only, no shell, no web search); gpt-6-* keep sub-agent tools; answers tool requests (toolMode: "auto": the MCP bridge with exec --json, EMULATE where it cannot — both live round trips on gpt-5.6-luna)
warp cli Warp's oz agent CLI, ndjson verified live — unsafeTools: ships disabled, never an alias leg, see above
gemini cli documented argv shape, not run against a live install — unsafeTools until a tool-less argv is checked: ships disabled
openai, anthropic, openrouter, groq, deepseek, together http standard endpoints; openai takes images, PDFs and audio, anthropic images and PDFs (media, from their API references)
google http verified live against Gemini's OpenAI-compatible endpoint: tools, streaming, thought signatures — see above; takes images (read live on gemini-3.5-flash) and audio; refuses a PDF file part and video_url
cloudflare http Workers AI's OpenAI-compatible endpoint; the account id sits in the URL (--account-id), key CLOUDFLARE_API_TOKEN; open it with keysmith source enable cloudflare
tokenrouter, mistral http OpenAI-wire endpoints (https://api.tokenrouter.com/v1, https://api.mistral.ai/v1; keys TOKENROUTER_API_KEY, MISTRAL_API_KEY), checked against a stub only; tokenrouter pairs with discover and freeOnly, see Free models
ollama, lmstudio, llamacpp, vllm http local servers, no key
copilot http verified live against api.githubcopilot.com with an OAuth device token; takes images with copilot-vision-request: true (not checked live)
traycer http verified live against https://server.traycer.ai (wire: "traycer"): discovers 32 models across anthropic, openai, xai, meta and openrouter from GET /api/traycer/models, routes each to its native /inference/… endpoint with x-traycer-account-context: PERSONAL, answers tool requests via EMULATE, takes images and PDFs; explicit-only
harnessrouter http UHP (2026-10-19) relay to HarnessRouter CE (http://127.0.0.1:8000/api/harness/v1) or Cloud (https://api.harnessrouter.ai/v1); native /v1/responses tools with automatic EMULATE fallback
traycer-cli, droid, devin, copilot-cli, cursor, amp, reasonix cli Traycer & packaged CLI harness profiles (traycer --json agent send --expect-reply, Factory droid exec, devin -p, GitHub copilot -p, cursor-agent -p, Sourcegraph amp -x, reasonix -p); parsed via harness-json; unsafeTools (ship disabled)

keysmith source enable <profile> --models-url <url> lists models from that address instead of <baseUrl>/models; the key is sent only to an https address with the baseUrl's own origin (scheme, host, port), to nothing else.

keysmith adapters lists them; keysmith add <profile> copies one into your config where every field stays yours. Adding an agent nobody has heard of is a config edit:

keysmith add custom --as myagent --bin myagent --args '["-p","{prompt}"]' --parser raw

The argv template supports {model}, {prompt}, {system}, {session}, {maxTokens} and {noSession}; a nested array is a group that disappears when its placeholder is empty (so -m can never swallow your prompt). Full field reference and the parser contract: docs/adapters.md.

Client recipes

Warp, Claude Code, opencode, Codex, Qoder, openai Python — copy-paste config in docs/clients.md.

MCP server

keysmith ships a local stdio JSON-RPC 2.0 MCP server for inspecting and managing configured sources on this Mac only (no HTTP listener, no remote access):

keysmith mcp --register            # register "keysmith" in installed local MCP clients (--dry-run previews)
keysmith mcp --setup               # print the manual mcpServers JSON snippet (writes nothing)
keysmith mcp                       # run the stdio MCP server (invoked by MCP clients)

--register writes to claude-code, claude-desktop, cursor, gemini-cli, opencode, and codex-cli: it creates a client's config file when only that client's folder exists, writes a mode-0600 dated backup before modifying each existing file, resolves the Node binary via stablePath, updates atomically, and is idempotent. --setup writes nothing and only prints the manual JSON snippet (command and args) for adding the server by hand.

  • Conventions: tools are named keysmith_<verb>, return structuredContent, and carry readOnlyHint/destructiveHint annotations. Every writing tool (and keysmith_reload) refuses unless confirm: true is passed; config writes take a dated mode-0600 backup first and write through a mode-0600 temp file and rename.
  • Read tools: keysmith_status (launchd state, PID, port, /healthz, enabled source count), keysmith_sources (non-secret metadata, key reference kind, Keychain yes/no), keysmith_source_models (models, enforced, approved, status: "not_enforced" and unenforced note on CLI sources, discovered free diff), keysmith_test (single-source check, latency + status, no body), keysmith_usage (per-source requests/tokens/spend and limits.spend headroom), keysmith_approved (approved HTTP source -> models, unenforcedCliSources / note marking CLI sources as unenforced, and pending free-flag changes).
  • Write & reload tools (all require confirm: true): keysmith_source_add (validates profile name and takes a built-in profile plus Keychain service/account names, never a key value), keysmith_source_enable, keysmith_source_disable, keysmith_source_set_models (HTTP sources only; refuses CLI sources even with confirm: true), keysmith_model_approve, keysmith_model_revoke (HTTP sources only; refuses CLI sources even with confirm: true), and keysmith_reload (validates config via loadConfig({ mint: false }), refuses when requests are in flight unless force: true, restarts dev.keysmith.gateway via launchd, waits for /healthz; supports KEYSMITH_MCP_LAUNCHCTL, KEYSMITH_MCP_GATEWAY_URL, and KEYSMITH_MCP_PLIST startup test hooks).
  • Never returned: key values, secret reference interiors (Keychain service/account or file/json/dotenv paths included), auth.keys[].key, Cloudflare account id, workspaceFiles content, or request/response bodies — all responses and errors pass through redact.js and src/mcp.js scrubbing.
  • Non-goals: no web UI, no remote access, no key generation, no provider signup, no new admin HTTP API, and no aliases, virtualModels, tunnel, or auth.keys management.

Full tool schemas, registration targets, and redaction details: docs/mcp.md.

Development

npm test          # 434 tests: parsers, routing, key scopes, tool routing and EMULATE, HTTP suites against stub CLIs and stub upstreams, and no key reaching a log
node src/cli.js doctor --probe-models   # the truth about which models answer (spends quota)

The integration suite spawns a stub script that prints Command-Code-shaped NDJSON, so spawning, parsing, SSE framing, session mapping and failover are covered without touching a provider or spending a token.

Config: ~/.config/keysmith/config.json ($KEYSMITH_CONFIG). State: ~/.local/share/keysmith/ ($KEYSMITH_DATA, 0700) — pid, logs, usage.jsonl, all 0600; see what is logged.

License

MIT — see LICENSE.

About

Forge an API key out of any coding CLI. Serve Command Code, opencode, Claude Code, Qoder and Copilot behind one OpenAI-compatible /v1 endpoint — with failover, streaming, sessions and Cloudflare named tunnels. Zero dependencies.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages