Give Claude Code a cloud Linux sandbox with Oyster

You can give Claude Code a sandbox in the cloud without moving its conversation off your laptop. Oyster supplies the MCP server for your own Apps. Shed runs shell commands on the cloud Computer, and Inkcap reads and writes its files. The commands run in a Linux workspace in a Cloudflare Container, not on your laptop.

This connects an existing MCP client to remote tools. It does not install Claude Code inside the Container or move every local tool call there. Ask the agent to use Oyster’s tools for the remote work.

Before you start

You need Claude Code, or another client supporting Streamable HTTP MCP, and a deployed Oyster with a Computer. Deployment needs a Cloudflare account on Workers Paid with Containers, Artifacts, Workers AI, Workflows and Browser Rendering enabled, plus Docker, Node 24, pnpm 11 or newer and Git.

Oyster’s laptop-only quick start has no Computer. Use the deployed setup for this guide.

1. Deploy Oyster and install its Apps

Follow Run your own Oyster and the Oyster quick start. Keep the owner key private. With the deployed address and owner key configured in your terminal:

TERMINAL

export OYSTER_URL=https://oyster.<your-subdomain>.workers.dev
export OYSTER_OWNER_KEY='<your owner key>'
npx oyster install-apps

The installer builds and installs the seven starter Apps, including Shed and Inkcap. The first install takes about 15 to 20 minutes. Sign in at $OYSTER_URL/login with your owner key and check that both Apps open.

2. Issue a separate key for the agent

As the owner, create a named key:

TERMINAL

curl -s -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" \
  -H 'content-type: application/json' \
  -d '{"name":"morel","grants":[{"capability":"apps.use","targets":{"kind":"all"}}]}' \
  "$OYSTER_URL/api/keys"

The response shows the key once in plaintext, beginning oyk_. Store it privately; give the agent this key, not the owner key. A separate key attributes its calls and Git pushes to that agent.

This is broad access, not a read-only sandbox credential. An apps.use key targeting all Apps can read and write every App on that Oyster, including Apps installed later. Anyone holding it can act as the owner in those Apps.

App writes need the owner’s approval, but issuing this key records that approval: its App calls do not ask again for each write. Do not expect a per-command confirmation before Shed executes a command. Other write calls, including the owner’s own MCP calls, need explicit approval through a client supporting form elicitation.

3. Connect Claude Code

Run this on the laptop where Claude Code is installed, substituting the agent key privately:

TERMINAL

claude mcp add --transport http oyster "$OYSTER_URL/mcp" \
  --header "Authorization: Bearer <the agent's key>"

Oyster exposes one execute tool. Inside it, installed App methods are available as env.<APP>. Discover their current inputs with forage.search and forage.describe before calling them. Another MCP client uses the same /mcp address and Authorization: Bearer <key> header.

4. Run a command on the cloud Computer

Ask the agent to call Shed from Oyster’s execute tool:

JS

return await env.SHED.runCommand({
  command: "pwd && uname -s",
  cwd: "/workspace",
  timeoutMs: 45000,
});

Expect /workspace and Linux in stdout, with exitCode: 0. Check stderr, exitCode and the truncation flags rather than treating returned output as success. Shed’s runCommand has a 45-second maximum and retains at most 64 KiB per output stream.

For file access, the agent can call Inkcap through the same tool:

JS

return await env.INKCAP.writeFile({
  path: "/workspace/sandbox-check.txt",
  content: "Written on the cloud Computer.\n",
});

Then read it:

JS

return await env.INKCAP.readFile({
  path: "/workspace/sandbox-check.txt",
});

Inkcap returns file bytes as base64, with encoding: "base64" and a truncated flag. Reads are bounded to 128 KiB. Paths must be absolute and cannot contain ... Open the same file in Inkcap’s browser editor to inspect it.

Limits and stopping access

• The Computer keeps its workspace when its Container stops. Processes do not survive that stop; running a command starts the Container again.
• A missing App or not_granted refusal is not a successful command. Check the installation and its Computer permissions before retrying.
• Revoking the agent’s key stops its access. Key grants are immutable; to narrow them, revoke the key and issue another rather than editing it. See Oyster’s key and MCP contract.
• Inspect any files and processes the agent already created. Revocation is not an undo operation.

For the browser terminal, processes, port previews and editor, continue with Use Computers. To sandbox a local Fungi Agent instead, see Sandbox a coding agent on Linux and macOS.