Команды

Выполняйте команды и управляйте фоновыми процессами в изолированном контейнерном окружении песочницы.

Методы

`exec()`

Выполните команду и получите полный результат.

const result = await sandbox.exec(command: string, options?: ExecOptions): Promise<ExecuteResponse>

Параметры:

command - Команда для выполнения (может включать аргументы)
options (необязательно):
- stream - Включите потоковые обратные вызовы (по умолчанию: false)
- onOutput - Обратный вызов для вывода в реальном времени: (stream: 'stdout' | 'stderr', data: string) => void
- timeout - Максимальное время выполнения в миллисекундах
- env - Переменные окружения для этой команды: Record<string, string | undefined>
- cwd - Рабочий каталог для этой команды
- stdin - Данные для передачи в стандартный ввод команды (обеспечивает произвольный ввод без риска инъекции shell-команд)

Возвращает: Promise<ExecuteResponse> с success, stdout, stderr, exitCode

const result = await sandbox.exec("npm run build");

if (result.success) {
	console.log("Build output:", result.stdout);
} else {
	console.error("Build failed:", result.stderr);
}

// With streaming
await sandbox.exec("npm install", {
	stream: true,
	onOutput: (stream, data) => console.log(`[${stream}] ${data}`),
});

// With environment variables (undefined values are skipped)
await sandbox.exec("node app.js", {
	env: {
		NODE_ENV: "production",
		PORT: "3000",
		DEBUG_MODE: undefined, // Skipped, uses container default or unset
	},
});

// Pass input via stdin (no shell injection risks)
const result = await sandbox.exec("cat", {
	stdin: "Hello, world!",
});
console.log(result.stdout); // "Hello, world!"

// Process user input safely
const userInput = "[email protected]\nsecret123";
await sandbox.exec("python process_login.py", {
	stdin: userInput,
});

const result = await sandbox.exec('npm run build');

if (result.success) {
  console.log('Build output:', result.stdout);
} else {
  console.error('Build failed:', result.stderr);
}

// With streaming
await sandbox.exec('npm install', {
  stream: true,
  onOutput: (stream, data) => console.log(`[${stream}] ${data}`)
});

// With environment variables (undefined values are skipped)
await sandbox.exec('node app.js', {
  env: {
    NODE_ENV: 'production',
    PORT: '3000',
    DEBUG_MODE: undefined // Skipped, uses container default or unset
  }
});

// Pass input via stdin (no shell injection risks)
const result = await sandbox.exec('cat', {
  stdin: 'Hello, world!'
});
console.log(result.stdout); // "Hello, world!"

// Process user input safely
const userInput = '[email protected]\nsecret123';
await sandbox.exec('python process_login.py', {
  stdin: userInput
});

Поведение тайм-аута

Когда истекает время ожидания команды, SDK выбрасывает ошибку на стороне вызывающего кода и закрывает соединение. Базовый процесс продолжает работу внутри контейнера. Чтобы остановить процесс, превысивший тайм-аут, удалите сеанс с помощью deleteSession() или уничтожьте sandbox с помощью destroy().

Приоритет тайм-аута: для отдельной команды timeout на exec() > на уровне сессии commandTimeoutMs на createSession() > глобальный COMMAND_TIMEOUT_MS переменную окружения. Если ни одна из них не задана, команды выполняются без тайм-аута.

`execStream()`

Выполните команду и получите поток Server-Sent Events для обработки в реальном времени.

const stream = await sandbox.execStream(command: string, options?: ExecOptions): Promise<ReadableStream>

Параметры:

command - Команда для выполнения
options - То же, что и exec() (включая stdin поддержка)

Возвращает: Promise<ReadableStream> генерируя ExecEvent объекты (start, stdout, stderr, complete, error)

import { parseSSEStream } from "@cloudflare/sandbox";

const stream = await sandbox.execStream("npm run build");

for await (const event of parseSSEStream(stream)) {
	switch (event.type) {
		case "stdout":
			console.log("Output:", event.data);
			break;
		case "complete":
			console.log("Exit code:", event.exitCode);
			break;
		case "error":
			console.error("Failed:", event.error);
			break;
	}
}

// Stream with stdin input
const inputStream = await sandbox.execStream(
	'python -c "import sys; print(sys.stdin.read())"',
	{
		stdin: "Data from Workers!",
	},
);

for await (const event of parseSSEStream(inputStream)) {
	if (event.type === "stdout") {
		console.log("Python received:", event.data);
	}
}

import { parseSSEStream, type ExecEvent } from '@cloudflare/sandbox';

const stream = await sandbox.execStream('npm run build');

for await (const event of parseSSEStream<ExecEvent>(stream)) {
  switch (event.type) {
    case 'stdout':
      console.log('Output:', event.data);
      break;
    case 'complete':
      console.log('Exit code:', event.exitCode);
      break;
    case 'error':
      console.error('Failed:', event.error);
      break;
  }
}

// Stream with stdin input
const inputStream = await sandbox.execStream('python -c "import sys; print(sys.stdin.read())"', {
  stdin: 'Data from Workers!'
});

for await (const event of parseSSEStream<ExecEvent>(inputStream)) {
  if (event.type === 'stdout') {
    console.log('Python received:', event.data);
  }
}

`startProcess()`

Запустите долго выполняющийся фоновый процесс.

const process = await sandbox.startProcess(command: string, options?: ProcessOptions): Promise<Process>

Параметры:

command - Команда для запуска в качестве фонового процесса
options (необязательно):
- cwd - Рабочий каталог
- env - Переменные окружения: Record<string, string | undefined>
- stdin - Данные для передачи в стандартный ввод команды
- timeout - Максимальное время выполнения в миллисекундах
- processId - Пользовательский ID процесса
- encoding - Кодировка вывода (по умолчанию: 'utf8')
- autoCleanup - Нужно ли завершать процесс при переходе песочницы в спящий режим

Возвращает: Promise<Process> объект с:

id - Уникальный идентификатор процесса
pid - Идентификатор системного процесса
command - Выполняемая команда
status - Текущий статус ('running', 'exited', и т. д.)
kill() - Остановка процесса
getStatus() - Получение текущего статуса
getLogs() - Получение накопленных логов
waitForPort() - Ожидание, пока процесс начнет прослушивать порт
waitForLog() - Ожидание шаблона в выводе процесса
waitForExit() - Ожидание завершения процесса и получение кода выхода

const server = await sandbox.startProcess("python -m http.server 8000");
console.log("Started with PID:", server.pid);

// With custom environment
const app = await sandbox.startProcess("node app.js", {
	cwd: "/workspace/my-app",
	env: { NODE_ENV: "production", PORT: "3000" },
});

// Start process with stdin input (useful for interactive applications)
const interactive = await sandbox.startProcess("python interactive_app.py", {
	stdin: "initial_config\nstart_mode\n",
});

const server = await sandbox.startProcess('python -m http.server 8000');
console.log('Started with PID:', server.pid);

// With custom environment
const app = await sandbox.startProcess('node app.js', {
  cwd: '/workspace/my-app',
  env: { NODE_ENV: 'production', PORT: '3000' }
});

// Start process with stdin input (useful for interactive applications)
const interactive = await sandbox.startProcess('python interactive_app.py', {
  stdin: 'initial_config\nstart_mode\n'
});

`listProcesses()`

Список всех выполняющихся процессов.

const processes = await sandbox.listProcesses(): Promise<ProcessInfo[]>

const processes = await sandbox.listProcesses();

for (const proc of processes) {
	console.log(`${proc.id}: ${proc.command} (PID ${proc.pid})`);
}

const processes = await sandbox.listProcesses();

for (const proc of processes) {
  console.log(`${proc.id}: ${proc.command} (PID ${proc.pid})`);
}

`killProcess()`

Завершает указанный процесс и все его дочерние процессы.

await sandbox.killProcess(processId: string, signal?: string): Promise<void>

Параметры:

processId - Идентификатор процесса (из startProcess() или listProcesses())
signal - Сигнал для отправки (по умолчанию: "SIGTERM")

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

const server = await sandbox.startProcess("python -m http.server 8000");
await sandbox.killProcess(server.id);

// Example with a process that spawns children
const script = await sandbox.startProcess(
	'bash -c "sleep 10 & sleep 10 & wait"',
);
// killProcess terminates both sleep commands and the bash process
await sandbox.killProcess(script.id);

const server = await sandbox.startProcess('python -m http.server 8000');
await sandbox.killProcess(server.id);

// Example with a process that spawns children
const script = await sandbox.startProcess('bash -c "sleep 10 & sleep 10 & wait"');
// killProcess terminates both sleep commands and the bash process
await sandbox.killProcess(script.id);

`killAllProcesses()`

Завершает все работающие процессы.

await sandbox.killAllProcesses(): Promise<void>

await sandbox.killAllProcesses();

await sandbox.killAllProcesses();

`streamProcessLogs()`

Передаёт журналы работающего процесса в режиме реального времени.

const stream = await sandbox.streamProcessLogs(processId: string): Promise<ReadableStream>

Параметры:

processId - Идентификатор процесса

Возвращает: Promise<ReadableStream> генерируя LogEvent объекты

import { parseSSEStream } from "@cloudflare/sandbox";

const server = await sandbox.startProcess("node server.js");
const logStream = await sandbox.streamProcessLogs(server.id);

for await (const log of parseSSEStream(logStream)) {
	console.log(`[${log.timestamp}] ${log.data}`);

	if (log.data.includes("Server started")) break;
}

import { parseSSEStream, type LogEvent } from '@cloudflare/sandbox';

const server = await sandbox.startProcess('node server.js');
const logStream = await sandbox.streamProcessLogs(server.id);

for await (const log of parseSSEStream<LogEvent>(logStream)) {
  console.log(`[${log.timestamp}] ${log.data}`);

  if (log.data.includes('Server started')) break;
}

`getProcessLogs()`

Получение накопленных логов процесса.

const logs = await sandbox.getProcessLogs(processId: string): Promise<string>

Параметры:

processId - Идентификатор процесса

Возвращает: Promise<string> со всем накопленным выводом

const server = await sandbox.startProcess("node server.js");
await new Promise((resolve) => setTimeout(resolve, 5000));

const logs = await sandbox.getProcessLogs(server.id);
console.log("Server logs:", logs);

const server = await sandbox.startProcess('node server.js');
await new Promise(resolve => setTimeout(resolve, 5000));

const logs = await sandbox.getProcessLogs(server.id);
console.log('Server logs:', logs);

Стандартный ввод (stdin)

Все методы выполнения команд поддерживают передачу данных в стандартный ввод команды через stdin опция. Это обеспечивает безопасную обработку пользовательского ввода без риска инъекции команд оболочки.

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

Если вы указываете stdin параметр:

Входные данные записываются во временный файл внутри контейнера
Команда получает эти данные через свой поток стандартного ввода
Временный файл автоматически удаляется после выполнения

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

// Safe: User input goes through stdin, not shell parsing
const userInput = "[email protected]; rm -rf /";
const result = await sandbox.exec("python validate_email.py", {
	stdin: userInput,
});

// Instead of unsafe: `python validate_email.py "${userInput}"`
// which could execute the embedded `rm -rf /` command

// Safe: User input goes through stdin, not shell parsing
const userInput = '[email protected]; rm -rf /';
const result = await sandbox.exec('python validate_email.py', {
  stdin: userInput
});

// Instead of unsafe: `python validate_email.py "${userInput}"`
// which could execute the embedded `rm -rf /` command

Типичные паттерны

Обработка данных формы:

const formData = JSON.stringify({
	username: "john_doe",
	email: "[email protected]",
});

const result = await sandbox.exec("python process_form.py", {
	stdin: formData,
});

const formData = JSON.stringify({
  username: 'john_doe',
  email: '[email protected]'
});

const result = await sandbox.exec('python process_form.py', {
  stdin: formData
});

Интерактивные инструменты командной строки:

// Simulate user responses to prompts
const responses = "yes\nmy-app\n1.0.0\n";
const result = await sandbox.exec("npm init", {
	stdin: responses,
});

// Simulate user responses to prompts
const responses = 'yes\nmy-app\n1.0.0\n';
const result = await sandbox.exec('npm init', {
  stdin: responses
});

Преобразование данных:

const csvData = "name,age,city\nJohn,30,NYC\nJane,25,LA";
const result = await sandbox.exec("python csv_processor.py", {
	stdin: csvData,
});

console.log("Processed data:", result.stdout);

const csvData = 'name,age,city\nJohn,30,NYC\nJane,25,LA';
const result = await sandbox.exec('python csv_processor.py', {
  stdin: csvData
});

console.log('Processed data:', result.stdout);

Методы готовности процесса

Process объект, возвращаемый startProcess() включает методы ожидания готовности процесса перед продолжением.

`process.waitForPort()`

Дождитесь, пока процесс начнёт слушать порт.

await process.waitForPort(port: number, options?: WaitForPortOptions): Promise<void>

Параметры:

port - Номер порта для проверки
options (необязательно):
- mode - Режим проверки: 'http' (по умолчанию) или 'tcp'
- timeout - Максимальное время ожидания в миллисекундах
- interval - Интервал проверки в миллисекундах (по умолчанию: 100)
- path - HTTP-путь для проверки (по умолчанию: '/', только в режиме HTTP)
- status - Ожидаемый диапазон HTTP-статусов (по умолчанию: { min: 200, max: 399 }, только в режиме HTTP)

Режим HTTP (по умолчанию) выполняет HTTP GET-запрос и проверяет статус ответа:

const server = await sandbox.startProcess("node server.js");

// Wait for server to be ready (HTTP mode)
await server.waitForPort(3000);

// Check specific endpoint and status
await server.waitForPort(8080, {
	path: "/health",
	status: { min: 200, max: 299 },
	timeout: 30000,
});

const server = await sandbox.startProcess('node server.js');

// Wait for server to be ready (HTTP mode)
await server.waitForPort(3000);

// Check specific endpoint and status
await server.waitForPort(8080, {
  path: '/health',
  status: { min: 200, max: 299 },
  timeout: 30000
});

Режим TCP проверяет, принимает ли порт соединения:

const db = await sandbox.startProcess("redis-server");

// Wait for database to accept connections
await db.waitForPort(6379, {
	mode: "tcp",
	timeout: 10000,
});

const db = await sandbox.startProcess('redis-server');

// Wait for database to accept connections
await db.waitForPort(6379, {
  mode: 'tcp',
  timeout: 10000
});

Исключения:

ProcessReadyTimeoutError - Если порт не становится готовым в течение тайм-аута
ProcessExitedBeforeReadyError - Если процесс завершается до того, как становится готовым

`process.waitForLog()`

Дождитесь появления паттерна в выводе процесса.

const result = await process.waitForLog(pattern: string | RegExp, timeout?: number): Promise<WaitForLogResult>

Параметры:

pattern - Строка или RegExp для поиска совпадений в stdout/stderr
timeout - Максимальное время ожидания в миллисекундах (необязательно)

Возвращает: Promise<WaitForLogResult> с:

line - Совпадающая строка вывода
matches - Массив групп захвата (для шаблонов RegExp)

const server = await sandbox.startProcess("node server.js");

// Wait for string pattern
const result = await server.waitForLog("Server listening");
console.log("Ready:", result.line);

// Wait for RegExp with capture groups
const result = await server.waitForLog(/Server listening on port (\d+)/);
console.log("Port:", result.matches[1]); // Extracted port number

// With timeout
await server.waitForLog("Ready", 30000);

const server = await sandbox.startProcess('node server.js');

// Wait for string pattern
const result = await server.waitForLog('Server listening');
console.log('Ready:', result.line);

// Wait for RegExp with capture groups
const result = await server.waitForLog(/Server listening on port (\d+)/);
console.log('Port:', result.matches[1]); // Extracted port number

// With timeout
await server.waitForLog('Ready', 30000);

Исключения:

ProcessReadyTimeoutError - Если шаблон не найден в течение тайм-аута
ProcessExitedBeforeReadyError - Если процесс завершается до появления шаблона

`process.waitForExit()`

Дождитесь завершения процесса и получения кода выхода.

const result = await process.waitForExit(timeout?: number): Promise<WaitForExitResult>

Параметры:

timeout - Максимальное время ожидания в миллисекундах (необязательно)

Возвращает: Promise<WaitForExitResult> с:

exitCode - Код завершения процесса

const build = await sandbox.startProcess("npm run build");

// Wait for build to complete
const result = await build.waitForExit();
console.log("Build finished with exit code:", result.exitCode);

// With timeout
const result = await build.waitForExit(60000); // 60 second timeout

const build = await sandbox.startProcess('npm run build');

// Wait for build to complete
const result = await build.waitForExit();
console.log('Build finished with exit code:', result.exitCode);

// With timeout
const result = await build.waitForExit(60000); // 60 second timeout

Исключения:

ProcessReadyTimeoutError - Если процесс не завершается в течение тайм-аута

Руководство по фоновым процессам - Управление длительными процессами
Files API - Операции с файлами

Команды

Методы

exec()

execStream()

startProcess()

listProcesses()

killProcess()

killAllProcesses()

streamProcessLogs()

getProcessLogs()

Стандартный ввод (stdin)

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

Типичные паттерны

Методы готовности процесса

process.waitForPort()

process.waitForLog()

process.waitForExit()

Дополнительные материалы

`exec()`

`execStream()`

`startProcess()`

`listProcesses()`

`killProcess()`

`killAllProcesses()`

`streamProcessLogs()`

`getProcessLogs()`

`process.waitForPort()`

`process.waitForLog()`

`process.waitForExit()`