← Sandbox SDK / sandbox

1.0 preview

Sandbox SDK 1.0 это следующий major релиз SDK. Сейчас он доступен как предварительная версия на npm @next тег. Текущий стабильный пакет остается опубликованным для существующих приложений.

Песочница по-прежнему выполняет изолированную работу на Cloudflare Containers. 1.0 preview представляет собой тоньше SDK построен на этой основе: единый process handle для короткой и длительной работы, никакого состояния команд на основе сессий, никакого выбора транспорта, terminals как полноценные PTY, а интерпретатор кода можно подключить как опциональное расширение.

Мы рекомендуем, чтобы новые проекты начните с @cloudflare/sandbox@next и следуйте инструкциям этого раздела. Существующие приложения стоит перенести, как только появится возможность, чтобы вы были готовы к моменту выхода стабильного релиза 1.0. Следуйте Миграция.

Основной Документация Sandbox по-прежнему описывает текущий стабильный пакет. Используйте это раздел о preview API и пути миграции.

npm i @cloudflare/sandbox@next

Разверните пакет Worker и образ контейнера песочницы из одинаковый preview-линии. Не смешивайте preview-пакет Worker со стабильным образом контейнера (и наоборот). Для регулярных развёртываний обратитесь к Разверните приложение Sandbox. О радикальном переходе с нарушением совместимости см. Миграция.

В стабильном пакете со временем появилось несколько способов выполнения команд (exec, startProcess, execStream), необязательное состояние сессии между запусками и выбор транспорта между Durable Object и контейнером. Этот интерфейс работал, но дублировал идеи и скрывал, как песочницы на самом деле ведут себя на контейнерах.

В превью это сведено к более компактному контракту:

Процедуры: Миграция. Концептуальная модель: Выполнение процессов и Жизненный цикл песочницы.

Стабильно: sandbox.exec(string) разрешается, когда команда завершается с буферизированным выводом. Для долго работающих сервисов и потоковой передачи используются отдельные API (startProcess, execStream).

Предпросмотр: sandbox.exec() принимает argv и разрешается, когда process запускается. Один и тот же дескриптор охватывает как короткие команды, так и долго работающие службы.

// Current stable package
const result = await sandbox.exec("npm test");
console.log(result.stdout, result.exitCode);

// 1.0 preview
const process = await sandbox.exec(["npm", "test"]);
const result = await process.output({ encoding: "utf8" });
console.log(result.stdout, result.exitCode);

// Current stable package
const result = await sandbox.exec("npm test");
console.log(result.stdout, result.exitCode);

// 1.0 preview
const process = await sandbox.exec(["npm", "test"]);
const result = await process.output({ encoding: "utf8" });
console.log(result.stdout, result.exitCode);

Возможности shell, такие как каналы и && требуют явной оболочки, например ['/bin/bash', '-lc', 'cd app && npm test']. Передайте cwd и env на каждый exec() когда они нужны процессу. Подробности: Выполнение процессов, API процессов.

Стабильно: сессия по умолчанию может сохранять рабочий каталог и переменные окружения между exec() вызовов. Приложения также могут создавать именованные сессии с помощью createSession().

Предпросмотр: не выполняет сессии в SDK. Каждый exec() работает независимо. Передайте cwd и env при каждом запуске, либо поместите многошаговый синтаксис оболочки в один явный shell argv. Изолируйте конечных пользователей с помощью отдельные песочницы, а не сессии внутри одной песочницы. Модель окружения: Переменные окружения.

Стабильно: оболочки браузера часто используют sandbox.terminal(request) со вспомогательными функциями сессии и xterm sessionId.

Предпросмотр: терминалы являются ресурсами PTY: createTerminal, getTerminal, listTerminals, а также terminal.connect(request). Вспомогательный модуль xterm использует terminalId. См. Терминалы.

Стабильно: методы интерпретатора находятся в Sandbox.

Предпросмотр: подключите интерпретатор в своём подклассе, затем вызовите sandbox.interpreter.*. См. Code interpreter.

Стабильно: приложения могут выбирать HTTP, WebSocket или RPC для связи между Durable Object и контейнером.

Предпросмотр: SDK всегда использует RPC. Уберите SANDBOX_TRANSPORT, transport опцию для getSandbox(), а также setTransport(). Заменяющая настройка не требуется.

Это не новый продукт на основе контейнеров. Обращение к sandbox по-прежнему выполняется через стабильный ID песочницы:

const sandbox = getSandbox(env.Sandbox, "user-123");

const sandbox = getSandbox(env.Sandbox, "user-123");

Эта песочница работает в контейнер. Идентификатор стабилен, однако экземпляр контейнера за ним не всегда один и тот же. Процессы и терминалы, которые вы запускаете, существуют только в текущий контейнер. Когда этот контейнер останавливается или заменяется, эти процессы и терминалы исчезают: старые хендлы сразу завершаются с ошибкой вместо того, чтобы незаметно подключиться к новому контейнеру с тем же ID песочницы.

Остановка и замена контейнера уже происходили в стабильной версии. Предварительная версия делает API процессов и терминала честными в отношении этого времени жизни. Полная модель: Жизненный цикл песочницы. Подробности о процессе: Сколько живёт процесс. Восстановление: Ошибки и восстановление.

Они остаются доступными. Используйте основную документацию Sandbox для сигнатур и игнорируйте параметры сеансов или транспорта там, где эти страницы всё ещё их упоминают:

• Файлы и отслеживание файлов
• Хранилище и резервные копии
• Порты и туннели
• Параметры жизненного цикла и параметры песочницы (кроме удалённых полей session/transport)
• Исходящий трафик (внедрение учётных данных и политика исходящего трафика)

Для окружения процесса на @next, используйте Переменные окружения в этом разделе.

Установка Cloudflare Skills ↗ для вашего агента (Настройка агента). Используйте sandbox-next для работы над @next (рекомендуется для новых проектов). Для существующих приложений на текущем стабильном пакете используйте sandbox-stable пока вы не будете готовы к переносу, затем sandbox-migrate-to-next. Об очистке устаревших API при сохранении стабильной версии рассказано в Руководство по прекращению поддержки в 2026 году и sandbox-stable.

Пока вы используете текущий стабильный пакет, обращайтесь к основной документации:

• Начало работы
• Команды
• Сеансы
• Миграция в связи с прекращением поддержки в 2026 году