Руководства
Изучите полные примеры, включая выполнение кода ИИ, анализ данных и интерактивные среды.
← Sandbox SDK / sandbox
Создание безопасных изолированных сред для выполнения кода
Sandbox SDK позволяет безопасно запускать недоверенный код в изолированных средах. Работает на основе Containers, Sandbox SDK предоставляет простой API для выполнения команд, управления файлами, запуска фоновых процессов и предоставления доступа к сервисам, и всё это прямо из вашего Workers приложения.
Песочницы отлично подходят для создания ИИ-агентов, которым нужно выполнять код, интерактивных сред разработки, платформ анализа данных, систем CI/CD и любых приложений, которым требуется безопасное выполнение кода на edge. Каждая песочница выполняется в собственном изолированном контейнере с полноценной средой Linux, обеспечивая надёжные границы безопасности без потери производительности.
С Sandbox вы можете выполнять скрипты Python, запускать приложения Node.js, анализировать данные, компилировать код и производить сложные вычисления: всё это через простой TypeScript API и без необходимости управлять инфраструктурой.
import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const sandbox = getSandbox(env.Sandbox, 'user-123');
// Execute a command and get the result
const result = await sandbox.exec('python --version');
return Response.json({
output: result.stdout,
exitCode: result.exitCode,
success: result.success
});
}
};import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const sandbox = getSandbox(env.Sandbox, 'user-123');
// Create a Python execution context
const ctx = await sandbox.createCodeContext({ language: 'python' });
// Execute Python code with automatic result capture
const result = await sandbox.runCode(`
import pandas as pd
data = {'product': ['A', 'B', 'C'], 'sales': [100, 200, 150]}
df = pd.DataFrame(data)
df['sales'].sum() # Last expression is automatically returned
`, { context: ctx });
return Response.json({
result: result.results?.[0]?.text,
logs: result.logs
});
}
};import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const sandbox = getSandbox(env.Sandbox, 'user-123');
// Create a project structure
await sandbox.mkdir('/workspace/project/src', { recursive: true });
// Write files
await sandbox.writeFile(
'/workspace/project/package.json',
JSON.stringify({ name: 'my-app', version: '1.0.0' })
);
// Read a file back
const content = await sandbox.readFile('/workspace/project/package.json');
return Response.json({ content });
}
};import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const sandbox = getSandbox(env.Sandbox, 'user-123');
// Watch for file changes in real-time
const watcher = await sandbox.watch('/workspace/src', {
include: ['*.js', '*.ts'],
onEvent: (event) => {
console.log(`${event.type}: ${event.path}`);
if (event.type === 'modify') {
// Trigger rebuild or hot reload
console.log('Code changed, recompiling...');
}
},
onError: (error) => {
console.error('Watch error:', error);
}
});
// Stop watching when done
setTimeout(() => watcher.stop(), 60000);
return Response.json({ message: 'File watcher started' });
}
};import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url);
// Terminal WebSocket connection
if (url.pathname === '/ws/terminal') {
const sandbox = getSandbox(env.Sandbox, 'user-123');
return sandbox.terminal(request, { cols: 80, rows: 24 });
}
return Response.json({ message: 'Terminal endpoint' });
}
};Подключайте терминалы браузера напрямую к shell песочницы через WebSocket. Подробнее: Терминалы в браузере.
import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
// Connect to WebSocket services in sandbox
if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {
const sandbox = getSandbox(env.Sandbox, 'user-123');
return await sandbox.wsConnect(request, 8080);
}
return Response.json({ message: 'WebSocket endpoint' });
}
};Подключайтесь к серверам WebSocket, работающим в песочницах. Подробнее: WebSocket-соединения.
Начало работы
Справочник API
Разверните Worker, сохраняя пакет npm и образ контейнера в одной линии выпуска.
Выполняйте shell-команды, скрипты Python, приложения Node.js и многое другое с поддержкой потокового вывода и автоматической обработкой тайм-аутов.
Читайте, записывайте и изменяйте файлы в файловой системе sandbox. Запускайте фоновые процессы, отслеживайте вывод и управляйте длительными операциями.
Открывайте доступ к HTTP-сервисам, запущенным в песочнице, с автоматически создаваемыми preview URL. Это удобно для интерактивных сред разработки и хостинга приложений.
Выполняйте код на Python и JavaScript с расширенным выводом, включая графики, таблицы и изображения. Состояние сохраняется между запусками, что удобно для кода, сгенерированного ИИ, и интерактивных сценариев работы.
Создавайте браузерные интерфейсы терминала, которые подключаются напрямую к оболочкам песочницы через WebSocket. Стройте совместные терминалы, интерактивные среды разработки и доступ к оболочке в режиме реального времени с автоматическим переподключением.
Подключайте S3-совместимое объектное хранилище (R2, S3, GCS и другие) как локальные файловые системы. Обращайтесь к бакетам с помощью стандартных файловых операций, а данные сохраняются между жизненными циклами песочницы. Требуется развертывание в продакшене.
Отслеживайте изменения файлов и каталогов с помощью нативных событий файловой системы. Такой подход отлично подходит для серверов разработки с горячей перезагрузкой, систем автоматизации сборки и инструментов мониторинга конфигурации.
Блокируйте, разрешайте и перехватывайте исходящие HTTP-запросы из песочниц. Храните учётные данные в своём Worker, добавляя заголовки авторизации в обработчиках исходящих запросов.
Создание мощных приложений с Sandbox:
Безопасно и надёжно выполняйте код, сгенерированный большими языковыми моделями. Нативная интеграция с Workers AI моделей, таких как GPT-OSS, добавляет вызов функций с выполнением в песочнице. Подходит для ИИ-агентов, ассистентов для кода и автономных систем, которым нужно выполнять недоверенный код.
Создавайте интерактивные среды анализа данных с помощью pandas, NumPy и Matplotlib. Формируйте диаграммы, таблицы и визуализации с автоматическим расширенным форматированием вывода.
Создавайте облачные IDE, площадки для написания кода и инструменты для совместной разработки с полноценными средами Linux и URL-адресами предварительного просмотра.
Запускайте тесты, компилируйте код и выполняйте пайплайны сборки в изолированных средах с параллельным выполнением и потоковыми логами.
Бессерверная среда выполнения контейнеров, на которой работает Sandbox: она позволяет запускать любые контейнеризированные нагрузки на edge.
Запускайте модели машинного обучения и LLM в сети. Сочетайте с Sandbox для безопасного выполнения кода ИИ.
Слой координации с отслеживанием состояния, который позволяет Sandbox поддерживать постоянные окружения со строгой согласованностью.
Установка Cloudflare Skills ↗ для вашего агента (Настройка агента). Используйте sandbox-stable с основной документацией на этом сайте, пока вы используете текущий стабильный пакет. Используйте sandbox-next для @cloudflare/sandbox@next (рекомендуется для новых проектов). Когда будете готовы перенести существующее приложение, используйте sandbox-migrate-to-next.
Изучите полные примеры, включая выполнение кода ИИ, анализ данных и интерактивные среды.
Разверните и поддерживайте согласованность пакета и образа.
Узнайте, как решать конкретные задачи и реализовывать функции с помощью Sandbox SDK.
Установка @cloudflare/sandbox@next и подготовиться к выходу
Sandbox SDK 1.0.
Изучите полную документацию по API Sandbox SDK.
Подробнее об основных концепциях и архитектуре Sandbox SDK.
Подробнее о параметрах конфигурации Sandbox SDK.
Просматривайте исходный код SDK, сообщайте о проблемах и вносите свой вклад в проект.
Узнайте о тарификации Sandbox на основе платформы Containers.
Подробнее об ограничениях ресурсов, квотах и рекомендациях по работе с ними.
Общайтесь с сообществом в Discord. Задавайте вопросы, делитесь тем, что вы создаёте, и получайте помощь от других разработчиков.
79 страниц, скопированных из документации Cloudflare для sandbox.