E2b Sandbox

E2B Sandbox

Use the bundled CLI to execute work in an isolated, session-scoped E2B sandbox. Keep the user's project as the current working directory and invoke the script by its absolute path so runtime state and downloaded artifacts stay with the project, not inside the installed skill.

Before execution

• E2B is a paid external cloud service. Treat code, prompts, uploaded files, environment values, and outputs as data sent to E2B.
• Do not upload secrets or private files unless the task requires it and the user has placed them in scope.
• Read the API key only from E2B_API_KEY. Never request that it be pasted into chat, pass it as a command argument, print it, or store it in project files.
• Prefer local tools when the user asked for local-only work. Use E2B when isolation, a disposable environment, an E2B template, or remote compute is materially useful.

Invocation

Let SKILL_ROOT mean the directory containing this SKILL.md; do not assume a fixed installation path.

Run the readiness check first:

uv run --script <SKILL_ROOT>/scripts/e2b_sandbox.py --json doctor

If uv is unavailable, run the script with a Python environment that has requirements.txt installed. Installing dependencies is a network-changing action; obtain any approval required by the host before doing it.

Use --json and inspect ok, status, artifacts, and warnings instead of scraping human output. Pick a short stable session name for related calls, such as the project name plus purpose.

uv run --script <SKILL_ROOT>/scripts/e2b_sandbox.py --json run --session analysis --file script.py --upload input.csv
uv run --script <SKILL_ROOT>/scripts/e2b_sandbox.py --json exec --session analysis --command "python -m pip list"

run and exec create a missing sandbox, reuse it on later calls, download new or changed files from /home/user/outputs, and pause it by default. Put user-facing deliverables in /home/user/outputs; uploaded files default to /home/user/uploads.

Operating rules

• Keep automatic pause enabled unless a running background process is genuinely needed. --keep-running can consume quota after the command returns.
• Use --package for explicit, task-required Python packages. Do not silently install unrelated packages.
• Use a new session or kill the old one before changing templates.
• Use status before assuming a saved remote sandbox still exists. The CLI recreates only sandboxes confirmed missing; it does not discard state on ordinary network failures.
• Use kill when state is no longer needed. Use pause when follow-up work should retain variables, files, or installed packages.
• Return downloaded artifacts to the user using the local paths in artifacts; never present /home/user/... as a usable local file.
• Keep output limits in place. Increase them only when the task truly needs the additional content.

For lifecycle, file mapping, networking, and command options, read references/commands.md.