gbox

gbox — это самостоятельная песочница для агентов ИИ, позволяющая выполнять команды, просматривать веб-страницы и использовать настольные/мобильные устройства. Подробности см. в разделе «Функции».

Этот проект основан на технологии gru.ai. Он был протестирован на более чем 100000 агентских заданиях.

Поскольку MCP становится все более популярным, мы также внедрили сервер MCP, чтобы упростить его прямую интеграцию в клиент MCP, такой как Claude Desktop/Cursor.

Функции

1. Терминал

   • Выполнить любую команду Linux

   • Выполнять скрипты Python напрямую

   • Поделиться сеансом между вызовами [в разработке]

2. Файл

   • Монтировать папки хост-машины в песочницу

   • Доступ к файлам песочницы через http-ссылки

   • Чтение содержимого файла в мультимодальном режиме

   • Запись/перезапись файлов

   • Редактировать файлы [в разработке]

   • Поиск файлов [в разработке]

3. Браузер

   • Откройте любой URL, верните содержимое в мультимодальном режиме

   • Загрузите с любого URL-адреса [в разработке]

   • Управляйте браузером по инструкции

   • Человеческое господство [недоразвитие]

4. HTTP-сервер

   • Запуск http-сервиса в любой папке по требованию [в стадии разработки]

5. SDK

   • Python SDK: Установка с помощью pip install pygbox . Подробности см. в PyPI .

   • Машинописный SDK

6. МКП

   • Стандартная поддержка MCP

   • Интеграция рабочего стола и курсора Claude

Related MCP server: sandbox-mcp

Использовать gbox как SDK

Python-SDK

pip install pygbox

Документация по Python SDK

Машинописный SDK

npm install @gru/gbox

Документация по TypeScript SDK

Использовать gbox как CLI

Установка

Системные требования

• macOS 10.15 или более поздняя версия

• Рабочий стол Docker для Mac

• Домашнее пиво

Примечание: поддержка других платформ (Linux, Windows) появится в ближайшее время.

Этапы установки

# Install via Homebrew
brew tap babelcloud/gru && brew install gbox

# Initialize environment
gbox setup

# Export MCP config and merge into Claude Desktop
gbox mcp export --merge-to claude
# or gbox mcp export --merge-to cursor

# Restart Claude Desktop

Шаги обновления

# Update gbox to the latest version
brew update && brew upgrade gbox

# Update the environment
gbox setup

# Export and merge latest MCP config into Claude Desktop
gbox mcp export --merge-to claude
# or gbox mcp export --merge-to cursor

# Restart Claude Desktop

Использование командной строки

Проект предоставляет инструмент командной строки gbox для управления контейнерами-песочницами:

# Cluster management
gbox cluster setup    # Setup cluster environment
gbox cluster cleanup  # Cleanup cluster environment

# Container management
gbox box create --image python:3.9 --env "DEBUG=true" -w /app -v /host/path:/app   # Create container
gbox box list                                                                      # List containers
gbox box start <box-id>                                                            # Start container
gbox box stop <box-id>                                                             # Stop container
gbox box delete <box-id>                                                           # Delete container
gbox box exec <box-id> -- python -c "print('Hello')"                               # Execute command
gbox box inspect <box-id>                                                          # Inspect container

# MCP configuration
gbox mcp export                          # Export MCP configuration
gbox mcp export --merge-to claude        # Export and merge into Claude Desktop config
gbox mcp export --dry-run                # Preview merge result without applying changes

Крепления для громкости

Команда gbox box create поддерживает монтирование томов, совместимых с Docker, с использованием флага -v или --volume . Это позволяет вам обмениваться файлами и каталогами между вашей хост-системой и контейнерами sandbox.

Синтаксис монтирования тома имеет следующий формат:

-v /host/path:/container/path[:ro][:propagation]

Где:

• /host/path : Путь к файлу или каталогу в вашей хост-системе.

• /container/path : Путь, по которому файл или каталог будет смонтирован в контейнере.

• ro (необязательно): делает монтирование доступным только для чтения

• propagation (необязательно): устанавливает режим распространения монтирования (частный, rprivate, общий, rshared, подчиненный, rslave)

Примеры:

# Basic bind mount
gbox box create -v /data:/data --image python:3.9

# Read-only bind mount
gbox box create -v /data:/data:ro

# Multiple bind mounts
gbox box create \
  -v /config:/etc/myapp \
  -v /data:/var/lib/myapp:ro \
  -v /logs:/var/log/myapp:ro:rprivate \
  --image python:3.9

Примечание: Путь к хосту должен существовать до создания контейнера. Путь к контейнеру будет создан автоматически, если он не существует.

Варианты использования MCP

Ваш клиент ИИ, такой как Claude Desktop, может использовать gbox MCP для достижения лучших результатов, например

1. Создание диаграмм

Сгенерируйте диаграммы цен на акции Tesla: https://claude.ai/share/34de8ca3-4e04-441b-9e79-5875fa9fc97a

2. Создание PDF-файлов

Сгенерируйте PDF-файл с последними новостями об ИИ: https://claude.ai/share/84600933-dcf2-44be-a2fd-7f49540db57a

3. Анализ и расчет

Проанализируйте и сравните рыночную капитализацию Nvidia/Tesla: https://claude.ai/share/70c335b7-9fff-4ee7-8459-e6b7462d8994

4. Обработка локальных файлов

Найдите изображения в папке загрузки и сожмите их в zip-архив. https://claude.ai/share/f8c4c617-9b32-4062-a8e2-2ab33ef46f42

5. Выполнение произвольных задач

Скачать видео с YouTube: https://claude.ai/share/c2ab6bcb-7032-489f-87d5-cc38f72c2ca9

Разработать gbox

Предпосылки

• Перейти к версии 1.21 или более поздней

• Рабочий стол Docker

• Делать

• pnpm (через corepack)

• Node.js 16.13 или более поздняя версия

Строить

# Build all components
make build

# Create distribution package
make dist

Запуск услуг

# API Server
make -C packages/api-server dev

# MCP Server
cd packages/mcp-server && pnpm dev

# MCP Inspector
cd packages/mcp-server && pnpm inspect

Внося вклад

Мы приветствуем вклады! Пожалуйста, не стесняйтесь отправлять запрос на извлечение. Для крупных изменений, пожалуйста, сначала откройте тему, чтобы обсудить, что вы хотели бы изменить.

1. Форк репозитория

2. Создайте ветку функций ( git checkout -b username/feature-name )

3. Зафиксируйте свои изменения ( git commit -m 'Add some feature' )

4. Отправьте изменения в ветку ( git push origin username/feature-name )

5. Открыть запрос на извлечение

Что нужно знать о локальной разработке и отладке

Как запустить gbox в среде разработки вместо установленной в системе

1. Остановите установленный gbox с помощью gbox cleanup . Это остановит сервер api, чтобы вы могли запустить сервер api в среде разработки.

2. Выполните make api-dev в корне проекта.

3. Выполните ./gbox box list — это команда, запускаемая из вашей среды разработки.

Как подключить MCP-клиент, такой как Claude Desktop, к MCP-серверу в среде разработки

1. Выполните make mcp-dev в корне проекта.

2. Выполнить ./gbox mcp export --merge-to claude

Как открыть MCP Inspect

1. Выполните make mcp-inspect в корне проекта.

2. Щелкните ссылку, возвращенную в терминале.

Как создать и использовать образ в среде разработки

1. Выполните make build-image-python в корне проекта, чтобы собрать образ Python, или make build-images , чтобы собрать все образы.

2. При необходимости измените имя образа (например, make build-image-typescript для образа TypeScript).

3. Возможно, вам придется удалить текущие песочницы, чтобы новый образ вступил в силу ./gbox box delete --all

Почему клиент MCP по-прежнему получает старый контент MCP?

1. После изменения конфигурации MCP, например определений инструментов, необходимо запустить make build , чтобы обновить файл dist/index.js .

2. Вам также может потребоваться выполнить ./gbox mcp export --merge-to claude

Лицензия

Данный проект лицензирован в соответствии с лицензией Apache License 2.0 — подробности см. в файле LICENSE .