> **[🇬🇧 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
```