Amazing Sandbox (asb)

Amazing Sandbox (AS) is for running various tools inside

graph TD
    AS[Amazing Sandbox] -->|Default| D[<a href='https://ashishb.net/programming/docker-101/'>Docker-based Sandbox</a>]
    AS -->|Mac OS| S[<a href='https://igorstechnoclub.com/sandbox-exec/'>Seatbelt-based Sandbox</a>]
    AS -->|GNU/Linux| B[<a href='https://github.com/containers/bubblewrap'>Bubblewrap Sandbox</a>]

• Prevents malicious packages from having full disk access and stealing data
• Prevents AI agents from mistakenly deleting all files on your disk
• Optionally, run packages like linters air-gapped (no internet access) as well

Features

Default config

• Give Read-write access to the current directory
• Network access
• Load .env file from the current directory
• Cache various build steps using Docker
• Give Read-write access to any explicitly referenced files via CLI arguments

Configurable via CLI parameters

• Disable read access to the current and referenced directories via -x
• Provide Read-only access to the referenced directories via -r
• Disable network access - via -n
• Disable .env file loading via --load-env=false
• Add ability to pass a custom Docker image via -i

Supported

• Python
  • python
  • pip
  • poetry
  • uv
  • uvx
• JavaScript/Typescript
  • npx
  • npm
  • yarn
  • pnpm
  • bun
• Go go-exec
• Rust cargo and cargo-exec
• Ruby gem and gem-exec
• Haskell cabal and cabal-exec
• Zig zig

Caches config of the following coding agents

The configuration of the following coding agents is mapped to the corresponding directories in your home directory, so they will work seamlessly inside the sandbox without needing to re-authenticate or re-configure them.

1. Claude code
2. OpenAI Codex
3. Google Gemini CLI

Installation

$ go install github.com/ashishb/amazing-sandbox/src/asb/cmd/asb@latest
...

Or download a binary from the releases page

Usage

Run yarn with full access to current directory + a cache directory but no access to full disk

$ asb yarn install
...

Run HTML linter inside the sandbox with -n, that is, no Internet access

$ asb -n npx htmlhint
...  

Run yamllint inside the sandbox

$ asb uvx yamllint -d <path-to-dir-containing-yaml-files-to-lint>
...  

Run Claude code against the current directory

$ asb npx @anthropic-ai/claude-code
...  

Run Open AI Codex against the directory "~/src/repo1"

$ asb -d ~/src/repo1 npx @openai/codex
...

Run Google Gemini CLI inside the sandbox

$ asb npx @google/gemini-cli@latest
...

Run fd tool inside the sandbox with no Internet access (air-gapped)

$ asb cargo install fd-find  # One time install
...
$ asb  -n cargo-exec fd '.*.go'
...

Run hadolint (Haskell-based Dockerfile linter) inside the sandbox

$ asb cabal update && asb cabal install hadolint  # One time install
...
$ asb -n cabal-exec hadolint Dockerfile
...

Run acoustid-index build using Zig inside the sandbox

$ git clone https://github.com/acoustid/acoustid-index.git
...
$ cd acoustid-index
$ asb zig build
...

Run Grok Build inside it

$ asb bash
<inside the sandboxed shell>
# One-time setup
$ apt-get update -y
$ apt-get install -y curl
$ curl -fsSL https://x.ai/cli/install.sh | bash
# Do this to run it from now on
$ /root/.grok/bin/grok # To start it

To see the full usage

asb is CLI tool for running tools inside Sandbox
See https://ashishb.net/programming/amazing-sandbox/ for reasoning behind this tool

$ asb --help
Usage:
  asb [flags]
  asb [command]

Available Commands:
  bun         Run a bun command
  cabal       Run a Haskell cabal command
  cabal-exec  Run a Haskell-based binary already installed inside sandbox
  cargo       Run a cargo command
  cargo-exec  Run a Rust-based binary package already installed inside sandbox
  completion  Generate the autocompletion script for the specified shell
  gem         Run a Ruby gem-based CLI tool
  go-exec     Run a Go-based binary package using go run
  help        Help about any command
  node        Run a node command
  npm         Run an npm command
  npx         Run an npx command
  pip         Install Python packages using pip
  pip-exec    Run a Python-based package already installed inside sandbox
  pnpm        Run a pnpm command
  poetry      Run a poetry command
  python      Run a python command
  uv          Run a uv command
  uvx         Run a Python-based package already installed inside sandbox using uvx
  version     Display asb version
  yarn        Run a yarn command
  zig         Run a Zig command

Flags:
  -i, --custom-docker-image string   Use a custom Docker image for the sandbox
  -d, --directory string             Working directory for this command (default "<current directory>")
  -h, --help                         help for asb
  -e, --load-env                     Load .env file from working directory (default true)
      --mode string                  Sandbox mode to use (docker or native) (default "docker")
  -m, --mount-ro stringArray         Mount a directory as read-only inside the sandbox (can be specified multiple times)
  -x, --no-disk-access               Disable disk access inside the sandbox
  -n, --no-network                   Disable network access inside the sandbox
  -r, --read-only                    Load working directory and referenced directories as read-only
  -w, --read-write                   Load working directory and referenced directories as read-write (default true)

How I use it

For interactive shells, one can use bash aliases, for example, alias htmlhint=asb -n npx htmlhint. However, this does not work for non-interactive shells, for example, inside Makefile. So, I prefer creating ~/.local/bin which contains htmlhint file containing asb npx htmlhint "$@" and add .local/bin to the $PATH in ~/.bash_profile via export PATH=$PATH:$HOME/.local/bin.

FAQ

1. Why not use bubblewrap?
   It only supports GNU/Linux.
   Further, the developer experience for trying to run a simple tool like htmlhint or yamllint is subpar.

2. Why not use Firejail?
   No support for Mac OS or Windows.
   Further, the developer experience for trying to run a simple tool like htmlhint or yamllint is subpar.

3. Why not use sandbox-exec on Mac OS?
   sandbox-exec is deprecated. But if you want, you can use asb to use sandbox-exec/bubblewrap via `asb --mode=native)

4. Why not use ai-jail? ai-jail uses OS-level sandboxing via bwrap on Linux and the deprecated sandbox-exec on macOS.
   It has no Windows support.
   In contrast, asb uses Docker, which works consistently across Linux, macOS, and Windows.

5. Why not use drop?
   drop uses Linux mount namespaces for sandboxing and only supports Linux.
   In contrast, asb uses Docker, which works consistently across Linux, macOS, and Windows.

6. I heard that Docker is not a security boundary?
   Containers aren't as strong a security boundary as VMs; however, this means that a successful attack now requires infection of the container AND a concurrent container-escape vulnerability. That's a really high bar; someone would need to burn a 0-day on that. Taken from here

7. I want to use a custom rootless image or a different version of Python instead of the default images?
   You can provide any custom image via -i CLI parameter.

   $ asb -i astral/uv:python3.12-bookworm-slim python --version
   Python 3.12.12
   $ asb -i astral/uv:python3.14-bookworm-slim python --version
   Python 3.14.2