asandbox/README.md

🇷🇺 Читать на русском → README.ru.md

asandbox

Run any CLI AI coding agent in Docker with host filesystem integration.
Works on macOS (Docker Desktop / OrbStack) and Linux.

Why

CLI agents (claude, codex, gemini, …) normally have full access to your machine.
asandbox runs them in an isolated Linux container:

• project directory is bind-mounted (same absolute path + /workspace);
• agent configs/auth (~/.claude, ~/.codex, …) stay on the host;
• no Docker socket — agents cannot escape via the Docker API;
• dropped capabilities, no-new-privileges, non-root user;
• CPU/RAM limits; optional --network none and --read-only.

Layout

Everything lives in one folder:

~/asandbox/   (or /Users/macbook/asandbox)
├── asandbox          # CLI program
├── Dockerfile
├── installagent      # agent installer (inside the sandbox)
├── entrypoint.sh
├── bashrc.asandbox
├── config/config.env
├── persist/          # installed agents (survives container restarts)
├── README.md         # this file (English)
└── README.ru.md      # Russian docs

Install

Requirements: Docker (OrbStack or Docker Desktop), bash.

cd ~/asandbox
./asandbox build
./asandbox doctor

# optional: put on PATH
ln -sf ~/asandbox/asandbox ~/.local/bin/asandbox

Usage

# interactive shell (cwd / git root mounted)
asandbox shell

# install agents inside the shell:
#   installagent list
#   installagent claude
#   installagent cursor
#   installagent antigravity
#   installagent opencode
#   installagent gemini
#   installagent all

# same from the host:
asandbox installagent list
asandbox installagent claude
asandbox installagent cursor
asandbox installagent antigravity
asandbox installagent opencode

# run agents
asandbox claude
asandbox run claude "explain this project"
asandbox codex
asandbox gemini
asandbox run aider
asandbox run antigravity
asandbox run cursor

# arbitrary command
asandbox run -- rg "TODO" -n
asandbox run -- python3 script.py

# offline + read-only rootfs
asandbox run --network none --read-only -- ls -la

# git over SSH
asandbox run --mount-ssh -- git pull

# other project directory
asandbox run -w ~/projects/foo claude

installagent

Available inside the sandbox shell and from the host (asandbox installagent …).

Name	Binary	Source
antigravity (agy)	agy	curl install script
cursor	agent	cursor.com/install
opencode	opencode	npm opencode-ai
claude	claude	npm @anthropic-ai/claude-code
gemini	gemini	npm @google/gemini-cli
codex	codex	npm @openai/codex
aider	aider	uv / pip
qwen	qwen	npm @qwen-code/qwen-code
amp, goose, continue	…	see installagent list

Installs go to ~/asandbox/persist/ and persist across container runs.

Filesystem

Host	Container
$WORKDIR (git root or cwd)	same path + /workspace
~/.claude, ~/.codex, …	/home/agent/... (rw if present)
~/.ssh	only with --mount-ssh (ro)
~/.gitconfig	ro by default

On Mac, path-preserving mounts (-v /Users/you/proj:/Users/you/proj) keep agent paths aligned with your IDE.

Security

Control	Status
Docker socket	not mounted
User	non-root (agent)
Capabilities	cap-drop ALL + minimal set
no-new-privileges	yes
Network	bridge by default (needed for APIs); none / host optional
Memory / CPU	4g / 4 cpus by default
Read-only root	--read-only

Note: bind-mounting the project gives the agent full rw on those files — that is the FS integration. Do not mount all of $HOME.

Config

~/asandbox/config/config.env — optional defaults.

Image sources live next to the CLI: Dockerfile, entrypoint.sh, installagent.

Environment variables

Forwarded automatically when set on the host:

ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, XAI_API_KEY, GITHUB_TOKEN, …

asandbox run --env MY_KEY=value claude
asandbox run --pass-env MY_KEY claude

Commands

Command	Description
asandbox build	Build the Docker image
asandbox doctor	Check environment
asandbox agents	List agent presets
asandbox installagent …	Install an agent in the sandbox
asandbox shell	bash in the sandbox
asandbox run …	Run agent / command
asandbox config init	Create config.env

Customize the image

Edit ~/asandbox/Dockerfile (or related scripts), then:

asandbox build --no-cache