motyadev/asandbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readme

Browse Source
This commit is contained in:
motyadev
2026-07-15 13:17:19 +00:00
parent 520276b676
commit f62a25fbc4
2 changed files with 344 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+172
View File
@@ -0,0 +1,172 @@
> **[🇷🇺 Читать на русском → 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
```
README.ru.md
+172
View File
@@ -0,0 +1,172 @@
> **[🇬🇧 Read in English → README.md](./README.md)**
# asandbox
Запуск любого CLI AI-агента в Docker с доступом к исходной файловой системе хоста.
Работает на **macOS** (Docker Desktop / OrbStack) и Linux.
## Зачем
CLI-агенты (`claude`, `codex`, `gemini`, …) имеют полный доступ к машине.
`asandbox` запускает их в изолированном Linux-контейнере:
- рабочая директория проекта **примонтирована** (тот же absolute path + `/workspace`);
- конфиги/авторизация агентов (`~/.claude`, `~/.codex`, …) сохраняются на хосте;
- **нет** Docker socket → агент не может сбежать через Docker API;
- dropped capabilities, `no-new-privileges`, non-root user;
- лимиты CPU/RAM; опции `--network none` и `--read-only`.
## Структура
Всё лежит в одной папке:
```
~/asandbox/ (или /Users/macbook/asandbox)
├── asandbox # программа (CLI)
├── Dockerfile
├── installagent # установщик агентов (внутри sandbox)
├── entrypoint.sh
├── bashrc.asandbox
├── config/config.env
├── persist/ # установленные агенты (живут между запусками)
├── README.md # документация на английском
└── README.ru.md # этот файл
```
## Установка
Требования: Docker (OrbStack или Docker Desktop), bash.
```bash
cd ~/asandbox
./asandbox build
./asandbox doctor
# опционально — в PATH:
ln -sf ~/asandbox/asandbox ~/.local/bin/asandbox
```
## Использование
```bash
# интерактивная оболочка (cwd / git-root смонтирован)
asandbox shell
# внутри shell — установка агентов:
# installagent list
# installagent claude
# installagent cursor
# installagent antigravity
# installagent opencode
# installagent gemini
# installagent all
# то же с хоста:
asandbox installagent list
asandbox installagent claude
asandbox installagent cursor
asandbox installagent antigravity
asandbox installagent opencode
# запуск агентов
asandbox claude
asandbox run claude "объясни структуру проекта"
asandbox codex
asandbox gemini
asandbox run aider
asandbox run antigravity
asandbox run cursor
# произвольная команда
asandbox run -- rg "TODO" -n
asandbox run -- python3 script.py
# offline + read-only rootfs
asandbox run --network none --read-only -- ls -la
# git по SSH
asandbox run --mount-ssh -- git pull
# другой каталог
asandbox run -w ~/projects/foo claude
```
## installagent
Команда доступна **внутри sandbox-оболочки** и с хоста (`asandbox installagent …`).
| Имя | Бинарь | Источник |
|-----|--------|----------|
| `antigravity` (`agy`) | `agy` | curl install.sh |
| `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` | … | см. `installagent list` |
Установки пишутся в `~/asandbox/persist/` и **сохраняются** между запусками контейнера.
## Файловая система
| Хост | Контейнер |
|------|-----------|
| `$WORKDIR` (git root или cwd) | **тот же путь** + `/workspace` |
| `~/.claude`, `~/.codex`, … | `/home/agent/...` (rw, если есть) |
| `~/.ssh` | только с `--mount-ssh` (ro) |
| `~/.gitconfig` | ro по умолчанию |
На Mac path-preserving mount (`-v /Users/you/proj:/Users/you/proj`) важен, чтобы пути в диффах/логах агента совпадали с IDE.
## Безопасность
| Защита | Статус |
|--------|--------|
| Docker socket | **не монтируется** |
| User | non-root (`agent`) |
| Capabilities | `cap-drop ALL` + минимальный набор |
| no-new-privileges | да |
| Network | `bridge` по умолчанию (нужен для API); `none` / `host` опционально |
| Memory / CPU | 4g / 4 cpus по умолчанию |
| Read-only root | `--read-only` |
Ограничения: bind-mount проекта даёт агенту полный rw к этим файлам — это и есть «интеграция с ФС». Не монтируйте `$HOME` целиком.
## Конфиг
`~/asandbox/config/config.env` — опциональные дефолты.
Источники образа рядом с CLI: `Dockerfile`, `entrypoint.sh`, `installagent`.
## Переменные окружения
Автоматически пробрасываются (если заданы на хосте):
`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
```
## Команды
| Команда | Описание |
|---------|----------|
| `asandbox build` | Собрать образ |
| `asandbox doctor` | Проверить окружение |
| `asandbox agents` | Список пресетов |
| `asandbox installagent …` | Установить агента в sandbox |
| `asandbox shell` | bash в sandbox |
| `asandbox run …` | Запуск агента/команды |
| `asandbox config init` | Создать config.env |
## Кастомизация образа
Отредактируйте `~/asandbox/Dockerfile` (или связанные скрипты), затем:
```bash
asandbox build --no-cache
```