Python Sandbox

A Claude Code plugin that runs any Python library task in an isolated, throwaway environment — no install, no pollution of your Python, and your secrets (~/.aws, ~/.ssh, ~/.midway, everything in $HOME) hidden from whatever package gets pulled in.

Describe a task in natural language; Claude writes a self-contained PEP 723 script, runs it in a disposable sandbox with exactly the libraries it needs, and hands back the result. Only your current working directory is exposed (read-write, so outputs land in the project) — nothing else.

Author: hung-phan

Install

Register as a plugin marketplace, then install:

/plugin marketplace add hung-phan/python-sandbox
/plugin install python-sandbox@python-sandbox

Local install (for development)

claude plugin marketplace add ./
claude plugin install python-sandbox@python-sandbox

Prerequisites

The skill picks the fastest working isolation engine at runtime (scripts/detect.sh):

Engine	Needs	Notes
bwrap (bubblewrap)	Linux + host uv on PATH	Fastest; drives the host uv directly. Linux-only.
docker	reachable Docker daemon	Portable. Ships its own uv/Python in the image — no host uv needed.
podman	working rootless podman	Daemonless Docker alternative. No host uv needed.

If none is available, the skill refuses to run unisolated and prints OS-aware install/enable guidance (scripts/suggest.sh). On macOS use Docker Desktop or Podman (bwrap is Linux-only).

How to Use

The plugin exposes one slash command: /python-sandbox. It is the front door — describe a Python-library task and it runs it in a sandbox.

/python-sandbox shuffle this array with numpy and write it back
/python-sandbox parse sales.csv with pandas and give me monthly totals
/python-sandbox resize every image in ./photos to 800px wide
/python-sandbox serve this directory on port 8000

You can also just describe a task that needs a Python library and wants it run (not merely explained) — the skill activates on its own.

Not for: explaining code, writing a script for you to run yourself, or non-Python work.

What each run guarantees

Every run happens inside an isolated engine that:

• hides your home dir — ~/.aws, ~/.ssh, ~/.midway and everything else in $HOME are invisible to the code;
• exposes only the current working directory, read-write, so outputs land in the project;
• installs packages into a throwaway env — your global/project Python is never touched.

The workflow

1. Detect the engine (scripts/detect.sh).
2. Write a PEP 723 script into .python-sandbox/<timestamp>-<slug>.py, with all config (dependencies, mounts, network, ports) in a single inline [tool.python-sandbox] table.
3. Show, then run — the sandbox is the safety layer, so ordinary runs (compute, workspace file I/O, :ro mounts, network) just execute. Claude pauses for approval only when a run crosses a real boundary (mounting your home/secrets, a read-write mount outside the workspace, or no isolation engine available).
4. Report the result and name any files written.

Example script

# /// script
# [tool.python-sandbox]
# dependencies = ["pandas"]
# mounts = ["/data/inputs:ro", "./out"]   # :ro = read-only; rw dirs auto-created
# net = "off"                             # pure local compute — safer
# publish = [8000]                        # expose TCP ports (needs net on)
# ///
import pandas as pd
# ... task ...

Precedence: command-line flags > inline [tool.python-sandbox] > defaults (net defaults to on).

Ephemeral vs warm sessions

• Ephemeral (default): one-off tasks. Unlimited cheap runs, auto-cleanup, nothing persists.
• Warm session (opt-in, docker/podman): keeps packages/services/data loaded across many tasks. Use for heavy installs, an interactive kernel, or a running service.

# Ephemeral
bash scripts/run.sh --net off .python-sandbox/task.py

# Warm session
bash scripts/session.sh start --net on --publish 8000   # prints a session id
bash scripts/session.sh run   .python-sandbox/serve.py
bash scripts/session.sh stop

Containers never leak: bwrap self-cleans via --die-with-parent; session.sh owns three reaper triggers for docker/podman — explicit stop, an idle TTL (default 30m), and a startup sweep that reaps stale/orphaned containers.

Repo Layout

skills/
└── python-sandbox/
    ├── SKILL.md                    # the only skill exposed to Claude
    └── scripts/
        ├── detect.sh               # engine detection ladder (bwrap → docker → podman → none)
        ├── run.sh                  # ephemeral runner (--net, --mount, --publish)
        ├── session.sh              # warm docker/podman session lifecycle + reaper
        ├── parse_meta.py           # reads the inline [tool.python-sandbox] table (stdlib tomllib)
        ├── suggest.sh              # OS-aware guidance when no engine is available
        └── tests/
            └── run_tests.sh        # test suite — run it to verify the skill
.claude-plugin/                     # plugin + marketplace metadata

Verify

Run the bundled test suite — it exercises the detection ladder, ephemeral runs on every engine that works on this box (compute, file-write, isolation wall, net on/off, mounts, inline config), and the docker reaper:

bash skills/python-sandbox/scripts/tests/run_tests.sh

Tests auto-skip engines that aren't available (e.g. bwrap on macOS, docker when the daemon is down), so a partial-engine box still reports a clean pass.

Philosophy

Run untrusted code as if it were untrusted.

Third-party packages run with your privileges by default — they can read your credentials, SSH keys, and cloud config the moment you pip install and import them. This skill inverts that: the sandbox is the default, the workspace is the only thing exposed, and widening the blast radius (mounting secrets, writing outside the workspace, running with no isolation at all) always requires an explicit, visible decision.