agent-run Review 2026: Run Coding Agents in a Tiny Sandbox That Catches Mistakes Before They Spread

Coding agents are powerful but unpredictable. They can write brilliant code one moment and, if confused, attempt to delete your home directory the next. Most developers rely on version control and prayer. agent-run offers a more structured defense: a tiny, standalone binary that wraps your coding agent in a Bubblewrap sandbox, giving it read-only access to your entire system and write access only to the paths you explicitly allow.

The philosophy is pragmatic. agent-run isn’t trying to stop a determined attacker — its threat model is honest mistakes. An agent that misinterprets instructions and tries to rm -rf / or exfiltrate a file will hit a permissions wall. Everything outside your project stays safe while the agent operates freely inside it. At under 1MB with zero runtime dependencies (bwrap is embedded and exec’d via memfd), it adds essentially no overhead to your workflow.

What agent-run Does

agent-run is a single binary that acts as a wrapper for coding agents — specifically Claude Code, Codex, OpenCode, and pi. When you run agent-run claude instead of claude directly, the agent launches inside a Bubblewrap container. The host filesystem is mounted read-only by default. Only paths you explicitly configure in a TOML config file become read-write. Per-tool sections (tools.claude, tools.codex, etc.) control environment variable inheritance, network access, and mount points. The bwrap binary is compiled for the target platform and embedded directly into agent-run, so there’s nothing to install separately. It currently supports aarch64 and x86_64 Linux and requires unprivileged user namespaces.

Use Cases

• Safe exploration of unfamiliar codebases: Let a coding agent explore a new repository without worrying it might accidentally modify or delete files outside the project directory.
• Junior developer onboarding: Give new team members access to AI coding help without granting them unrestricted filesystem access — the sandbox contains both human and AI mistakes.
• CI/CD agent integration: Run coding agents in automated pipelines where a mistake shouldn’t have the power to affect the host build environment.
• Experimentation with agent configurations: Test new prompts, tools, or agent versions in an isolated environment before granting full access.

Key Features

Read-Only by Default

The entire host filesystem is mounted read-only. Only directories you explicitly list in the config file become writable. If an agent tries to touch anything outside your project, the kernel says no.

Embedded Bubblewrap, Zero Dependencies

The bwrap sandbox binary is compiled per-platform and embedded into agent-run. At runtime, it’s extracted and executed via memfd — no separate package to install, no apt install bubblewrap required.

Simple TOML Configuration

Each tool gets its own config section with straightforward options for environment variables, network access, and mount points. No complex YAML, no templating — just paths and booleans.

Per-Tool Isolation

Claude Code, Codex, OpenCode, and pi each get independent sandbox configurations. You can give Claude Code write access to /src while keeping Codex read-only everywhere — tailored permissions per agent.

Pricing

agent-run is free and open source under GPL-3.0. There are no paid tiers, no SaaS, and no accounts.

Common Questions

Is this a security tool against malicious code? No. agent-run’s threat model explicitly targets mistakes, not adversarial attacks. If a human is actively trying to use an agent to do harm, the sandbox can be bypassed. It’s designed for the far more common scenario: an agent misinterprets a prompt and does something destructive by accident.

Does this work on macOS or Windows? No. agent-run relies on Linux kernel features — Bubblewrap, user namespaces — and currently only supports aarch64 and x86_64 Linux. macOS and Windows users will need a Linux VM or Docker to use it.

Verdict

agent-run solves a specific, real concern with elegant minimalism. The “read-only by default” model is the right security posture for AI agents — it’s the principle of least privilege applied to an increasingly common workflow. The embedded bwrap design and sub-1MB footprint show genuine engineering care. The limitations are clear and mostly by design: Linux-only (because kernel features), mistake-focused (not malware-hardened), and early-stage (no config merging, limited arch support). For Linux developers who regularly use Claude Code or Codex on important projects, agent-run is a worthwhile addition to the toolkit — a small investment in configuration for meaningful protection against the most common agent failure mode: honest mistakes with destructive consequences.