# E2b Sandbox

> Run Python or shell commands in a stateful E2B cloud sandbox, including isolated execution, package installation, file upload/download, and sandbox lifecycle control. Use when the user asks for E2B, cloud-isolated execution, or running untrusted/generated code away from the local machine; do not use when they require local-only processing or their data must not leave the machine.

- Skill: `sl251/e2b-sandbox` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add sl251/e2b-sandbox`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sl251/e2b-sandbox/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: sl251 (https://skillmd.com/u/sl251)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sl251/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:

```text
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.

```text
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](references/commands.md).