agent-run Review 2026: Run Coding Agents in a Sandbox Smaller Than a Megabyte

AI coding agents are powerful, but they’re also unpredictable. Give Claude Code or Codex CLI access to your filesystem, and there’s always the lingering fear that a hallucinated rm -rf or an overeager refactor might delete something it shouldn’t. agent-run tackles this problem with a refreshingly minimal approach: a single binary under one megabyte that wraps any coding agent inside a Bubblewrap sandbox. The host filesystem is mounted read-only by default, and the agent can only touch what you explicitly allow. No Docker daemon, no complex configuration, no runtime dependencies — just a tiny binary and a TOML file.

The project comes from the same school of thought as Bubblewrap itself: do one thing well, and do it with as little surface area as possible. agent-run embeds a pre-compiled bwrap binary for your platform and executes it at runtime via a memory file descriptor, so there’s literally nothing to install beyond the agent-run binary itself. For developers who want to let AI agents loose on their codebase without losing sleep, it’s an elegant safety net.

What agent-run Does

agent-run is a lightweight sandbox runner for AI coding agents. It supports four major agent CLIs — pi, opencode, codex, and claude — and runs them inside a Bubblewrap container where the host filesystem is read-only by default. You configure which directories the agent can write to via a simple TOML configuration file, organized into per-tool sections. The agent sees only what you’ve permitted, and any attempt to read from or write to unauthorized paths is blocked at the sandbox level. The bwrap binary itself is compiled for your target architecture and embedded directly into agent-run, so there are zero external dependencies.

Use Cases

Safe AI-assisted refactoring. You want an agent to refactor a sprawling codebase, but you don’t want it accidentally modifying configuration files, dotfiles, or system directories. agent-run gives the agent write access only to the project directory, while everything else — including your home folder — remains read-only or invisible. The agent can do its job, and you don’t have to audit every file it touched afterward.

Letting agents run tests without side effects. AI agents often need to install dependencies, run build steps, or execute test suites. With agent-run, you can grant write access to a dedicated build directory while keeping source files read-only. The agent can run npm install or pip install inside the sandbox without polluting your global environment.

Evaluating new agent tools safely. Before trusting a new coding agent with a real project, you can use agent-run to let it operate inside a throwaway sandbox. Mount a copy of your project, give the agent write access, and see what it does — all without risk to the original files.

CI/CD agent integration. In automated pipelines where AI agents review or modify code, agent-run provides an additional isolation layer beyond what CI containers already offer. If an agent goes rogue during an automated PR review, the sandbox contains the damage to the explicitly mounted workspace.

Key Features

Bubblewrap Sandbox

The core of agent-run is Bubblewrap (bwrap), a lightweight Linux sandboxing tool that uses user namespaces to create isolated environments. The host filesystem is mounted read-only inside the sandbox. Only paths you explicitly declare in the configuration file become writable. Network access can be disabled per-tool, and environment variables can be selectively inherited from the host. This isn’t a full virtual machine — it’s a namespace-based container, which means it starts instantly and adds negligible overhead.

Tiny Self-Contained Binary

agent-run ships as a single binary under 1 MB. The bwrap executable is compiled for the target platform (currently aarch64 and x86_64 Linux) and embedded directly into the agent-run binary. At runtime, agent-run extracts bwrap into a memory file descriptor and executes it — no filesystem writes, no separate installation step. The entire tool fits in a single curl download.

Per-Tool TOML Configuration

Configuration lives in a single TOML file with dedicated sections for each supported agent: [tools.pi], [tools.opencode], [tools.codex], and [tools.claude]. Each section controls environment variable inheritance, network access toggles, and mount points. You can lock down Claude Code to read-only everywhere except ./src, while giving Codex CLI different permissions entirely. The configuration model is deliberately simple — no inheritance chains, no merging rules, no surprises.

Mistake Containment, Not Malware Defense

agent-run’s threat model is explicitly scoped to agent mistakes, not adversarial attacks. It catches the rm -rf /home/user scenarios, the accidental config overwrites, and the well-intentioned but destructive refactors. It is not designed to defend against a determined attacker crafting a kernel exploit from inside the sandbox. This honesty about the threat model is refreshing and lets the tool stay minimal rather than accumulating layers of hardening that most users don’t need.

Broad Agent Compatibility

agent-run supports the four most prominent open-source and semi-open coding agents: pi (a lightweight coding agent), opencode (the successor to Open Interpreter), OpenAI’s Codex CLI, and Anthropic’s Claude Code. Each agent runs through its native CLI interface, so there’s no wrapper API to learn or adapter layer to maintain. If a new agent CLI emerges, adding support is straightforward.

Pricing

agent-run is free and open source under the GPL-3.0 license. There are no paid tiers, no hosted service, and no enterprise licensing. It’s a standalone tool you download and run locally. Contributions and forks are welcome under the terms of the GPL.

Common Questions

Does agent-run work on macOS or Windows? No. agent-run relies on Bubblewrap, which requires Linux user namespaces — a Linux kernel feature not available on macOS or Windows. You can run it inside a Linux VM on either platform, but there’s no native support. The project currently targets aarch64 and x86_64 Linux exclusively.

How does agent-run compare to Docker? Docker provides a full container runtime with image management, networking, and orchestration — and weighs hundreds of megabytes. agent-run is a single binary under 1 MB with zero runtime dependencies. If you just want to isolate a coding agent’s filesystem access, agent-run is dramatically simpler. If you need network isolation, multi-container orchestration, or cross-platform support, Docker is the better fit.

Can I use agent-run with custom or self-built agents? The current release supports pi, opencode, codex, and claude out of the box. Adding a custom agent would require modifying the source to add a new tool section, since the agent CLI commands are compiled in. The project is open source, so this is possible but not yet a configuration-only operation.

Verdict

agent-run solves a specific, narrow problem with impressive economy. In a world where “just use Docker” is the default answer to isolation questions, agent-run offers a radically simpler alternative: one binary, one config file, and the agent stays in its lane. The 1 MB footprint is almost absurdly small for what it does, and the embedded-bwrap approach eliminates the dependency headaches that plague most sandboxing tools.

The Linux-only limitation is real and excludes a large portion of developers who work on macOS. The threat model is explicitly scoped to mistakes rather than malicious code, which is honest but worth keeping in mind if you’re running untrusted third-party agents. The configuration model, while refreshingly simple, lacks some quality-of-life features like environment variable expansion inside mount paths.

For Linux-based developers who regularly use Claude Code, Codex CLI, or similar tools and want a lightweight safety net, agent-run is an excellent addition to the toolkit. It takes five minutes to set up and provides a meaningful layer of protection against the kind of mistakes that every AI coding agent will eventually make.

Overall: 7.6/10 — A minimal, elegant sandbox for AI coding agents. Essential for Linux developers who want peace of mind without Docker’s complexity.