Příkazy

Spouštějte příkazy a spravujte procesy na pozadí v izolovaném kontejnerovém prostředí sandboxu.

Metody

`exec()`

Spustí příkaz a vrátí kompletní výsledek.

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

Parametry:

command - Příkaz ke spuštění (může obsahovat argumenty)
options (volitelné):
- stream - Povolte streamované callbacky (výchozí: false)
- onOutput - Callback pro výstup v reálném čase: (stream: 'stdout' | 'stderr', data: string) => void
- timeout - Maximální doba spuštění v milisekundách
- env - Proměnné prostředí pro tento příkaz: Record<string, string | undefined>
- cwd - Pracovní adresář pro tento příkaz
- stdin - Data předaná na standardní vstup příkazu (umožňuje libovolný vstup bez rizika shell injection)

Vrací: Promise<ExecuteResponse> hodnotou 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
});

`execStream()`

Spustí příkaz a vrátí stream Server-Sent Events pro zpracování v reálném čase.

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

Parametry:

command - Příkaz ke spuštění
options - Stejné jako exec() (včetně stdin podpora)

Vrací: Promise<ReadableStream> a vysílá ExecEvent objekty (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()`

Spusťte dlouho běžící proces na pozadí.

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

Parametry:

command - Příkaz ke spuštění jako proces na pozadí
options (volitelné):
- cwd - Pracovní adresář
- env - Proměnné prostředí: Record<string, string | undefined>
- stdin - Data předaná na standardní vstup příkazu
- timeout - Maximální doba spuštění v milisekundách
- processId - Vlastní ID procesu
- encoding - Kódování výstupu (výchozí: 'utf8')
- autoCleanup - Zda ukončit proces při uspání sandboxu

Vrací: Promise<Process> objekt s:

id - Jedinečný identifikátor procesu
pid - ID systémového procesu
command - Právě spouštěný příkaz
status - Aktuální stav ('running', 'exited', atd.)
kill() - Zastavení procesu
getStatus() - Získejte aktuální stav
getLogs() - Získejte nahromaděné logy
waitForPort() - Čekání, až proces začne naslouchat na portu
waitForLog() - Čekání na vzor ve výstupu procesu
waitForExit() - Čekání, až proces skončí, a vrácení kódu ukončení

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()`

Vypíše všechny běžící procesy.

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()`

Ukončí konkrétní proces a všechny jeho podřízené procesy.

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

Parametry:

processId - ID procesu (z startProcess() nebo listProcesses())
signal - Signál k odeslání (výchozí: "SIGTERM")

Signál se odešle celé skupině procesů, čímž se zajistí ukončení hlavního procesu i všech procesů potomků, které spustil. Tím se zabrání tomu, aby po ukončení rodičovského procesu dál běžely osiřelé procesy.

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()`

Ukončí všechny běžící procesy.

await sandbox.killAllProcesses(): Promise<void>

await sandbox.killAllProcesses();

await sandbox.killAllProcesses();

`streamProcessLogs()`

Streamujte protokoly z běžícího procesu v reálném čase.

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

Parametry:

processId - ID procesu

Vrací: Promise<ReadableStream> a vysílá LogEvent objekty

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()`

Získejte nashromážděné logy z procesu.

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

Parametry:

processId - ID procesu

Vrací: Promise<string> s veškerým nahromaděným výstupem

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);

Standardní vstup (stdin)

Všechny metody spouštění příkazů podporují předávání dat na standardní vstup příkazu prostřednictvím stdin volba. To umožňuje bezpečné zpracování uživatelského vstupu bez rizika shell injection.

Jak funguje stdin

Když zadáte stdin možnost:

Vstupní data se zapíší do dočasného souboru uvnitř kontejneru
Příkaz přijímá tato data prostřednictvím svého standardního vstupního streamu
Dočasný soubor se po spuštění automaticky smaže

Tento přístup zabraňuje útokům typu shell injection, ke kterým by mohlo dojít při vkládání uživatelských dat přímo do příkazů.

// 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

Běžné vzory

Zpracování dat formuláře:

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
});

Interaktivní nástroje příkazového řádku:

// 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
});

Transformace dat:

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);

Metody připravenosti procesu

Process objekt vrácený startProcess() obsahuje metody, kterými počkáte, až bude proces připravený, než budete pokračovat.

`process.waitForPort()`

Počkejte, až proces začne naslouchat na portu.

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

Parametry:

port - Číslo portu ke kontrole
options (volitelné):
- mode - Režim kontroly: 'http' (výchozí) nebo 'tcp'
- timeout - Maximální doba čekání v milisekundách
- interval - Interval kontroly v milisekundách (výchozí: 100)
- path - Cesta HTTP ke kontrole (výchozí: '/', pouze v režimu HTTP)
- status - Očekávaný rozsah stavových kódů HTTP (výchozí: { min: 200, max: 399 }, pouze v režimu HTTP)

Režim HTTP (výchozí) odešle HTTP GET požadavek a zkontroluje stavový kód odpovědi:

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
});

Režim TCP zkontroluje, zda port přijímá spojení:

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
});

Vyhazuje:

ProcessReadyTimeoutError - Pokud port není připravený v rámci časového limitu
ProcessExitedBeforeReadyError - Pokud proces skončí dříve, než je připravený

`process.waitForLog()`

Počkejte, až se ve výstupu procesu objeví daný vzor.

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

Parametry:

pattern - Řetězec nebo RegExp, který se má hledat ve stdout/stderr
timeout - Maximální doba čekání v milisekundách (volitelné)

Vrací: Promise<WaitForLogResult> s:

line - Odpovídající řádek výstupu
matches - Pole zachytávacích skupin (pro vzory 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);

Vyhazuje:

ProcessReadyTimeoutError - Pokud vzor není nalezen v rámci časového limitu
ProcessExitedBeforeReadyError - Pokud proces skončí dříve, než se objeví daný vzor

`process.waitForExit()`

Počkejte, až proces skončí, a vraťte návratový kód.

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

Parametry:

timeout - Maximální doba čekání v milisekundách (volitelné)

Vrací: Promise<WaitForExitResult> s:

exitCode - Návratový kód procesu

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

Vyhazuje:

ProcessReadyTimeoutError - Pokud proces neskončí v rámci časového limitu

Průvodce procesy na pozadí - Správa dlouhotrvajících procesů
API souborů - Operace se soubory

Příkazy

Metody

exec()

execStream()

startProcess()

listProcesses()

killProcess()

killAllProcesses()

streamProcessLogs()

getProcessLogs()

Standardní vstup (stdin)

Jak funguje stdin

Běžné vzory

Metody připravenosti procesu

process.waitForPort()

process.waitForLog()

process.waitForExit()

Související zdroje

`exec()`

`execStream()`

`startProcess()`

`listProcesses()`

`killProcess()`

`killAllProcesses()`

`streamProcessLogs()`

`getProcessLogs()`

`process.waitForPort()`

`process.waitForLog()`

`process.waitForExit()`