The proxy keeps Anthropic and OpenAI API keys, Claude setup tokens, and Codex workspace tokens on the host. It is opt-in, off by default, and supports Firecracker and Lima.
With open networking and without proxy mode, coop forwards the raw
ANTHROPIC_API_KEY / OPENAI_API_KEY into the guest as SSH SendEnv
variables — a prompt-injected or rogue agent can read them from its own
environment and exfiltrate them. Isolated Firecracker
mode suppresses direct credentials and requires
the corresponding managed proxy for Claude or Codex.
With proxy mode, the raw credential never enters the guest. coop runs a
small host-side reverse proxy (coop-proxy) — one process per (VM, provider) —
for the lifetime of the VM:
- The proxy binds host loopback and is exposed into the guest by a per-instance
ssh -Rreverse tunnel; the guest is pointed athttp://127.0.0.1:<port>and holds only a per-instance capability token.- Claude Code:
ANTHROPIC_BASE_URL+ANTHROPIC_AUTH_TOKENin the managed~/.claude/settings.json. - Codex: a
[model_providers.coop_local]block in~/.codex/config.toml(base_urlat the proxy,wire_api = "responses") with the capability token supplied as the provider's bearerenv_key. Proxy mode pins no model — Codex keeps its own, only its egress is redirected.
- Claude Code:
- The proxy verifies that token (constant-time), strips it, injects the real
credential (
x-api-key, orAuthorization: Bearer), and streams the request to the pinned upstream (api.anthropic.com,api.openai.com, or the Codex backend onchatgpt.com) over TLS. - The raw
ANTHROPIC_API_KEY/OPENAI_API_KEYis no longer forwarded, and in proxy mode Codex's~/.codex/auth.jsonis not staged onto the guest disk (it holds a refreshable subscription token — the exact at-rest exposure #411 closes). A cached ChatGPT OAuth session is not supported in proxy mode; use an OpenAI API key or a Codex workspace personal access token.
When agent bootstrap runs with an OpenAI proxy, coop also removes any existing
~/.codex/auth.json left by a previous direct-auth boot. If removal fails,
proxy bootstrap aborts and tears down the proxy. --no-agents skips this
cleanup along with the rest of agent bootstrap.
For workspace entitlements through the proxy, use a Codex personal access
token as described below. For interactive account login inside the guest, use
[codex] auth = "chatgpt" instead of [proxy.openai]. That mode stores Codex
credentials in the guest Linux keyring and cannot be combined with a proxy.
The capability token is worthless off the host — it only authorizes the local proxy, which holds the real key itself — so exfiltrating it gains a compromised guest nothing.
After authenticating the capability token, the proxy default-denies operations before connecting upstream. The only allowed method/path pairs are:
| Provider | Allowed operation |
|---|---|
| OpenAI | POST /v1/responses |
| Codex access token | POST /v1/responses, translated to POST /backend-api/codex/responses on chatgpt.com |
| Anthropic | POST /v1/messages |
| Anthropic | POST /v1/messages/count_tokens |
All other methods, paths, and unknown upstream profiles receive a local 403.
This limits a compromised guest to the model calls its configured coding agent
needs, and prevents it from using the injected key for account, model, admin,
or arbitrary retrieval APIs. Widening this list requires security review and
tests for the new agent operation.
The request bodies are intentionally opaque and streamed. In particular, an
allowed POST /v1/responses can still reference OpenAI objects by ID (such as
existing conversations, responses, prompts, or files) when the injected key is
authorized for them. The allowlist is defense in depth against broad API use,
not object-level tenant isolation.
The policy is intentionally closed: if a future agent version needs another
endpoint, it fails locally with 403 until coop adds and reviews that route.
Claude Code may issue HEAD /api/hello and GET /v1/models?limit=1000 for
warmup or discovery; proxy mode intentionally refuses both because its normal
message and token-count operations do not require gateway discovery. Codex's
proxy provider is named coop credential proxy, not OpenAI, so Codex does
not currently enable its OpenAI-specific POST /v1/responses/compact behavior.
If either client changes this behavior, add the route only with an explicit
policy, test, and documentation update.
The easiest path is coop proxy setup: it takes a pasted credential, stores it
in a secret backend of your choice (macOS Keychain / Linux secret-service /
1Password / a 0600 file), and writes the [proxy.<provider>] block for you with
a cmd: reference — so the credential is never plaintext in the config.
- Anthropic (default):
coop proxy setuptakes a Claudesetup-token(subscription) or an API key with--api-key. To generate a token first, runclaude setup-tokenon the host (needs a Claude subscription; the token is inference-scoped, ~1 year). - OpenAI (Codex):
coop proxy setup --openaitakes an OpenAI API key (always injected asAuthorization: Bearer). - Codex workspace access token:
coop proxy setup --openai --codex-access-tokentakes a Codex-scoped personal access token (at-...) from ChatGPT Admin > Access tokens. Requests use the creator's workspace Codex entitlements and controls rather than Platform API billing. Availability and usage charges follow the workspace plan. A Workspace Agents-only token is not a Codex inference credential.
Or configure it by hand:
[proxy.anthropic]
credential = "cmd:op read op://Private/Anthropic/credential" # or a plain key
auth = "api_key" # api_key → x-api-key (default); bearer → a Claude setup-token
[proxy.openai]
credential = "cmd:op read op://Private/OpenAI/credential"
auth = "bearer" # OpenAI keys inject as Authorization: BearerFor a Codex workspace token, use this OpenAI block instead:
[proxy.openai]
credential = "cmd:op read op://Private/Codex/access-token"
auth = "codex_access_token"Leave [codex] auth at its default (api_key); in proxy mode the host
credential determines billing, and the guest authenticates only with its
capability token. No guest codex login is required. Cached OAuth credentials
and legacy agent-identity JWTs are not accepted by this mode.
Setup and every proxy start validate the token with a bounded HTTPS metadata
request to auth.openai.com. Host curl is required. The proxy then pins
chatgpt.com and the workspace headers returned by that lookup, replacing any
guest-supplied account or FedRAMP headers. The real token travels through stdin
to curl and the proxy; it is never a command-line argument. The guest cannot
call metadata, login, refresh, or arbitrary ChatGPT endpoints through the proxy.
The guest provider uses streaming HTTP Responses requests with WebSockets
disabled. Model selection stays with Codex; choose a model available to your
workspace. This inference-only proxy does not expose ChatGPT plugins or account
management. Expired/revoked tokens fail authentication; there is no OAuth
refresh or API-key fallback. Rotate the secret, then restart the VM to load it.
CODEX_ACCESS_TOKEN, as well as OPENAI_API_KEY, is suppressed from managed
environment forwarding whenever the OpenAI proxy is active. Explicit
guest_files copies remain a separate credential-exposure opt-in.
The credential uses the same cmd: resolution as every other coop secret and
is resolved on the host at VM start. For Claude subscription billing without
exposure, run claude setup-token on the host, stash the printed one-year
token, reference it via cmd:, and set auth = "bearer".
The [proxy.<provider>] blocks are the defaults for every VM. A single VM
can use a different credential — for per-project billing, scope, or revocation —
with coop proxy setup --openai --vm <name> (or --anthropic --vm <name>). The
override is stored in that instance's state (<inst.dir>/proxy.json), not in a
growing config table, and its secret is namespaced separately (coop-openai-<vm>).
Resolution per provider is override → default → off: the per-VM override wins, else the config default, else the proxy is off for that provider. This is purely host-side credential selection — the proxy binary and the per-VM capability token are unchanged, so there is no new attack surface.
coop proxy status shows the defaults and every VM's overrides; coop proxy status --vm <name> shows one VM's effective resolution. Credentials are shown
as their cmd: reference (a command, not the secret); a hand-written literal is
redacted.
Proxy mode applies only in remote model mode. coop model <vm> local takes
precedence (the VM routes at your local model server and the proxy is torn
down). If credential resolution fails at start, the VM fails closed — it
does not come up on a path where the agent silently has no or the wrong key.
It stops a rogue agent from reading a usable key from its environment or disk. It does not:
- Stop use of the credential while the agent runs — the agent still makes model calls through the proxy (that is the point). Non-exposure limits exfiltration of the raw key, not use during the session.
- Provide egress control — a token-less agent with open egress can still reach arbitrary hosts (issue #2). The proxy composes with, but does not replace, "no route out except the proxy."
- Provide scope enforcement — the injected key keeps its full account scope (issue #73). Non-exposure and scope are orthogonal.
The proxy itself is new attack surface, mitigated by a fixed per-route upstream (the guest controls only the path, never the host — closing SSRF), TLS verification against a pinned root set, a required capability token, and resource limits. Each proxy allows at most 256 accepted guest TCP connections and 256 concurrent requests; excess connections are closed immediately, so idle sockets cannot bypass the request limit. The listener binds only host loopback and is reverse-tunnelled to exactly one guest — never a non-loopback interface, never the LAN.
It is also jailed to bound the blast radius of a proxy exploit. On Linux,
Landlock denies filesystem writes and program execution as a required floor;
additional filesystem restrictions apply where the kernel supports them. TCP
egress is limited to :443 and :53 on kernels ≥6.7. On kernels 5.13–6.6,
the proxy can start with that TCP restriction absent. On macOS, sandbox-exec
applies a Seatbelt profile that denies filesystem writes and program execution
and limits egress to those ports.
Startup fails closed if the required filesystem/exec floor cannot be applied.
The network rules are port-scoped, not host-scoped, and Landlock does not
restrict UDP. See trust-model.md for the full threat model
and accepted limitations.
Firecracker (Linux) and Lima (macOS). The proxy binds 127.0.0.1 on the
host and is exposed into the guest with a per-instance ssh -R reverse tunnel,
so it works identically on both backends (each already keeps an SSH channel to
its guest). The host-side proxy process is jailed on both — Landlock on Linux
(enabled on the host; kernel ≥5.13, with TCP scoping from ≥6.7), Seatbelt via
sandbox-exec on macOS. GitHub credentials are not supported.