@aurbi/coder

Run coding agents in a sandboxed environment using fuse-overlayfs and bubblewrap. The agent gets a copy-on-write overlay of your filesystem — it can read everything but only writes to the overlay (or explicitly passed-through directories like your project dir). Sensitive directories like ~/.ssh and ~/.gnupg are hidden.

Platform

Linux only. The underlying tools (fuse-overlayfs, bubblewrap) are Linux-specific. WSL may work if the dependencies are installed, but is not officially supported.

System Dependencies

These must be installed on your system before using coder:

• fuse-overlayfs — unprivileged FUSE overlay filesystem
• bubblewrap (bwrap) — unprivileged sandboxing
• fusermount3 — FUSE unmount utility (usually comes with fuse3)

On Arch Linux:

pacman -S fuse-overlayfs bubblewrap fuse3

On Debian/Ubuntu:

apt install fuse-overlayfs bubblewrap fuse3

On Fedora:

dnf install fuse-overlayfs bubblewrap fuse3

Install

npm i -g @aurbi/coder

Or run without installing:

npx @aurbi/coder

Usage

coder [-p project-dir] [-a agent] [-o overlay] [-- agent args...]

Options

| Flag | Description | Default | |------|-------------|---------| | -p DIR | Project directory | $PWD | | -a CMD | Agent command | $CODER_AGENT or claude | | -o MODE | Overlay mode (see below) | ephemeral | | -h | Show help | |

Overlay Modes

• (omitted) — ephemeral overlay, gone on exit
• project — persistent per-project overlay stored in ~/.local/share/coder/<mangled-path>/
• NAME — persistent overlay with an explicit name

Environment Variables

| Variable | Description | |----------|-------------| | CODER_AGENT | Default agent command (e.g., claude, pi) | | CODER_AGENT_ARGS | Default agent arguments, prepended to any -- args | | CODER_BLOCKS | Space-separated dirs to hide from the agent (default: ~/.ssh ~/.gnupg) | | CODER_BINDS | Space-separated dirs/files to bind read-write, bypassing the overlay. Single path (~/.claude) binds as-is; colon pair (~/.pi/.gitconfig:~/.gitconfig) binds host source to sandbox destination. |

Examples

# Run claude in current directory with ephemeral overlay
coder

# Use a different agent
coder -a pi

# Persistent per-project overlay
coder -o project

# Named overlay, specific project, extra agent args
coder -p ~/code/app -o myproject -- --verbose

How It Works

1. Creates a fuse-overlayfs overlay with / as the lower (read-only) layer
2. Launches bubblewrap (bwrap) to pivot into the overlay as root filesystem
3. Bind-mounts your project directory, ~/.cache, and other essential dirs as read-write passthroughs (plus any entries in CODER_BINDS)
4. Masks sensitive directories (~/.ssh, ~/.gnupg, or whatever is in CODER_BLOCKS) with empty tmpfs mounts
5. Runs your agent inside the sandbox
6. Cleans up the overlay on exit

License

MIT