stack/docs/plans/2026-10-24_model-proxy-rows.md

Briefs: the model proxy build rows P1 to P5

Written 2026-10-24 by Sage for Mos's mos-1600, which approved the Vikunja 237 design (docs/plans/2026-10-24_stack-model-proxy.md, 9a50f082f) with changes. Read the design first. These briefs cite its decision numbers (D1 to D20) and carry Mos's changes, which win over the design where they differ. Line numbers are at origin/refactor 06f507dbc. Check them before you edit.

Every row is a Codex gpt-6.1-sol build on its own new thread and worktree off refactor (mos-1542). A separate Codex thread gives the first review and a Claude reviewer gives the second, because every row touches credentials or the Console's security boundary. Sage runs the landing gate.

Rules for every row

• Secrets and the live proxy. No agent reads <configDir>/secrets/proxy-management.key or anything under a real instance's <dataRoot>/proxy/ (config.yaml, auth/, logs/). That covers Mos, Sage, every builder and every reviewer (mos-1600 ruling 2). Tests and acceptance runs use their own made-up config, key and data root in a fresh temp root. The host proxy on 127.0.0.1:8317, its binary under ~/.local/opt/EasyCLIProxyAPI and its config are never started, stopped, read, copied or called. No real upstream credential and no request off the machine except P1's pinned fetch.
• No live change. No row edits a live instance config, starts mosaic-proxy, restarts a bus or Console, or changes claude-session.env. Cutover is P7, with Jason present.
• Refusals. Every new fail-closed refusal gets its own test, by its code (mos-1590). A red in an old test goes to Sage before any rerun, including a rerun you expect to be timing (mos-1592).
• Runs. TMPDIR and nice as BRIEF-TEMPLATE's Gate says. All test runs are slot work: ask Sage for CLEAR. Design notes and receipts go in agents/<seat>/work/queue-<row>/BUILD.md. Report to Sage's thread.

Order

P1 and P4 start now. P4 builds against the config contract in P1 item 3 and rebases on P1 before its gate, and P4 lands after P1. P2 starts when P1 lands. P3 and P5 start when P2 lands and run in parallel. P6 waits for row 157 to resume. P7 waits for P1 to P4 and for Jason.

Brief: P1 the model-proxy package, pinned fetch, proxy init and the proxy unit

Why. D1 to D6 and D11's sentinel need a pinned binary, a config the stack writes once, a management client that only the bus uses, and a human-only way to set the management key. Mos dropped J1 and merged J2 into J3: a row does the fetch, and mosaic proxy init writes the proxy settings, so Jason never edits a file by hand (mos-1600 rulings 1 and 7, Q126).

What ships.

1. packages/model-proxy/, a new package with its own tests/, so the gate's package loop picks it up.
2. PIN and the fetch. packages/model-proxy/PIN names the CLIProxyAPI version, the linux-amd64 release asset, the control panel asset (router-for-me/Cli-Proxy-API-Management-Center) and the sha256 of each.
   • Pin the newest release that the acceptance run below passes on. Record in BUILD.md which release that is, and whether it is 8.0.27, the version row 96 tested.
   • Record each hash from the release as downloaded. The reviewer downloads the same assets and measures them independently.
   • A fetch step (mosaic proxy fetch) downloads the pinned assets from the release URLs only and verifies each against PIN. It installs them under <dataRoot>/opt/cliproxyapi/<version>/, outside <dataRoot>/proxy/. A hash mismatch, a redirect off GitHub's release hosts, or an existing target with different content refuses, and a refusal leaves nothing installed.
   • The gate's tests use a local fake file server. Only the builder's and the reviewer's own measurement runs touch GitHub.
3. The proxy settings, written by mosaic proxy init.
   • Invariant 2 says config.json is created only by bootstrap and never overwritten. So init doesn't touch config.json. It creates <configDir>/proxy.json once, exclusively (wx, the same rule as createExclusive in scripts/mosaic-config.mjs:398), with { "port": N, "binary": "<path>" }.
   • The loader (scripts/mosaic-config.mjs validate :293 and load :362) reads it when present, checks it, and returns it as proxy in the validated config. A missing file means no proxy, which is today's behaviour. A present file with an unknown key, a missing field, a port outside 1024 to 65535, port 8317, or a binary that isn't the pinned install path refuses.
   • The port is a setting with a default. Init picks a free loopback port other than 8317 unless the human names one, and refuses a port that something already listens on.
   • The binary path is the one the fetch installed. Init refuses if the fetch hasn't run or the installed file doesn't match PIN.
   • The config contract for the other rows is "the validated config has proxy.port and proxy.binary". P4 reads proxy.port from it and nothing else.
4. The management key. Init is human-only. It prompts twice with no echo. It sends the key through the bus's human transport with the path-bound proof (packages/bus/src/human-cli.mjs, #225), the same way the human-only settings verbs work (packages/bus/src/runtime.mjs:158). A tester or agent caller refuses. The bus writes <configDir>/secrets/proxy-management.key (0600, exclusive) and the initial <dataRoot>/proxy/config.yaml (0600, directory 0700, auth/ 0700, logs/), once (D5, D6). Running init again refuses and changes nothing. No verb, log or error returns the key.
5. The config template sets these values:
   • host: 127.0.0.1 and allow-remote: false;
   • disable-auto-update-panel: true, with the panel from the pinned install;
   • request-retry: 0;
   • D10's routing defaults (fill-first, session affinity on, rebind on quota, no alias pools);
   • a client-key list holding only the sentinel (msk-<tag>-sentinel-..., D11);
   • the management key.
6. The management client (packages/model-proxy/src/client.mjs) is used by the bus alone (D12). It GETs and PUTs the v8 client-key list and never uses the v0 DELETE ?value= (D14). It sends the management key only in the Authorization header and only to loopback. It logs a receipt per call (call, status, key ids as the first 12 hex of sha256) and never a key value or a list body.
7. The unit. A user unit mosaic-proxy.service (named instance: mosaic-proxy-NAME.service), from a template beside packages/cli/systemd/mosaic-bus.service.in. scripts/instance.sh gets a PROXY_UNIT name next to CONSOLE_UNIT (:84). The unit's start step refuses a binary whose sha256 doesn't match PIN. The bus unit gets Wants= and After= on it only when the instance has a proxy. Tests render and check the unit in a temp root. Nothing is installed or started for real.
8. Correction to D3. At boot the proxy is already listening on its port, so "refuse if another process listens" can't work as the design wrote it. Init refuses a port in use. At boot, P2's sentinel check (D11) is what proves the listener is this instance's proxy.

Acceptance run, recorded in BUILD.md. This runs the pinned binary under unshare -rn against a stand-in upstream, the way row 96 did (agents/researcher/work/i1-proxy-test/). It lives in a script outside the gate's scripts/test-*.sh set, and its output goes in BUILD.md as plain text. It must answer each of these:

• what the proxy does with an empty client-key list (D11);
• whether GET /v1/models with a client key is answered locally, with no upstream call (D17);
• the body and status for a revoked or wrong key, and what Claude Code does with it (row 96 point 4 and note b), recorded only, with no shape fix;
• whether the version can restrict a client key to some models (design section 3, for P2);
• whether the pinned panel works under a /proxy/ sub-path through a minimal loopback forward, and under Content-Security-Policy: sandbox allow-scripts allow-forms with no allow-same-origin (needed by P4);
• what redirect or callback URL the panel's OAuth start returns for Claude and Codex, and whether that callback can come back through /proxy/. If it can't, J3 gets the proxy's CLI login in Jason's own shell as the fallback, and BUILD.md gives the exact command (mos-1600 ruling 3).

Out of scope. Per-agent keys (P2), harness config (P3), the Console forward (P4), usage (P5), any live instance, and the 8317 proxy.

Gate. Boyd gives the first Codex review, and re-measures both hashes from the release. Dewey reviews the landing candidate. The new package suite runs whole, scripts/test-config.sh and every touched test file run whole, and every package suite but queue plus every scripts/test-*.sh is green on Sage's landing gate. BUILD.md has the acceptance output.

Brief: P4 the Console forwards /proxy/ to the instance proxy in a sandbox

Why. D8: Jason reaches the panel at https://mosaic.woltje.com/proxy/ behind the Console's existing sign-in, with no new DNS name (Q116). The Console never injects or stores the management key (mos-1600 ruling 3).

One risk the design missed: the forward serves the panel's HTML and scripts on the Console's own origin. Those scripts would pass the Console's same-origin checks (Origin equal to its own and sec-fetch-site: same-origin, packages/webui/src/serve.mjs:463-464) and could call every Console write route as the owner. The session cookie is HttpOnly (packages/webui/src/sso.mjs:19), but a same-origin fetch still carries it. A bug in the third-party panel would become a bug in the Console. So the forward puts the panel in a CSP sandbox with an opaque origin, and the panel never runs as the Console.

What ships.

1. The route. /proxy/ and below on the human listener is forwarded to 127.0.0.1:<proxy.port> (P1 item 3's contract), and only when the validated config has proxy. Otherwise it answers 404 not-configured.
   • The route is owner-only. It is refused for a granted user (before userRoute, serve.mjs:745), on the tester listener and on a loopback Host.
   • It needs the same sign-in as other owner pages: a session under --sso, or the preview header equal to the user.
   • The path mapping (prefix strip or base path) follows P1's acceptance result for the pinned panel. Until P1 has it, use a fake upstream and record which mapping you built.
2. Requests.
   • Strip the Console session cookie, every x-authentik-* header, the preview header, the proof header and x-mosaic-* before forwarding.
   • Pass Authorization, the management key the panel sends, through unchanged. Never log it, store it or add one.
   • Only the panel's own paths and its management API paths go through. Anything else under /proxy/ answers 404.
3. Responses.
   • Every forwarded response gets Content-Security-Policy: sandbox allow-scripts allow-forms with no allow-same-origin. It also gets the Console's nosniff, no-referrer and frame-ancestors 'none'.
   • Upstream Set-Cookie headers are dropped.
   • The panel then runs with an opaque origin, so its calls arrive with Origin: null. The forward accepts that only on /proxy/ management paths. Every Console route keeps refusing it, and a test proves that.
4. Stop condition. First check on the stand-in whether the pinned panel can sign in and list keys while sandboxed and while the sign-in cookies stay SameSite=Lax. If it can't (for example it needs localStorage, or its API calls lose the sign-in), stop and report to Sage with the evidence. Don't ship an unsandboxed forward. A subdomain is Jason's call (Q116), and a forward without the sandbox is a security boundary change that needs Mos.
5. Logs. Each forwarded call logs method, path, status and user, and never headers or bodies.

Tests. Cover each of these:

• owner allowed, and a granted user, the tester listener, a loopback Host and a signed-out request each refused;
• not configured;
• headers stripped;
• Authorization passed through and absent from logs;
• the CSP sandbox and the dropped Set-Cookie on every response;
• Origin: null accepted on /proxy/ and refused on a Console write route;
• paths outside the allowed set refused;
• an upstream that is down answering 502 with no retry.

The fake upstream is a local test server. P4 doesn't need the binary. Before its gate, P4 reruns P1's panel acceptance step against the real forward and records the result.

Out of scope. Traefik, DNS, Authentik settings, the .54 Console's provider (Q218), and the management key.

Gate. Gladstone gives the first Codex review, Filbert reviews the landing candidate. P4 rebases on P1's landing. The webui suite runs whole with MOSAIC_REQUIRE_EDITOR_BUILD=1, and every package suite but queue plus every scripts/test-*.sh is green on Sage's landing gate.

Brief: P2 per-agent model keys, reconcile and the launch preflight

Why. D11 to D14 and D17: each agent gets its own client key from the stack, revoked before a fire delists the agent, and no session starts on a key the proxy refuses.

What ships.

1. The store kind. A row 199 store kind model (packages/bus/src/credentials.mjs: issue :291, revoke :383, remove :400, status :474) at <configDir>/secrets/agents/<business>/<agent>/model (0600).
   • Its status holds the key id, the issue time and the state, never the value.
   • The kind is implicit for every agent of an instance with a proxy, with no credentials.model reference and no change to roles/*.json (D13, mos-1600 ruling 4).
   • Key format msk-<instanceTag>-<32 random bytes, base64url> (D11).
2. Issue. At hire (packages/business/src/instance-settings.mjs:354) and at the first launch of an agent with no key, the bus GETs the list, PUTs it with the new key, and GETs again to confirm the key is there. Only then does it write the file. Any failure writes nothing and refuses proxy-key-issue-failed.
3. Rotate. rotateBy defaults to 30 days for model keys. The bus PUTs the new key beside the old one, writes the new file and launches new sessions on it. The old key goes once the runs started on it have ended, or after proxy.rotateGraceMinutes (default 120), whichever is first. A session still running then is stopped. The rotation period is human-only (Q222, D20).
4. Revoke. revoke() in packages/bus/src/runtime.mjs:166-197 gains the model kind: GET, PUT without the key, then GET to confirm, and only then remove the file. A failure refuses the fire with credential-revoke-failed, as for the other kinds. It never uses the v0 DELETE.
5. Reconcile at boot. The bus GETs the list once.
   • A key in the record but missing from the proxy is PUT back.
   • A key with this instance's prefix that is in the proxy but not in the record is removed.
   • Keys without the prefix are left alone.
   • A list with no sentinel refuses every launch with proxy-open. That check is also what proves the listener is this instance's proxy (P1 item 8).
   • The reconcile writes a receipt with key ids only.
   • One broker runs per data root, so one bus holds the management client per instance. Say in BUILD.md how the code relies on that.
6. Preflight (D17). Before each launch in proxy mode, the bus sends one GET /v1/models with the agent's key. A 401 refuses proxy-key-refused, and a connection failure refuses proxy-down. A session with no output during the one initial proxy.firstOutputSeconds budget (default 120), armed by successful first actual adapter-child spawn, is stopped and logged as proxy-stall. Idle before then is unarmed; later turns do not reset or extend it; first output cancels. Invalid first-turn metadata uses the same existing stop and value-free receipt once, unless output already cancelled it.
7. If P1 found that a client key can be limited to some models, narrow each agent's key to its role's models. If it can't, say so in BUILD.md. The bundle's model choice stays the guard.

Tests. Use a fake management server for every step above, every refusal code by its own test, and a receipt check that no key value appears in any log, error or status. Add a fire test showing the key is gone from the proxy before the agent is delisted.

Out of scope. Harness env and files (P3), usage (P5), the Console.

Gate. Boyd gives the first Codex review, Dewey reviews the landing candidate (credentials). Every touched test file runs whole, the named mutants below are killed, and every package suite but queue plus every scripts/test-*.sh is green on Sage's landing gate. Mutants: revoke skips the confirming GET; reconcile removes a key without the prefix; the preflight treats a 401 as success.

Brief: P3 harness config from the proxy

Why. D16: in proxy mode each session gets only its own key and the proxy's address, written fresh on every launch, and none of the instance-wide provider variables (mos-1600 ruling 6).

What ships.

1. The bus passes the harness module { baseUrl: "http://127.0.0.1:<port>", key } with today's env answer.
2. Dropped variables. In proxy mode sessionEnv (packages/seat/src/session.mjs:256, ENV_ALLOW :242) stops passing CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_*, OPENAI_API_KEY, OPENROUTER_API_KEY and ZAI_API_KEY from the instance. Without a proxy nothing changes.
3. Claude Code (packages/plugins/harness/claude-code/index.mjs, env :119-126) sets ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN=<key>.
4. pi (packages/plugins/harness/pi/index.mjs, env :63-70) writes <run>/home/.pi/agent/models.json with the provider's baseUrl (no /v1) and sets ANTHROPIC_API_KEY=<key>.
   • A non-Anthropic route names that provider's base URL in the same file.
   • pi gets a preflight that refuses no-session-credential when it has neither a proxy key nor its own credential.
   • Nobody maps CLAUDE_CODE_OAUTH_TOKEN into a pi variable. Whether this closes P19 #383 is Jason's call, and the row doesn't close it.
5. Business settings. launch.models (packages/business/src/launch.mjs:12-24) accepts provider proxy, and launch.account (:81-89) can name the proxy. A business without proxy entries is unchanged. Record the exact key names in BUILD.md.
6. No harness reads the host's ~/.claude, ~/.pi or ~/.codex. The Codex harness config waits for a Codex harness row and isn't here.

Tests. Cover each of these:

• proxy mode drops each named variable, and non-proxy mode keeps today's env exactly;
• the Claude Code env;
• pi's models.json content and mode, rewritten on every launch;
• the pi preflight refusal;
• the proxy provider in launch.models;
• a session env that never holds another agent's key.

Out of scope. Key issue and revoke (P2), the proxy itself (P1), and live sessions.

Gate. Gladstone gives the first Codex review, Dewey reviews the landing candidate. Every touched test file runs whole, and every package suite but queue plus every scripts/test-*.sh is green on Sage's landing gate. Mutant: proxy mode still passes CLAUDE_CODE_OAUTH_TOKEN.

Brief: P5 usage plug-in and per-key limits

Why. D18 and D19 (Q153, Q154, Q222).

Correction to D18 (mos-1600). D18 said the stack counts per account, but D9 says the stack never sees which account served a request. The stack's own count is per agent key. Per-account numbers come only from the cliproxy-queue plug-in or from the panel.

What ships.

1. Per-key quotas. launch.limits.tokens (packages/business/src/launch.mjs:60-75) accepts an agent's key id as a keys name, so a daily quota per agent key is a business setting. It is unset by default, which means no quota, and it is human-only (Q222).
2. The plug-in. A usage plug-in kind with one optional module, cliproxy-queue. It drains GET /v8/management/observability/usage/queue?count=100 through the bus's management client every usage.cliproxyQueue.pollSeconds (default 15, under the proxy's 60 s retention).
   • It maps each event's client key to a key id and drops the value.
   • It maps the upstream account field to an account id the same way. Row 96 saw that field carry an upstream key in plain text (REPORT.md:161), and the stack never stores an upstream credential (D7).
   • It records upstream failures per key id. It is off by default and turned on by plugins.set.
   • It never enforces a quota alone.
   • A msk- key that isn't in the record goes to the reconcile log.
3. The Console view. Usage shows the stack's per-key count. When the plug-in is on, it also shows the plug-in's per-account numbers, labelled as the proxy's.

Tests. Use a fake queue that returns events with made-up client keys and upstream values, and check that no value of either kind appears in any store, log or view. Also test the poll interval setting, plug-in off by default, a quota per key id, and the unknown-key reconcile entry.

Out of scope. Quota enforcement from proxy numbers, and the panel.

Gate. Boyd gives the first Codex review, Dewey reviews the landing candidate. Every touched test file runs whole, and every package suite but queue plus every scripts/test-*.sh is green on Sage's landing gate. Mutant: the reader stores the upstream account value instead of its id.