Amazing Sandbox (asb)

Amazing Sandbox (AS) is for running various tools inside a Docker sandbox.

• 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 pass a custom Docker image via -i

Supported

• JavaScript/Typescript
  • npx
  • npm
  • yarn
  • pnpm - Use asb npx pnpm
  • bun
• Rust cargo and cargo-exec
• Ruby gem and gem-exec
• Python
  • pip
  • poetry
  • uv
  • uvx

Caches config of the following coding agents

The config 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. Open AI 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 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

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

To see the full usage

$ asb --help
asb is CLI tool for running tools inside Sandbox
See https://ashishb.net/programming/run-tools-inside-docker/ for reasoning behind this tool

Usage:
  asb [flags]
  asb [command]

Available Commands:
  bun         Run a bun command
  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
  help        Help about any command
  npm         Run an npm command
  npx         Run an npx command
  poetry      Run a poetry 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

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)
  -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-only (default true)

Use "asb [command] --help" for more information about a command.

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 sub-par.