SPACE: песочница для агентного кода на Firecracker

О проекте

SPACE (Sandboxed Platform for Agentic Code Execution — изолированная платформа для агентного выполнения кода) — это платформа-песочница для запуска кода в изолированных микровиртуальных машинах Firecracker. Приложения используют её HTTP API для создания Linux-окружений, выполнения команд, сбора вывода и управления жизненным циклом песочниц.

Используйте SPACE в тех случаях, когда вашему приложению нужна отдельная среда выполнения — для агента, пользовательского рабочего пространства или задачи запуска кода. Ваше приложение решает, что запускать и какие результаты сохранять; SPACE управляет песочницей, её процессами и соединением, по которому передаётся вывод команд.

Как это работает

Шаблон (template) задаёт начальное окружение. Песочница (sandbox) — это экземпляр этого окружения с собственной виртуальной машиной и доступной для записи файловой системой; в одной песочнице может выполняться несколько команд.

Ваше приложение
    |
    +-- Создать песочницу из шаблона --> Ждать готовности
    |
    +-- Создать командную сессию ------> Подключиться для запуска процесса
    |                                    Читать вывод и результат завершения
    |
    +-- Сохранить, приостановить или заморозить --> Разбудить при необходимости
    |
    +-- Удалить песочницу

Изменения жизненного цикла песочницы выполняются асинхронно: API возвращает идентификатор операции, который нужно периодически опрашивать до её завершения. Вывод команд передаётся через отдельное соединение уровня данных (data-plane) с использованием токена привязки, привязанного к сессии.

Начало работы

Следуйте руководству Установка и настройка, чтобы развернуть SPACE в локальном кластере Kind и пройти аутентификацию. Затем обратитесь к разделу Первая песочница, чтобы запустить команду и получить её вывод. Руководство по установке ориентировано на Kubernetes; в руководстве по архитектуре также объясняется, как SPACE может работать без него.

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

Актуальные Руководство и Справочник по API доступны онлайн и автоматически обновляются после принятия изменений. Ссылки ниже ведут к исходной документации в репозитории.

Раздел Что вы узнаете

Раздел	Что вы узнаете
Версионирование и совместимость	Процесс выпуска релизов, поддерживаемые гостевые системы, стабильность сервиса, требования к обновлению и откату.
Архитектура	Как соотносятся шаблоны, песочницы, процессы, сессии и операции; что сохраняется при приостановке и заморозке; как взаимодействуют сервисы.
Установка и настройка	Требования к хосту, локальное развёртывание в Kind, настройки по умолчанию, аутентификация, проверка и удаление.
CLI оператора	Доступ к API, проброс портов, `space-admin-cli login`, узлы, тёплые пулы (warm pools) и сборка системных шаблонов.
Первая песочница	Полный рабочий сценарий с API, настройка команд, обработка вывода, инспекция и удаление.
Обёртка совместимости E2B	Настройка ECW, создание ключа API совместимости, использование протестированного Python SDK E2B, поддерживаемое поведение и ограничения.
Справочник по API	Эндпоинты, поля запросов и ответов, примеры.
Устранение неполадок	Локальная установка, аутентификация, операции жизненного цикла, потоки команд и безопасные повторные попытки.
Профили исходящего трафика оператора	Настройка именованных дополнений политики для федеративного создания через native и ECW.
Наблюдаемость	Возможности сборки телеметрии, контракт выбора Rust/Go и неизменённые настройки образов по умолчанию.
Тёплые пулы	Поддержание загруженных песочниц в готовности на Kubernetes, чтобы при создании пропустить холодную загрузку.
Базовые снимки	Восстановление песочниц из снимка на одном узле, опционально с тёплым пулом узлов.

Версионирование и совместимость

Процесс выпуска релизов, поддерживаемые гостевые системы, стабильность сервиса, требования к обновлению и откату.

Архитектура

Как соотносятся шаблоны, песочницы, процессы, сессии и операции; что сохраняется при приостановке и заморозке; как взаимодействуют сервисы.

Установка и настройка

Требования к хосту, локальное развёртывание в Kind, настройки по умолчанию, аутентификация, проверка и удаление.

CLI оператора

Доступ к API, проброс портов, space-admin-cli login, узлы, тёплые пулы (warm pools) и сборка системных шаблонов.

Первая песочница

Полный рабочий сценарий с API, настройка команд, обработка вывода, инспекция и удаление.

Обёртка совместимости E2B

Настройка ECW, создание ключа API совместимости, использование протестированного Python SDK E2B, поддерживаемое поведение и ограничения.

Справочник по API

Эндпоинты, поля запросов и ответов, примеры.

Устранение неполадок

Локальная установка, аутентификация, операции жизненного цикла, потоки команд и безопасные повторные попытки.

Профили исходящего трафика оператора

Настройка именованных дополнений политики для федеративного создания через native и ECW.

Наблюдаемость

Возможности сборки телеметрии, контракт выбора Rust/Go и неизменённые настройки образов по умолчанию.

Тёплые пулы

Поддержание загруженных песочниц в готовности на Kubernetes, чтобы при создании пропустить холодную загрузку.

Базовые снимки

Восстановление песочниц из снимка на одном узле, опционально с тёплым пулом узлов.

Локальная сборка документации

Чтобы просматривать руководство и API вместе локально, установите mdBook 0.4.52 и необходимые зависимости для сборки API. Из чистой копии репозитория выполните:

bash scripts/build-docs.sh
python3 -m http.server 8000 --bind 127.0.0.1 --directory target/docs/site

Откройте http://127.0.0.1:8000. Для сборки также требуются Git и Python 3.11+. Отдельные команды — bash scripts/build-guide-docs.sh и bash scripts/build-api-docs.sh — по-прежнему доступны и поддерживают локальные несохранённые правки.

API предоставляет сгенерированный справочник по адресу /openapi-m1.json, содержащий поля запросов, схемы ответов и ошибки. Файл /openapi.json дополнительно включает инкубационные операции, которые не скрыты. Некоторые инкубационные операции — в том числе создание снимков, checkpoint и rollback — скрыты: если развёртывание не включило их для вашей организации, они отвечают так, будто их не существует. Ни один из этих документов не перечисляет их для каких-либо клиентов; /openapi-full.json документирует все операции и требует учётных данных API.

SPACE API

SPACE API управляет жизненным циклом песочниц, запускает процессы и управляет ими, а также передаёт их вывод в потоковом режиме. Поля, помеченные в схеме как incubating, находятся за пределами поддерживаемого контракта.

SPACE реализован на Rust, однако приложения взаимодействуют с ним через HTTP и события, отправляемые сервером (server-sent events). Встраивать библиотеку на Rust не нужно; в пошаговом руководстве по первой песочнице используется пример на Python без сторонних зависимостей. Установка и диагностика кластера выполняются с помощью Bash.

Разработка

При добавлении или обновлении стороннего кода обращайтесь к файлу DEPENDENCIES.md.

После локальной установки наблюдатель Tilt, запущенный скриптом up.sh, продолжает работать: при изменении файлов он пересобирает затронутые образы и обновляет соответствующие рабочие нагрузки. Повторно запустите up.sh, чтобы дождаться стабилизации стека; не запускайте второй экземпляр tilt up. Руководство по Kind описывает этот цикл разработки, локальную топологию и сборку шаблонов.

Используйте точечные юнит-тесты для проверки логики компонентов и дымовые наборы Kind для проверки поведения во время выполнения. Для диагностики, специфичной для установки, см. разделы об устранении проблем с host-path и отладке сборки шаблонов.

Структура репозитория

crates/apps/            CLI-инструменты и бинарные файлы сервисов
crates/libs/            Общие библиотеки на Rust
docs/                   Архитектура, установка, пошаговое руководство по API и устранение неполадок
examples/               Запускаемые примеры работы с API без зависимости от SDK
proto/                  Определения gRPC protobuf
templates/firecracker/  Сборщик начальных образов и рецепты шаблонов
scripts/                Вспомогательные скрипты и дымовые наборы (scripts/tests/)
docker/                 Dockerfile-файлы сервисов и сборка артефактов Rust
ci/                     Проверки CI и скрипты сборки артефактов
infra/space/kind/        Конфигурация локального Kind, начальная загрузка и руководство по разработке
infra/space/aws/reference/  Эталонное развёртывание EKS, применяемое по расписанию

Лицензия

SPACE распространяется под лицензией Apache License, Version 2.0.

Инструкции по предложению изменений и участию в разработке см. в файле CONTRIBUTING.md.

Сведения о покрытии контракта native API, параллелизма, восстановления и карантина приведены в разделе Укрепление native API.