Home / Docs / Clients / Claude Code · also: Quickstart

Claude Code

Claude Code (the claude CLI) speaks remote MCP over HTTP, so it connects to our sandbox endpoint directly. Pick one of two sign-in paths. Both give the same ten tools.

Install

The agent-full template already has Claude Code, so inside a sandbox you can skip this. On your own machine use Anthropic's installer:

curl -fsSL https://claude.ai/install.sh | bash
claude --version

Path 1: X-API-Key header (headless)

Use your tenant API key (the value of E2B_API_KEY). No browser needed. Keep the key in an environment variable and put the variable name, not the key, in the command. Claude Code saves the header text exactly as given and expands ${SANDBOX_API_KEY} each time it starts, so the key never lands in its config or in the config backups it writes.

read -rs SANDBOX_API_KEY && export SANDBOX_API_KEY   # paste the key, nothing is echoed or saved in history
claude mcp add --transport http sandbox https://api.sbx.agent-next.com/mcp/v1 \
  --header 'X-API-Key: ${SANDBOX_API_KEY}'
claude mcp list

Use single quotes around the header. Double quotes make your shell replace the variable with the key before Claude Code sees it, and the key is then written to ~/.claude.json and to ~/.claude/backups/. claude mcp list health-checks the server: a key that works passes, and a key it refuses prints ! Needs authentication. A variable that is not exported is a different failure — the output carries a diagnostics warning naming SANDBOX_API_KEY — so export it in every shell that starts claude. Add --scope project to write .mcp.json instead (safe to commit, it holds only the variable name). The same commands work inside an agent-full sandbox.

Path 2: OAuth sign-in

No key to paste. This path needs a browser once, on any machine, to approve the sign-in.

claude mcp add --transport http sandbox https://mcp.agent-next.com/mcp
claude

Inside Claude Code run /mcp, pick sandbox, choose Authenticate, and finish the sign-in in the browser tab it opens. The token resolves to the same tenant as your API key.

Common errors

Every message below was produced by claude 2.1.296 while this page was written. What the MCP server itself answers — statuses, error codes and retryable failures — is in the errors reference.

• Missing environment variables: SANDBOX_API_KEY under MCP config diagnostics — the variable is not exported in this shell, so the header goes out empty. Run the read -rs line above, or export SANDBOX_API_KEY=..., before claude. Nothing is stored in place of the key.
• sandbox: ... - ! Needs authentication — the header went out and was refused: the key is empty, wrong or revoked, and the server answers 401 {"code":401,"message":"invalid API key"}. Check the key. On the OAuth path the same line means you have not signed in yet: run /mcp inside Claude Code, pick sandbox, choose Authenticate, then approve in the browser tab it opens.
• ✘ Failed to connect — ENOENT ... posix_spawn 'https://api.sbx.agent-next.com/mcp/v1' — --transport http was left out, so Claude Code stored the URL as a stdio command. Run claude mcp remove sandbox and add it again with that flag.
• MCP server sandbox already exists in local config — the name sandbox is taken in that scope. Remove it first with claude mcp remove sandbox, or pick another name or scope.
• ⏸ Pending approval — an entry written with --scope project into .mcp.json is not connected until it is approved once: start claude in that repository and approve it.
• The server disappears when claude runs from another directory — the default scope is local, private to the project that added it. Add it with -s user to have it in every project (it lands in ~/.claude.json, still holding only the variable name).
• The key itself shows up in ~/.claude.json — the header was added with double quotes. Remove the entry, add it again with single quotes, then delete the backups that hold the key (see Uninstall).

Model setup

On your own machine, sign in to Claude Code as usual. Inside a sandbox there is no Anthropic account, so point Claude Code at our model gateway with your model key (AGENT_NEXT_API_KEY, from the console; it is a gateway key, not an Anthropic key and not your sandbox key). Set it in the environment, never as a command-line flag:

export ANTHROPIC_BASE_URL=https://gateway.agent-next.com
export ANTHROPIC_AUTH_TOKEN="$AGENT_NEXT_API_KEY"
claude --model zai/glm-5.3

Gateway model ids like zai/glm-5.3 are never in Claude Code's bundled catalog, and Claude Code 2.1.296 makes a headless run (claude -p) hang on its unknown-model prompt — it prints <model> isn't described by this version's model catalog and then waits, looking hung. The agent-full template sets CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1, so the run goes straight to the gateway: a served id works, an unknown id fails fast with the gateway's own error. On an older image, export that variable yourself before running.

Try it

Ask Claude Code: "create a sandbox, run echo ok; exit 3 in it, write and read back a file, then kill it". It calls sandbox_create, sandbox_exec (you get exit_code 3), sandbox_files_write, sandbox_files_read and sandbox_kill. There is no list-files tool: to list a directory, ask it to run ls through sandbox_exec.

Uninstall

First ask the agent to sandbox_kill your sandboxes: they keep running until killed or until their timeout. Then remove the entry:

claude mcp remove sandbox

That deletes the saved server entry only. Claude Code copies ~/.claude.json to ~/.claude/backups/.claude.json.backup.* on every config write, and remove does not touch those copies. With the variable form above the copies hold only ${SANDBOX_API_KEY}. If the key was ever pasted literally (double quotes, or older instructions), export the variable again, then delete every backup that still contains the key. The key goes to grep on standard input, so it never shows in a process list:

if [ -z "$SANDBOX_API_KEY" ]; then
  echo "export SANDBOX_API_KEY first: it is the key to look for" >&2
else
  printf %s "$SANDBOX_API_KEY" | grep -lF -f - ~/.claude/backups/.claude.json.backup.* 2>/dev/null \
    | while IFS= read -r f; do rm -- "$f"; done
  printf %s "$SANDBOX_API_KEY" | grep -rlF -f - ~/.claude ~/.claude.json 2>/dev/null   # prints nothing when clean
fi
unset SANDBOX_API_KEY

If the last grep still lists a file, that file holds the key: edit the key out or delete it. For OAuth, this page has not checked whether remove clears Claude Code's stored token; sign out from /mcp first.

Next: quickstart · coding agents · limits and network policy