← Sandbox SDK / sandbox / bridge

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

Эта страница описывает каждый маршрут, предоставляемый мост песочницы в стабильном шаблоне.

Все маршруты внутри /v1/sandbox/* и /v1/openapi.* требуют Bearer-токен:

Authorization: Bearer <SANDBOX_API_KEY>

Когда SANDBOX_API_KEY не настроен, аутентификация пропускается для удобства локальной разработки. Перед развертыванием в продакшене обязательно задайте секрет.

Мост предоставляет собственную документацию по API:

Оба маршрута принимают аутентификацию через заголовок Bearer или ?token= параметр запроса.

При локальном запуске с npm run dev, откройте http://localhost:8787/v1/openapi в браузере, чтобы интерактивно изучить каждую конечную точку.

/exec конечная точка принимает тело в формате JSON:

{
  "argv": ["sh", "-lc", "echo hello"],
  "timeout_ms": 10000,
  "cwd": "/workspace"
}

Каждый элемент массива argv массив экранируется с помощью ANSI-C $'...' экранирование перед объединением в команду оболочки. Токены, содержащие только безопасные символы (A-Za-z0-9@%+=:,./-) передаются без изменений. Все остальные токены оборачиваются в $'...' с экранированными обратными слэшами, одинарными кавычками, символами новой строки, возврата каретки и табуляции. Это предотвращает shell injection и сохраняет аргументы, содержащие пробелы, кавычки или специальные символы.

Ответ представляет собой text/event-stream со следующими типами событий:

Путь к файлу кодируется в URL после /file/. Все пути должны находиться в пределах /workspace. Попытки обхода пути (например, ../../etc/passwd) отклоняются.

/persist конечная точка принимает необязательный excludes параметр запроса: список относительных путей через запятую, которые нужно исключить из архива.

/hydrate конечная точка принимает необработанные данные tar объёмом до 32 MiB.

/mount конечная точка принимает тело в формате JSON. Поддерживаются два сценария:

Опустите endpoint и передайте имя привязки R2 в Worker в bucket:

{
  "bucket": "MY_BUCKET",
  "mountPath": "/mnt/data",
  "options": {
    "readOnly": false,
    "prefix": "/subdir"
  }
}

Когда options.endpoint не указан, bucket означает имя привязки R2 в Worker.

Для явного монтирования S3-совместимой конечной точки укажите endpoint и при необходимости credentials:

{
  "bucket": "my-r2-bucket",
  "mountPath": "/mnt/data",
  "options": {
    "endpoint": "https://ACCOUNT_ID.r2.cloudflarestorage.com",
    "readOnly": false,
    "prefix": "/subdir",
    "credentials": {
      "accessKeyId": "...",
      "secretAccessKey": "..."
    }
  }
}

Когда endpoint указан, bucket означает имя удалённого бакета. Учётные данные необязательны только в этом режиме: мост определяет их автоматически из секретов Worker (R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY или AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY) если не указано.

Сессии изолируют рабочую директорию, переменные окружения и состояние выполнения команд внутри sandbox. Передайте Session-Id header в /exec, /file/*, а также /pty запросы, чтобы привязать их к сессии.

Если не указан Session-Id header, запросы используют неявный режим выполнения сандбокса. По умолчанию это сессия по умолчанию, но SDK, настроенные с enableDefaultSession: false вместо этого выполняйте такие неявные операции без сессии.

Параметры запроса:

WebSocket передаёт двоичные кадры для ввода-вывода терминала и текстовые кадры JSON для управляющих сообщений:

Пул прогретых контейнеров заранее запускает контейнеры песочниц, чтобы новые сеансы запускались мгновенно. Настройте его с помощью переменных окружения в wrangler.jsonc:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "vars": {
    "WARM_POOL_TARGET": "3",
    "WARM_POOL_REFRESH_INTERVAL": "10000"
  }
}

[vars]
WARM_POOL_TARGET = "3"           # Number of idle containers to keep warm (0 = disabled)
WARM_POOL_REFRESH_INTERVAL = "10000"  # Health-check interval in milliseconds

Cron-триггер (* * * * *) автоматически прогревает пул после развёртывания. Установите WARM_POOL_TARGET к "0" (значение по умолчанию), чтобы отключить пул и избежать непредвиденных расходов.

• Обзор Bridge : Что такое bridge, его развёртывание и примеры использования.
• Справочник по API Sandbox : полный справочник по методам Sandbox SDK.
• Исходный код Bridge на GitHub ↗ : Worker, Dockerfile и схема OpenAPI.