Agentbox — песочница для кодирующих агентов

Идеального способа изолировать агентов (пока) не существует, но контейнеры — практичное начало.

Agentbox — это песочница для кодирующих агентов на базе Docker, изначально вдохновлённая Batrachian Toad, а теперь обобщённая для большего числа инструментов. Она предоставляет изолированную среду, которая хорошо работает с webterm для запуска нескольких сессий агентов.

Возможности

Контейнер по умолчанию предоставляет:

• Среду разработки: Debian Stable с распространёнными инструментами разработки
• Предустановленные кодирующие агенты: Copilot CLI, Codex, Pi
• Предустановленные CLI-инструменты: gh, Nushell, lazygit, killall
• Менеджеры пакетов: Homebrew и APT, а также uv и Bun; при сборке контейнера устанавливаются последние доступные пакеты без точного закрепления версий
• Дополнительные инструменты для агентов: установка toad, opencode, gemini и vibe через make -C ~ ...
• Управление сервисами: переключение Docker/SSH/RDP с помощью ENABLE_DOCKER, ENABLE_SSH и ENABLE_RDP
• Docker-in-Docker: доступен, когда контейнеры запускаются в привилегированном режиме
• Удалённый доступ: SSH (ENABLE_SSH=true) и поддержка mosh
• Начальная настройка рабочего пространства: встроенный каркас рабочего пространства и навыки агентов в /home/agent/workspace-skel

План развития

• Ограничения CPU и памяти (базовые ограничения ресурсов Docker)
• Варианты сетевой изоляции
• Другие методы изоляции (gVisor, Kata Containers и т. д.)

Конфигурация сервисов

Agentbox использует переменные окружения для управления тем, какие сервисы запускаются при старте контейнера:

• ENABLE_DOCKER=true — запустить демон Docker (для поддержки Docker-in-Docker)
• ENABLE_SSH=true — запустить SSH-сервер (порт 22)
• ENABLE_RDP=true — запустить RDP-сервер (порт 3389)
• AGENTBOX_ENVIRONMENT=cli|gui — маркер окружения, предоставляемый образом (cli для headless/CLI, gui для десктопных образов)

Поведение по умолчанию: все сервисы отключены, если не включены явно.

Примеры:

# По умолчанию — все сервисы отключены
docker run -d agentbox

# Включить только демон Docker
docker run -d -e ENABLE_DOCKER=true agentbox

# Включить Docker и SSH для разработки
docker run -d -e ENABLE_DOCKER=true -e ENABLE_SSH=true -p 22:22 agentbox

# Полноценный десктопный опыт со всеми сервисами (GUI-образ)
docker run -d -e ENABLE_DOCKER=true -e ENABLE_SSH=true -e ENABLE_RDP=true -p 22:22 -p 3389:3389 agentbox:gui

Быстрый старт

Установка дополнительных инструментов

Внутри контейнера пользователь agent поставляется с ~/Makefile, который может устанавливать дополнительный инструментарий.

Кодирующие агенты/CLI, которые можно установить через make -C ~ …:

• toad — устанавливает Batrachian Toad (через uv tool)
• opencode — устанавливает OpenCode (через Bun)
• gemini — устанавливает Gemini CLI (через Homebrew)
• vibe — устанавливает mistral-vibe (через uv tool)

Удобные цели:

• tools — устанавливает node, go, gemini, vibe
• node, go — устанавливают языковые тулчейны (предварительные требования для некоторых агентов)

Каркас рабочего пространства

Agentbox поставляется со встроенным каркасом проекта в /home/agent/workspace-skel.

Чтобы скопировать его в текущий /workspace без перезаписи существующих файлов:

make init-workspace

Подробности см. в docs/workspace-skeleton.md.

GUI-образ

GUI-сборка публикуется под тегом :gui (также <release>-gui) и включает XFCE, XRDP и VS Code.

Docker Compose

Рекомендуемый рабочий процесс:

make up
make enter-toad   # или: make enter-copilot
make down

Если нужны переопределения сервисов, создайте docker-compose.override.yml:

services:
  toad:
    environment:
      ENABLE_DOCKER: "true"
      ENABLE_SSH: "true"
  copilot:
    environment:
      ENABLE_DOCKER: "true"
      ENABLE_SSH: "true"

Затем выполните:

docker compose up -d

Прямое использование Docker

# Собрать headless-образ
docker build -t agentbox .

# Собрать GUI-образ
docker build -t agentbox:gui --target gui .

# Запустить контейнер с выбранными сервисами (GUI-образ)
docker run -d \
  --name agentbox \
  --privileged \
  -e ENABLE_DOCKER=true \
  -e ENABLE_SSH=true \
  -e ENABLE_RDP=true \
  -p 22:22 \
  -p 3389:3389 \
  -v $(pwd):/workspace \
  agentbox:gui

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

После подключения к контейнеру:

1. Установите Toad (если нужно):

make -C ~ toad

2. Запустите Toad:

toad

3. Или запустите с указанием конкретного каталога проекта:

toad /workspace

4. Или запустите сразу с агентом:

toad -a open-hands

Замечания по безопасности

• Управление сервисами: по умолчанию все сервисы (Docker, SSH, RDP) отключены. Явно включайте только то, что вам нужно, с помощью переменных окружения.
• Пароли по умолчанию слабые — смените их для использования в продакшене
• Контейнер должен работать в привилегированном режиме, чтобы Docker-in-Docker был доступен вашим агентам (это лучше, чем ничего)
• Рассмотрите использование SSH-ключей вместо аутентификации по паролю
• Для использования в продакшене рассмотрите отключение ненужных сервисов и смену учётных данных по умолчанию

Благодарности

Этот проект в общих чертах основан на моём старом rcarmo/docker-templates/desktop-chrome с обновлённым userland.

Лицензия

MIT