sandbox-agent
Run agent CLIs (codex/copilot/opencode) inside a Podman container with full internet access but filesystem exposure limited to the repo root + explicit bind mounts.
When & Why to Use This Skill
The sandbox-agent skill provides a secure, containerized execution environment for AI agent CLIs such as Codex, Copilot, and OpenCode. By utilizing Podman, it creates a robust sandbox that allows agents full internet access for web research and data fetching while strictly limiting their filesystem visibility to the repository root and explicitly authorized bind mounts. This ensures a high level of security and data privacy when running autonomous agents on local machines.
Use Cases
- Secure Code Execution: Run autonomous coding agents on local projects while preventing them from accessing sensitive system files, SSH keys, or password stores.
- Isolated Web Research: Enable agents to perform extensive web searches and external API calls within a sandbox, ensuring any potential malicious downloads or exfiltration attempts are contained.
- Reproducible Agent Environments: Standardize the execution environment for AI agents across different development setups using Podman containers to ensure consistent behavior and safety constraints.
- Safe Testing of New Agents: Evaluate the capabilities of new or experimental AI agents in a restricted environment before granting them broader access to your development system.
| name | sandbox-agent |
|---|---|
| description | "Run agent CLIs (codex/copilot/opencode) inside a Podman container with full internet access but filesystem exposure limited to the repo root + explicit bind mounts." |
sandbox-agent
Use this when you want:
- Full egress/network for agent CLIs (web search, fetching, etc.)
- Tight filesystem boundaries via container bind mounts (repo root + explicit allowlist)
This repo contains a wrapper script intended to be installed as sandbox-agent.
Workflow
Build the image
From the repo root (this repository):
podman build -t localhost/sandbox-agent:latest -f Containerfile .
2. **Install the wrapper**
```bash
install -m 0755 sandbox-agent ~/.local/bin/sandbox-agent
- (Optional) Configure extra mounts
Create ~/.config/sandbox-agent/config.sh:
CODEX_CONTAINER_SANDBOX_IMAGE="localhost/sandbox-agent:latest"
# Extra read-only mounts (mapped under /home/codex/... if under $HOME)
CODEX_CONTAINER_SANDBOX_RO_MOUNTS=(
"$HOME/.local/bin"
)
# Extra read-write mounts
CODEX_CONTAINER_SANDBOX_RW_MOUNTS=(
"$HOME/.cache/uv"
"$HOME/tmp"
)
Login once inside the container
sandbox-agent --shell codex login
5. **Run the self-test (recommended)**
```bash
./selftest.sh
If this repo is vendored as a git submodule at ./sandbox-agent/ (for example in a dotfiles repo), either:
cd sandbox-agent && ./selftest.sh, or- run
./sandbox-agent/selftest.shfrom the parent repo root.
- Run an agent CLI
sandbox-agent codex exec "Summarize this repo"
Safety notes
- This wrapper runs with full networking. Anything mounted into the container can be exfiltrated.
- Keep mounts minimal; do not mount secrets, password stores, SSH keys, or large chunks of
$HOMEunless you intend to expose them.