> **[🇷🇺 Читать на русском → README.ru.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.

```bash
cd ~/asandbox
./asandbox build
./asandbox doctor

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

## Usage

```bash
# 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`, …

```bash
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:

```bash
asandbox build --no-cache
```