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

Sandbox SDK

Создание безопасных изолированных сред для выполнения кода

Доступно на тарифе Workers Paid

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


Возможности

Разверните приложение Sandbox

Разверните Worker, сохраняя пакет npm и образ контейнера в одной линии выпуска.

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

Выполняйте shell-команды, скрипты Python, приложения Node.js и многое другое с поддержкой потокового вывода и автоматической обработкой тайм-аутов.

Управление файлами и процессами

Читайте, записывайте и изменяйте файлы в файловой системе sandbox. Запускайте фоновые процессы, отслеживайте вывод и управляйте длительными операциями.

Публикация сервисов через preview URL

Открывайте доступ к HTTP-сервисам, запущенным в песочнице, с автоматически создаваемыми preview URL. Это удобно для интерактивных сред разработки и хостинга приложений.

Прямое выполнение кода

Выполняйте код на Python и JavaScript с расширенным выводом, включая графики, таблицы и изображения. Состояние сохраняется между запусками, что удобно для кода, сгенерированного ИИ, и интерактивных сценариев работы.

Создание интерактивных терминалов

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

Постоянное хранение данных с объектным хранилищем

Подключайте S3-совместимое объектное хранилище (R2, S3, GCS и другие) как локальные файловые системы. Обращайтесь к бакетам с помощью стандартных файловых операций, а данные сохраняются между жизненными циклами песочницы. Требуется развертывание в продакшене.

Отслеживание изменений файлов в реальном времени

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

Обработка исходящего трафика

Блокируйте, разрешайте и перехватывайте исходящие HTTP-запросы из песочниц. Храните учётные данные в своём Worker, добавляя заголовки авторизации в обработчиках исходящих запросов.


Сценарии использования

Создание мощных приложений с Sandbox:

Выполнение кода ИИ

Безопасно и надёжно выполняйте код, сгенерированный большими языковыми моделями. Нативная интеграция с Workers AI моделей, таких как GPT-OSS, добавляет вызов функций с выполнением в песочнице. Подходит для ИИ-агентов, ассистентов для кода и автономных систем, которым нужно выполнять недоверенный код.

Анализ данных и ноутбуки

Создавайте интерактивные среды анализа данных с помощью pandas, NumPy и Matplotlib. Формируйте диаграммы, таблицы и визуализации с автоматическим расширенным форматированием вывода.

Интерактивные среды разработки

Создавайте облачные IDE, площадки для написания кода и инструменты для совместной разработки с полноценными средами Linux и URL-адресами предварительного просмотра.

CI/CD и системы сборки

Запускайте тесты, компилируйте код и выполняйте пайплайны сборки в изолированных средах с параллельным выполнением и потоковыми логами.


Containers

Бессерверная среда выполнения контейнеров, на которой работает Sandbox: она позволяет запускать любые контейнеризированные нагрузки на edge.

Workers AI

Запускайте модели машинного обучения и LLM в сети. Сочетайте с Sandbox для безопасного выполнения кода ИИ.

Durable Objects

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


Дополнительные ресурсы

Агенты для написания кода

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

Руководства

Изучите полные примеры, включая выполнение кода ИИ, анализ данных и интерактивные среды.

1.0 preview

Установка @cloudflare/sandbox@next и подготовиться к выходу Sandbox SDK 1.0.

Репозиторий GitHub

Просматривайте исходный код SDK, сообщайте о проблемах и вносите свой вклад в проект.

Цены

Узнайте о тарификации Sandbox на основе платформы Containers.

Лимиты

Подробнее об ограничениях ресурсов, квотах и рекомендациях по работе с ними.

Сообщество в Discord

Общайтесь с сообществом в Discord. Задавайте вопросы, делитесь тем, что вы создаёте, и получайте помощь от других разработчиков.

Содержание

79 страниц, скопированных из документации Cloudflare для sandbox.

Pages

1.0 preview

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

Мост песочницы

Основные понятия

Конфигурация

Практические руководства

Платформа

Руководства