Engineering · Claude Code · Gateway
How to run Claude Code in the cloud without patching it
How we run Claude Code in the cloud unmodified and configured per run, why a 128K output default read as auth failures, and the 64,000-token fix that held.
On this page
On October 13 we turned on $20 of Claude Opus 5.5 credit for new members, and the first real Claude Code run on it printed "Claude API authentication failed" ten times and then gave up. Nothing was wrong with authentication: the gateway was refusing the request size, and Claude Code has one way of reading a 403.
That bug is most of this post. The rest is how we run Claude Code in the cloud in general, because the bug only makes sense once you see how the binary is configured.
How we run Claude Code in the cloud: stock binary, per-run settings
Each sandbox installs @anthropic-ai/claude-code at a pinned version (2.1.296 in production today), and an install probe on every bootstrapped sandbox checks that the binary on disk belongs to exactly that package and version. No fork, no patched auth. Our runtime drives it headless over stream-json.
The Claude Code process stays resident across turns in a thread, but each turn is a different run with its own credential, model and limits. Restarting the agent every turn would throw away its warm state, so we don't. The launcher exports only two things into the environment: the gateway URL and the config directory. Everything else that changes per run goes in a settings file passed with --settings, rewritten before every turn:
{
"apiKeyHelper": "cat \"<per-run capability file>\"",
"env": {
"ANTHROPIC_MODEL": "claude-opus-5-5[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5[1m]",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-opus-5-5[1m]",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-opus-5-5[1m]",
"CLAUDE_CODE_SUBAGENT_MODEL": "claude-opus-5-5[1m]",
"CLAUDE_CODE_API_KEY_HELPER_TTL_MS": "1",
"CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000"
}
}The apiKeyHelper never sees an Anthropic key. It reads a capability our backend mints for this one run, which only our gateway accepts. With the helper TTL at 1 ms, Claude Code calls the helper on every request, so when the next turn's capability lands in the file the resident process picks it up without a restart. The real key stays on the gateway, outside the sandbox. Why that split matters is in AI agent sandbox architecture.
Every model slot points at the run's model
Claude Code doesn't only call the model you picked. It sends small helper calls (the session title, for one) to a Haiku-class slot, and subagents have their own slot. Our gateway refuses any model the run didn't start with, because the run's model is what we bill and what the member chose. So all five slots name the run's model.
The [1m] suffix is Claude Code's own selector for the 1M-context window. It is local metadata: Claude Code strips it before calling the API, so the gateway still sees the canonical id claude-opus-5-5, while the runtime knows the real context size and still compacts when it fills.
The 128K default broke every call
Here is the sequence from October 13.
The credit code had been through about ten review rounds and 290 tests. Two proof runs went out on production, one on Claude Code and one on OpenCode. Both were admitted on the credit, and both died without a single row in the gateway's audit table. Claude Code said "Claude API authentication failed" ten times, then "no progress". OpenCode said output_limit_exceeded.
The OpenCode error was the honest one. Claude Code on claude-opus-5-5[1m] sends max_tokens: 128000 on every main call; that is its default for the 1M-context Opus models. OpenCode asks for the full 128,000 its catalog lists for the model too. Our gateway's per-request output ceiling is 65,536. About half. The request policy refused both with a 403 before the audit row was written, which is why there were zero rows.
To see what Claude Code does with that 403, we pointed the real 2.1.296 binary at a stub that returned exactly our refusal:
api_retry error_status:403 error:"authentication_failed"
...
retry attempt 10: Claude API authentication failedTen retries with backoff, the same last line production had printed after 169 seconds. Claude Code reads a 403 from its API as an auth problem, and that's reasonable when the endpoint is Anthropic. It's wrong when the endpoint is a gateway with other reasons to say no.
The part I keep coming back to: 290 tests and ten rounds of adversarial review, all against simulated transports. None ran a real engine binary against the real gateway. The first real run found it in one try. We now don't put money-feature keys into production until one real run per engine has passed on a real stack.
64,000 tokens for both engines
The fix has two halves.
First, ask for less. CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000 brings Claude Code's max_tokens down to 64,000, and it works from the env block of the settings file as well as from the real environment, so it rides the same per-turn file as everything else. It's set for Anthropic models only; GLM keeps Claude Code's own 32K default. OpenCode gets the same number through a per-model limit.output in its config. One constant feeds both, and a test fails if it ever rises past the gateway ceiling:
/** The most output an engine asks an Anthropic model for (OpenCode's model
* limit, Claude Code's CLAUDE_CODE_MAX_OUTPUT_TOKENS): under the gateway's
* default ceiling (limits.ts; its test holds the two apart), and over the
* 16,000-token thinking budget a manual-thinking model gets. */
export const ANTHROPIC_ENGINE_OUTPUT_TOKENS = 64_000;Why 64,000 and not 65,536: it stays under the ceiling with room, and it's well above the 16,000-token thinking budget that older manual-thinking models get, so thinking never eats the whole answer.
With the cap in place we drove the binary exactly the way the sandbox does (stream-json, the settings file, only the gateway URL and config dir in the environment). The title call, three main calls (a Bash tool turn, a WebSearch turn, the final answer) and the WebSearch sub-call all went out with max_tokens=64000 and got a 200. The production proof run answered on the next deploy.
Refuse in Anthropic's shape, not ours
The second half is about the next time something is over a limit. Our gateway now answers an over-limit request on the Anthropic route with Anthropic's own error, status 400:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "max_tokens 128000 is above this gateway's limit of 65536"
}
}Claude Code stops on a 400 and shows the message. One line. No ten retries, no auth wording, and the person reading the run sees the actual reason.
The same shape covers a model the run doesn't use. That one came up for real: after Opus 5.5's safeguards flagged a session, Claude Code fell back to another model, our gateway said 403, and Claude Code retried it as an authentication failure. Now it gets "This task runs on claude-opus-5-5; other models are not available to it here." as a 400 and the turn ends cleanly.
One more thing went soft instead of hard. The credit allows a fixed list of Anthropic beta headers. We used to refuse a request carrying an unknown beta; now we drop it, send the rest, and log it once per run. Betas that change the price, like fast mode, stay off the list, so dropping is safe.
Your Claude plan versus our credit
People ask whether they can use their Claude Pro or Max plan. Not on the hosted app yet. Anthropic's rule for hosted products is specific: the binary must be unmodified, each user signs in through Anthropic's own flow, and the product never collects, stores or relays the Claude.ai credentials or session token, and never pays for or resells the usage. A third-party app can't offer its own "log in with Claude", and the Agent SDK is API keys only.
Our sandboxes are short-lived and scoped to a thread, so following that rule means a fresh sign-in inside each new sandbox. We haven't shipped plan sign-in on the hosted app. Persisting a login across sandboxes is exactly the part the rule doesn't clearly allow, and we're not going to guess.
So on the hosted app, Claude Code runs on:
- your own Anthropic API key, connected in Settings, write-only and never in the sandbox;
- the $20 of Claude Opus 5.5 credit every new member gets (Claude Code and OpenCode, not Codex);
- after that, GLM credits from us. Claude Code talks to GLM through Z.ai's Anthropic-compatible endpoint, with the same gateway in front.
A first Claude Code turn on the credit costs about $0.35, most of it a 69K-token cache write. How the gateway meters a per-member credit without letting a sandbox spend past it is in an LLM gateway with per-user credit.
Check the version that actually runs
A small thing that misled us during that incident: the sandbox image file still pinned Claude Code 2.1.226 and OpenCode 1.18.7, and neither was what ran. The runtime installs its own pinned versions at bootstrap, 2.1.296 and 2.0.26. Our first notes on the failure quoted the wrong versions because we read the image file. It now pins the same versions the runtime installs.
One earlier install failure is worth knowing if you build your own images. On one sandbox provider, a desktop helper installed a browser MCP package with npm install -g into the same prefix and cache as the Claude Code install, at the same time. The Claude install failed, our retry wiped the shared cache while the other npm was still writing, and the error became ENOTEMPTY. The fix gave the retry a private npm cache; later we moved every engine to the runtime's own staged install. If you install Claude Code in your own containers, install it alone, or with its own cache.
If you want to see this running, start a thread with Claude Code, or read the settings code in the repo.
Frequently asked questions
Why does Claude Code say authentication failed when my API key is fine?
Claude Code treats a 403 from its API endpoint as an authentication failure and retries it. If a proxy or gateway refuses the request for another reason, such as max_tokens above its limit, you see 'authentication failed' even though the key is valid.
How do I lower Claude Code's max output tokens?
Set CLAUDE_CODE_MAX_OUTPUT_TOKENS, either as an environment variable or in the env block of a settings file passed with --settings. We set it to 64000 for Anthropic models in every sandbox.
Can I use my Claude Pro or Max plan in UseAgent's hosted sandboxes?
Not today. Anthropic allows it only when each user signs in through Anthropic's own flow and the product never stores the session, and our sandboxes are short-lived per thread. Hosted Claude Code runs on your Anthropic API key or on our credit.