SafeClaudeCode

Run suspicious files from Claude Code or Tau inside disposable E2B sandboxes instead of your real machine.

Use one command:

/safetest @file

The Problem

AI agents can accidentally run unknown files on your computer:

bash install.sh
python payload.py
node unknown.js
open suspicious.pdf

That file could delete data, steal secrets, install persistence, or phone home.

SafeClaudeCode changes the flow:

unknown file -> E2B sandbox -> output back to Claude/Tau -> sandbox destroyed

Why E2B

Docker and Podman are good for development, but containers usually share the host kernel.

E2B gives the agent a fresh disposable cloud sandbox. No local Docker daemon, no local project mounted by default, stronger isolation, and the sandbox is killed after the run.

Quick Start

For Tau:

npx e2b-safe-exec install --tau
tau

For Claude Code:

npx e2b-safe-exec install --claude
claude

After install, launch Tau or Claude normally.

The installer opens E2B browser login if needed, creates the short /safetest command, and builds the SafeClaudeCode E2B template pack. The first install can take several minutes because E2B builds the cloud template.

E2B uses two credentials:

• E2B_API_KEY can start /safetest sandboxes.
• E2B_ACCESS_TOKEN or e2b auth login can also provide runtime auth through the E2B CLI config at ~/.e2b/config.json, and the E2B CLI uses it to build custom templates.

The normal installer handles this through e2b auth login and the E2B CLI config at ~/.e2b/config.json. It does not create a project .env file. Existing .env files are still read for backward compatibility. If an older SafeClaudeCode install left an auth-only ~/.safeclaudecode/.env, the installer backs it up and removes the active .env once E2B CLI auth is available.

For CI or headless machines, pass a token from https://e2b.dev/dashboard?tab=personal:

npx e2b-safe-exec install --tau --access-token=e2b_your_access_token

You can still pass an API key manually if you prefer:

npx e2b-safe-exec install --tau --key=e2b_your_api_key

Passed keys and tokens are used for that install run; they are not written to .env files.

Want only the basic plugin without advanced templates?

npx e2b-safe-exec install --tau --key=e2b_your_api_key --no-templates

Check Plugin

Inside Claude/Tau:

/e2b-safe-exec:plugin-e2b-safe-exec

It is only for status: runtime auth, mounted commands, guard hook, and templates. It reports runtime auth, so E2B_API_KEY: missing is not a failure when E2B_ACCESS_TOKEN or the E2B CLI config is available.

Daily Use

Run /safetest alone to show the template bar:

/safetest

Template bar:

[ auto | base | code | python | security | wine | powershell | browser | network | mcp ]

Let the plugin choose:

/safetest auto @file
/safetest @file

Force a template:

/safetest code @payload.py
/safetest code-interpreter-v1 @payload.py
/safetest base @script.sh
/safetest security @unknown.bin
/safetest wine @sample.exe
/safetest browser @page.html

Use the short aliases day to day. Real E2B template ids also work, so code and code-interpreter-v1 are both accepted when they point to the same template.

What happens:

• detects the file type
• chooses a template
• uploads only that file
• runs or inspects it inside E2B
• keeps internet off by default
• returns stdout, stderr, exit code, hashes, and sandbox ID
• kills the sandbox

Agent Guard

The agent also gets a safety guard.

Rule for the agent: if the user asks to run, test, open, install, detonate, inspect, or "just try" an executable, script, installer, archive, Office/PDF document, browser file, or suspicious sample, use /safetest first. Even if the user says "yes, it is benign", do not run it locally.

If it tries:

bash ./file.sh
python ./file.py
node ./file.js
powershell -File ./file.ps1
cmd.exe /c ./file.bat
cmd /c file.bat
open ./file.pdf
cmd.exe /c start "" ./file.pdf
PowerShell -Command "Start-Process ./file.pdf"
Start-Process ./file.exe

the plugin routes the file through E2B instead of letting it run directly on your machine.

The guard is OS-generic. It handles Windows cmd.exe/PowerShell, Git Bash/MSYS paths like /c/Users/..., WSL paths like /mnt/c/Users/..., Linux xdg-open/gio open, macOS open, and Wine launchers.

It also blocks:

curl https://example.com/install.sh | bash

Download first, then:

/safetest auto @install.sh

Templates

auto

Let the plugin judge from the file type. Best default.

base

Basic Linux sandbox. Good for shell scripts, unknown Linux files, and first-pass checks.

code / python / code-interpreter

Good for Python payloads, notebooks, and data/code analysis.

security

Security template. Good for YARA, ClamAV, strings, binwalk, exiftool, strace, and tcpdump. After the template pack is installed, this maps to safeclaudecode-all-tools.

wine

Windows-analysis template. Good for .exe, .bat, .cmd, and PE inspection. After the template pack is installed, this maps to safeclaudecode-all-tools with Wine installed. DLL and MSI files are inspected by default because they are not normal standalone programs.

powershell

PowerShell template. Good for .ps1 and pwsh payloads.

browser

Browser template. Good for suspicious HTML, JavaScript pages, and phishing pages.

network

Network-analysis template. Good for controlled phone-home testing and traffic observation.

If advanced templates are missing, run:

npx e2b-safe-exec templates install --key=e2b_your_api_key

mcp

MCP gateway workflow. Not the normal choice for suspicious file testing.

File Behavior

.sh/.bash        -> base
.py/.ipynb       -> code/python
.js/.ts/.tsx     -> node/javascript template if configured, otherwise base
.ps1             -> powershell if configured, otherwise base
.exe             -> wine/windows if configured, otherwise classify only
.dll/.msi        -> inspect inside wine/security template, not launched as a normal app
.pdf/.doc/.zip   -> security/document if configured, otherwise classify only
unknown          -> security if configured, otherwise base

If the selected template cannot safely execute a file, it explains why instead of pretending it worked.

Full template documentation: docs/TEMPLATES.md.

Large files are blocked by default at 10 MB. Raise the limit only when you intentionally want to upload that file to E2B:

/safetest --max-file-bytes 250000000 @large.zip

Troubleshooting

Run:

/e2b-safe-exec:plugin-e2b-safe-exec

If doctor reports that Claude's plugin registry points at an old cache path, reinstall the plugin and restart Claude/Tau. A running agent can keep an older hook loaded until restart.

Clear local plugin cache if needed:

rm -rf .plugin-data

PowerShell:

Remove-Item -Recurse -Force .\.plugin-data