Skip to content
Runtime

How to run Claude Code in a cloud sandbox

Install it with npm in a Linux microVM. Store the API key as a secret, run claude -p on a cloned repo, and copy the diff back.

Start free, no cardRead as Markdown

On Runtime, the agent runs on a machine of its own and never holds your key. Every sandbox is a Firecracker microVM with Ubuntu 24.04 and Node.js 24, so Claude Code's npm package installs unchanged. Your Anthropic key is stored as a Runtime secret. The sandbox sees a placeholder, which is not a valid key. The host's proxy adds the real key only to requests to api.anthropic.com. A 2 vCPU, 4 GiB sandbox costs $0.03125 an hour while the agent waits on the model. Claude Code 2.1.310 was the current npm release on 25 October 2026.

There are two ways to combine the two:

You want Do this
Claude Code to work on a repo away from your laptop Run Claude Code inside a sandbox (below)
Claude Code on your machine to run code safely Add Runtime's MCP server, and it creates sandboxes as tools

Store the key once

Store your Anthropic key as a secret bound to Anthropic's API host. Every sandbox in your account then has ANTHROPIC_API_KEY set to a placeholder. Only an HTTPS request to that host carries the real value (secrets sandboxes never see).

Terminalprintf %s "$ANTHROPIC_API_KEY" | npx withruntime secrets set ANTHROPIC_API_KEY --host api.anthropic.com

The value is read from standard input, so it never lands in your shell history. No API, tool or command returns it afterwards. If a prompt injection makes the agent print its environment, the output shows the placeholder.

Run Claude Code on a repo

TypeScriptimport { writeFile } from "node:fs/promises";import { Sandbox } from "withruntime";const repo = "https://github.com/your-org/your-repo";const task = "Find and fix the failing test in the parser, then run the tests.";await using sbx = await Sandbox.create({ diskMiB: 8192, timeoutSeconds: 3600 });const slow = { check: true, timeoutMs: 600_000 } as const;await sbx.exec("npm install -g --prefix /workspace/.local @anthropic-ai/claude-code", slow);await sbx.exec(["git", "clone", "--depth", "1", repo, "/workspace/app"], slow);// From here on the agent reaches only the model and the npm registry.await sbx.network.set({ internet: true, allow: ["api.anthropic.com", "registry.npmjs.org"] });const run = await sbx.exec(  [    "claude",    "--bare",    "-p",    task,    "--allowedTools",    "Bash,Read,Edit,Write",    "--output-format",    "json",  ],  {    cwd: "/workspace/app",    env: { CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" },    timeoutMs: 1_800_000,    onStderr: (text) => process.stderr.write(text),  },);const result = JSON.parse(run.stdout);console.log(result.result, result.total_cost_usd);await sbx.exec("git add -A && git diff --cached > /workspace/change.patch", {  cwd: "/workspace/app",  check: true,});await writeFile("change.patch", await sbx.files.readText("/workspace/change.patch"));
Pythonimport sys, jsonfrom withruntime import Sandboxrepo = "https://github.com/your-org/your-repo"task = "Find and fix the failing test in the parser, then run the tests."with Sandbox.create(disk_mib=8192, timeout_seconds=3600) as sbx:    sbx.exec("npm install -g --prefix /workspace/.local @anthropic-ai/claude-code",             check=True, timeout_ms=600_000)    sbx.exec(["git", "clone", "--depth", "1", repo, "/workspace/app"],             check=True, timeout_ms=600_000)    sbx.network.set(internet=True, allow=["api.anthropic.com", "registry.npmjs.org"])    run = sbx.exec(        ["claude", "--bare", "-p", task, "--allowedTools", "Bash,Read,Edit,Write",         "--output-format", "json"],        cwd="/workspace/app",        env={"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"},        timeout_ms=1_800_000,        on_stderr=sys.stderr.write,    )    result = json.loads(run.stdout)    print(result["result"], result["total_cost_usd"])    sbx.exec("git add -A && git diff --cached > /workspace/change.patch",             cwd="/workspace/app", check=True)    with open("change.patch", "w") as file:        file.write(sbx.files.read_text("/workspace/change.patch"))

What each part does:

  • --prefix /workspace/.local installs the claude command into /workspace/.local/bin, which is first on the sandbox's PATH. Anthropic's guide warns against sudo npm install -g. This install needs no sudo.
  • --bare skips hooks, plugins, MCP servers and CLAUDE.md discovery. It reads ANTHROPIC_API_KEY from the environment. Anthropic recommends it for scripted runs. Pass --append-system-prompt-file CLAUDE.md to keep the repo's own instructions.
  • --allowedTools approves those tools without a prompt, since nobody is there to answer one. The sandbox is the boundary. The agent can run any command inside it and nothing outside it.
  • The task is an array element. It reaches claude with no shell in between, whatever quotes or symbols it holds.
  • --output-format json returns the answer in result, along with session_id and total_cost_usd. The cost is Anthropic's estimate of the model cost.
  • The diff comes back as a file. A large change is therefore never cut at the 64 KiB result limit.

A timeout longer than 60 seconds makes the command stream, so the result keeps all of its output. onStderr shows progress as it happens.

Headless flags that matter

Checked in Anthropic's documentation on 25 October 2026:

Flag What it does
-p, --print Runs once, non-interactively, and exits 0 on success
--bare Skips local configuration; uses ANTHROPIC_API_KEY
--allowedTools "Bash,Read,Edit" Approves those tools without asking
--permission-mode acceptEdits Writes files without asking; other commands still need a rule
--output-format json One JSON result: result, session_id, total_cost_usd
--output-format stream-json --verbose One JSON event per line as the run goes
--continue, --resume <id> Carries on an earlier conversation

To run a second task on the same checkout, keep the sandbox. Pause it between tasks. Its files, memory and processes are kept, and compute billing stops.

Give Claude Code Runtime as a tool

The other direction: Claude Code on your own machine creates sandboxes, runs commands in them and reads files back. It does this through Runtime's MCP server.

Terminalclaude mcp add --scope user runtime -- npx -y withruntime mcp

The first call shows a link and a code. Approve Connect agent in your browser. Every Runtime tool then appears, with no key to copy and nothing to restart (MCP). A machine already connected by npx withruntime login skips that step.

To connect without the local bridge, add the remote server and run /mcp to sign in:

Terminalclaude mcp add --transport http --scope user runtime https://api.withruntime.com/mcp

The tools Claude Code uses most:

Tool What it does
runtime_sandboxes_create A new sandbox, ready when the call returns
runtime_sandboxes_exec Runs a command and returns its exit code and output
runtime_sandboxes_files_read, runtime_sandboxes_files_write Reads and writes files in the sandbox
runtime_sandboxes_network Narrows or turns off the sandbox's internet
runtime_sandboxes_previews Shares a port at a private HTTPS address
runtime_secrets Stores a key the sandbox uses without seeing

In CI, RUNTIME_API_KEY from a secret manager replaces the browser approval. The full list is in MCP tools. Coding agents has the same setup for Codex, Cursor and others.

What it costs

Runtime bills the CPU the agent uses at $0.025 per vCPU-hour, with a floor of a twentieth of a vCPU. Memory is billed at $0.0075 per GiB-hour. A coding agent spends most of its time waiting on the model. That time costs $0.03125 an hour for 2 vCPUs and 4 GiB. With both CPUs busy, the rate is $0.08 an hour (pricing). Anthropic bills model tokens on your key.

A new account gets 100 free hours of a 1 GB machine in its first 30 days. No card is needed:

Terminalnpx withruntime sandboxes run -- node --version

The first run prints a link to approve in your browser. The same setup for OpenAI's agent is in Codex in a sandbox. To run many agents at the same time, see a sandbox for coding agents.

Sources

Checked 25 October 2026.

Facts on this page were checked on 25 October 2026.

Related.

100 free hoursin your first 30 days.

of a 1 GB machine

  • No credit card
  • Four sandboxes at once, 2 vCPU and 4 GiB each
  • Then prepaid credit from $10, no plan fee
Start free, no card
Start free, no card