agent-run
Run a coding agent in a sandboxed environment using a tiny standalone binary with simple TOML configuration.
agent-run
What is agent-run?
agent-run is a command-line tool that runs AI coding agents (like pi, opencode, codex, claude) in a sandboxed environment using bubblewrap. It provides a simple TOML-based configuration to control network access, environment variables, and mount points, keeping agents isolated from the host filesystem except for specified paths.
How to use agent-run?
- 1Install via Nix: nix run github:sin-ack/agent-run -- <command>
- 2Or via Mise: mise use github:sin-ack/agent-run@latest
- 3Or manually: download binary from releases, place in PATH, chmod +x
- 4Create a TOML config file at .agent-run/config.toml (or use default)
- 5Run: agent-run <agent> (e.g. agent-run claude)
agent-run Key Features
- Tiny standalone binary (<1MB) for GNU/Linux (aarch64 and x86_64)
- Simple TOML-based configuration with JSON schema support
- Sandboxed execution via embedded bwrap (unprivileged user namespaces)
- Supports multiple coding agents: pi, opencode, codex, claude
- Per-tool configurable mounts, environment variables, and network access
- Read-only host filesystem by default with optional writable mounts
agent-run Use Cases
- Run AI coding agents securely without permission prompts
- Isolate agents from non-project files to prevent accidental damage
- Test or develop agents in a controlled environment
- Sandbox agent operations while allowing access to specific directories
agent-run Pricing & Free Credits
agent-run currently operates on a Free model.
This tool is completely free to use
agent-run Pros & Cons
Pros
- Extremely lightweight and fast
- Simple configuration with good defaults
- Per-tool flexibility for mounts, env, network
- Open source and auditable
Cons
- Linux only (requires bwrap and unprivileged user namespaces)
- Not hardened against malicious code (read-only filesystem but sockets/network available)
- Limited to supported agents; custom agents require manual config
- No overlay or parallel agent support
What is agent-run best for?
- Developers using AI coding agents
- Those wanting simple sandboxing without heavy VMs
- Users annoyed by permission prompts
- Linux users seeking a lightweight isolation tool