From f62a25fbc4b4c5cc9ff6280d805ccbdbd302eb94 Mon Sep 17 00:00:00 2001 From: motyadev Date: Wed, 15 Jul 2026 13:17:19 +0000 Subject: [PATCH] readme --- README.md | 172 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.ru.md | 172 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 344 insertions(+) create mode 100644 README.md create mode 100644 README.ru.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..21cff7d --- /dev/null +++ b/README.md @@ -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 +``` diff --git a/README.ru.md b/README.ru.md new file mode 100644 index 0000000..fb3da85 --- /dev/null +++ b/README.ru.md @@ -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 +```