173 lines
4.7 KiB
Markdown
173 lines
4.7 KiB
Markdown
> **[🇷🇺 Читать на русском → 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
|
|
```
|