asandbox/README.ru.md

🇬🇧 Read in English → 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.

cd ~/asandbox
./asandbox build
./asandbox doctor

# опционально — в PATH:
ln -sf ~/asandbox/asandbox ~/.local/bin/asandbox

Использование

# интерактивная оболочка (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, …

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 (или связанные скрипты), затем:

asandbox build --no-cache