Hep Agent Sandbox — AI skill for Claude Code

hep-agent-sandbox

A sandboxed VS Code dev container for AI coding agents (Claude Code, Codex) doing high-energy-physics work on a Mac. Agents run inside a Linux container that sees **only your research folder** (default `~/hep`), with the tools HEP work needs, instead of running directly on your Mac with access to everything.

**What you get**

• HEP tooling: Python 3.14 with ROOT 6.40, uproot, awkward, hist, iminuit, pyhepmc, jupyterlab (pinned via conda-forge); gcc/clang/cmake/gdb; a TeX Live subset (REVTeX, biber, LuaLaTeX, XeLaTeX); poppler for PDFs; Node.js; the Claude Code and Codex CLIs.
• Isolation: one bind mount of your research folder, with optional read-only dataset folders. No sudo, all Linux capabilities dropped, no Docker socket, no Mac credentials.
• GitHub over SSH: through your Mac's forwarded ssh-agent; your key never enters the container.
• Optional remote-access presets: none, Fermilab via Kerberos (host-only), or SSH-key clusters.
• A verification script: checks the toolchain and the isolation from inside the container.
• An agent policy: instructions every agent session loads: scientific safety, provenance, grid stewardship.
• An agent survey to improve the setup from your agents' actual experience.

Read [docs/DESIGN.md](docs/DESIGN.md) for the security model: what is enforced, what is only an instruction, and the risks that remain.

Quick start with Claude Code (guided)

You need Docker Desktop, VS Code with the Dev Containers extension, and Claude Code on the Mac; see the prerequisites linked below. In Claude Code on the Mac:

/plugin marketplace add S81D/hep-agent-sandbox
/plugin install hep-sandbox@hep-agent-sandbox

Then ask: *"Set up the HEP agent sandbox"* (or run `/hep-sandbox:setup-sandbox`).

The skill takes you through these steps, asking before anything that changes your Mac:

1. a read-only check of the Mac
2. a few decisions
3. generating the configuration
4. building and veri