A minimal sandbox wrapper for running commands in an isolated environment. It is ideal to isolate coding agents or testing untrusted Windows software under Wine.
The core idea is to provide a simple way to restrict processes to their own directory without the overhead of starting containers or creating new user accounts.
It is particularly well-suited for isolating agents like (pi-agent) into individual directories, preventing them from interfering with the rest of your private files.
The tool uses a multi-profile approach. It is designed to be minimal and follows the KISS principle. When starting a new box, it draws a shield emoji (🛡️) into your prompt to indicate that you're sandboxed.
Boxes run in their own PID namespace, so ps, kill and pkill inside the box can never see or reach host processes.
You will need bwrap (bubblewrap) installed, which is available in most common distributions or via your package manager.
curl -fsSL https://raw.githubusercontent.com/shagu/box/refs/heads/master/install.sh | shCopy box to /usr/bin/box and the config directory to ~/.config/box.
Run box to use the default profile, or box wine to use the Wine profile.
The example configurations include:
| Profile | Description |
|---|---|
| default | Basic sandbox with bash configuration |
| pi | Configuration for the pi agent |
| wine | Environment for running Windows software via Wine |