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"}]}'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.
| 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.
Keysmith natively speaks the Universal Harness Protocol (UHP 2026-10-19) in both directions:
- As a UHP Server: Any UHP client or SDK can discover capabilities at
GET /.well-known/uhp(orGET /v1/uhp), inspect attached harnesses atGET /v1/harnesses(filtered by the caller key's scope), route to a specific harness viametadata.harness_idorx-harness-id, chain stateful multi-turn sessions onPOST /v1/responseswithprevious_response_id(GET /v1/responses/:id), enforceIdempotency-Keydeduplication (409 idempotency_conflicton payload mismatch), and propagate W3Ctraceparent/tracestateheaders. - As a UHP Upstream Relay (
harnessrouterprofile): 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 withmetadata.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 traycerKeysmith 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").
<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": {
"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 --deleteA 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.
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.
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.
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,thinkingand itsanthropic-betafeatures (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
toolModeanswers 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 astool_calls(tool_useblocks on/v1/messages,function_callitems 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 (
toolModeabsent oroff:kiroand the profiles markedunsafeTools) 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 underauto.timeoutMscounts 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'sMCP_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) andbridge.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.maxSessionsis 2 per adapter,limits.bridge.maxSessions2 in all, andlimits.bridge.maxSessionsPerKey1 — a key that opens a session over its share gives up its oldest waiting one. With no room,autois EMULATE andmcpa 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'sinvalid(its answer to a call of a tool it does not have), qoder'smcp_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 saysSECURITY … foreign tooland the usage rowfailure: "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 anytool_useblock 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 whosemaxPromptCharsis 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>.mdin 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 nextkeysmith serveremoves 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
mcpServersas a list, itseagerkey, itsmcp_<server>_<tool>names, theserver/discoverit asks first, its schema cache; opencode'sOPENCODE_CONFIGmerge and inline agents, codex's per-serverdefault_tools_approval_mode, qoder'sdisableAllHooks, Claude Code's--setting-sources "",autoMemoryEnabled,CLAUDE_CODE_DISABLE_AUTO_MEMORY,MCP_TOOL_TIMEOUT,ENABLE_TOOL_SEARCHand a tool'santhropic/maxResultSizeChars. A CLI that changes one fails the readiness gate, andautoanswers 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
usageis its own share of the run, what the upstream charged — the harness's system prompt and the cache included (inputwithcached_tokens; on/v1/messagesthe uncachedinput_tokenswithcache_read_input_tokensandcache_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 thereason, 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.
keysmith add google # reads {env:GOOGLE_API_KEY}
keysmith add google --key '{dotenv:~/project/.env#GOOGLE_API_KEY}' # or where the key already livesGoogle'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.
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.highis Argon's maximum — agy refuses--effort maxand--effort xhighfor it. Through the tool-lesskeysmith-textagent,agy/gemini-4-argon-highanswered "Reply with exactly: OK" in 3.2 s. A request with tools is answered too (toolMode: "auto"in the profile): the tool-lesskeysmith-toolsagent writes the calls, EMULATE hands them over (see Tool calls). -
google (the API) lists
gemini-4-argon, takes tools, and takes OpenAI'sreasoning_effortfield. keysmith builds the body of a plain completion itself, so the effort goes in the adapter'smodelParams, 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;
modelParamsfills 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'sthinking_config(underextra_body.googleorgoogle). Then no effort field frommodelParamsis added at all: Google's documentation saysreasoning_effortand a thinking budget cannot be used together, and that 400 would count as the leg refusing the tools.highhere 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-argonA 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.
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.
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 aliasrefuses it unless the alias opts in with--allow-explicit-only; a hand-edited leg without opt-in is skipped and named indoctor,/v1/modelsand the routes endpoint), never probed bydoctor --probe-models. For an adapter that spends something you keep for yourself; theclaudeprofile ships it, andkeysmith add <profile> --explicit-onlysets it on any other.unsafeTools: true— keysmith could not take the CLI's tools away. EverythingexplicitOnlydoes, and the profile shipsdisabled: 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; onlynote,models,defaultModel,priority,timeoutMs,maxConcurrent,maxPromptCharsandexplicitOnlychange without it, and turning it off never needs it. Its profile also setsstopAtToolCall: "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).
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.
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 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 scopeAn 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 transcriptA 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.
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
allowlist means everything that is not denied. Anallowlist means only what it names, aliases included: an allow-listed key names each alias it may use (alias:argon). denywins overallow.- 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
modelMaprewrites it, as sent upstream. A bare adapter id (claude-api) is checked with itsdefaultModel; 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'smodels/) answersgoogle/models/gemini-4-argonasgemini-4-argon, sogoogle/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/usageand 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 whosekeysholds 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 — anddoctor,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 isclaude-api— is not an error (it may name an adapter you add later), but it keeps nothing out, soserve,doctor,key listand the status page (to an unscoped key) warn about it, with a hint when a configured name differs only in case or_/-. - With
auth.enabledfalse no key is asked for, so no scope applies:key add,key scopeandkey listsay 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/modelkey 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 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/embeddingsor/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 aretry-afterin 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'susage.jsonl.YYYY-MMwhen 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 usagelists each capped key's requests today beside itsperDaycap, 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
perDaythat 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: 0refuses every request. Like every key change, a cap takes effect when the gateway restarts.
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 startThe 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.keyOff 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
anthropicwire 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 inpricingis refused too: a cap cannot be checked without a price. --keyapplies that key's allow/deny list and daily cap (perDay) to the batch, as a live request would. Without--keythe 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 secondsubmitof 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'scacheWrite1h, 2x the base input rate without one);usage.jsonlgets one row per request withbatch: true, andbatch resultsprints 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. --cacheputs one 1-hourcache_controlmark 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
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 fromauth.keys, beside its fingerprint (key).adapter,kind("http"or"cli") and, for an HTTP adapter,host— the upstreamhostname[:port]alone, with no path and no query.account— which credential the adapter spent, named and never valued: an explicitaccounton the adapter config, else for{exec:security find-generic-password … -s NAME …}the keychain serviceNAME; for{env:NAME}the variable nameNAME; for{file:PATH}path.basename(PATH); for any other{…}reference"exec"(with no text from it); andnullfor 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'srequest-id, OpenAI'sx-request-id, or a UHP upstream'sresp_…response id), to reconcile a line with the provider's console.tag— the client'sx-keysmith-tagrequest 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 asinput - cacheRead - cacheWriteat theinputrate and pricescacheReadandcacheWriteat their own rates, uniformly across every adapter and parser):"metered"for a per-token HTTP adapter matched bypricing(harnessrouterincluded), computed frominput - cacheRead - cacheWrite,output,cacheReadandcacheWritetokens;"subscription"for a CLI adapter or a subscription-backed HTTP profile (traycer,usd: 0), withlistUsdholding what those tokens would cost at the list ratepricingnames for that model, when it names one;"unpriced"withusd: nullandreasonwhen the row's token counts are unknown (usage: nullwithusageReason), orusd: 0when no price entry matches (keysmith usageprints such a row asunpriced, 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 jsonEach 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.
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.
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 namesEach 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.
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.
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 YAMLThat 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.
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;~provenanceandnote: the profile's current text;=the entry has another value: yours, kept.--take <field,…>replaces it with the profile's (← field … was: …). A file ofworkspaceFilesthe 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.
| 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 rawThe 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.
Warp, Claude Code, opencode, Codex, Qoder, openai Python — copy-paste config in
docs/clients.md.
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>, returnstructuredContent, and carryreadOnlyHint/destructiveHintannotations. Every writing tool (andkeysmith_reload) refuses unlessconfirm: trueis passed; config writes take a dated mode-0600backup first and write through a mode-0600temp file andrename. - Read tools:
keysmith_status(launchd state, PID, port,/healthz, enabled source count),keysmith_sources(non-secret metadata, key reference kind, Keychainyes/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 andlimits.spendheadroom),keysmith_approved(approved HTTPsource -> models,unenforcedCliSources/notemarking 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 withconfirm: true),keysmith_model_approve,keysmith_model_revoke(HTTP sources only; refuses CLI sources even withconfirm: true), andkeysmith_reload(validates config vialoadConfig({ mint: false }), refuses when requests are in flight unlessforce: true, restartsdev.keysmith.gatewayvialaunchd, waits for/healthz; supportsKEYSMITH_MCP_LAUNCHCTL,KEYSMITH_MCP_GATEWAY_URL, andKEYSMITH_MCP_PLISTstartup test hooks). - Never returned: key values, secret reference interiors (Keychain service/account or
file/json/dotenv paths included),
auth.keys[].key, Cloudflare account id,workspaceFilescontent, or request/response bodies — all responses and errors pass throughredact.jsandsrc/mcp.jsscrubbing. - Non-goals: no web UI, no remote access, no key generation, no provider signup, no
new admin HTTP API, and no
aliases,virtualModels,tunnel, orauth.keysmanagement.
Full tool schemas, registration targets, and redaction details: docs/mcp.md.
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.
MIT — see LICENSE.