173 lines
6.0 KiB
Markdown
173 lines
6.0 KiB
Markdown
> **[🇬🇧 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
|
||
```
|