INTEGRITY Dokumentace

Sandbox SDK

Vytvářejte zabezpečená, izolovaná prostředí pro spouštění kódu

K dispozici v tarifu Workers Paid

Sandbox SDK vám umožňuje bezpečně spouštět nedůvěryhodný kód v izolovaných prostředích. Je postaveno na Containers, Sandbox SDK poskytuje jednoduché API pro spouštění příkazů, správu souborů, běh procesů na pozadí a zpřístupňování služeb, to vše přímo z vašeho Workers aplikace.

Sandboxy jsou ideální pro vytváření AI agentů, kteří potřebují spouštět kód, pro interaktivní vývojová prostředí, platformy pro analýzu dat, CI/CD systémy a jakékoli aplikace vyžadující bezpečné spouštění kódu na edge. Každý sandbox běží ve vlastním izolovaném kontejneru s plnohodnotným prostředím Linux, což zajišťuje silné bezpečnostní hranice při zachování výkonu.

Se Sandboxem můžete spouštět skripty v Pythonu, provozovat aplikace v Node.js, analyzovat data, kompilovat kód a provádět složité výpočty, to vše pomocí jednoduchého TypeScript API a bez nutnosti spravovat infrastrukturu.

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

Prohlížečové terminály připojte přímo k shellům sandboxu přes WebSocket. Další informace: Terminály v prohlížeči.

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

Připojte se k WebSocket serverům běžícím v sandboxech. Další informace: Připojení WebSocket.

Začínáme

Referenční dokumentace API


Funkce

Nasazení aplikace Sandbox

Nasaďte svůj Worker a udržujte balíček npm a obraz kontejneru ve stejné vydávací řadě.

Bezpečné spouštění příkazů

Spouštějte shellové příkazy, Python skripty, Node.js aplikace a další, s podporou streamovaného výstupu a automatickým ošetřením časových limitů.

Správa souborů a procesů

Čtěte, zapisujte a upravujte soubory v souborovém systému sandboxu. Spouštějte procesy na pozadí, sledujte výstup a spravujte dlouho běžící operace.

Zpřístupnění služeb pomocí náhledových URL adres

Zpřístupněte HTTP služby běžící ve vašem sandboxu pomocí automaticky generovaných náhledových URL adres, ideální pro interaktivní vývojová prostředí a hosting aplikací.

Spouštění kódu přímo

Spouštějte kód v Pythonu a JavaScriptu s bohatými výstupy včetně grafů, tabulek a obrázků. Stav mezi jednotlivými spuštěními zůstává zachovaný, což se hodí pro kód generovaný AI i interaktivní workflow.

Vytvářejte interaktivní terminály

Vytvářejte terminálová rozhraní v prohlížeči, která se přes WebSocket připojují přímo ke shellům sandboxu. Sestavte kolaborativní terminály, interaktivní vývojová prostředí a přístup ke shellu v reálném čase s automatickým opětovným připojením.

Trvalé úložiště s objektovým úložištěm

Připojte objektové úložiště kompatibilní s S3 (R2, S3, GCS a další) jako lokální souborové systémy. K bucketům přistupujte pomocí standardních souborových operací a data zůstanou zachována napříč životními cykly sandboxu. Vyžaduje nasazení do produkčního prostředí.

Sledování souborů v reálném čase

Sledujte změny souborů a adresářů pomocí nativních událostí souborového systému. Ideální pro vývojové servery s hot reloadem, systémy pro automatizaci sestavení a nástroje pro sledování konfigurace.

Zpracování odchozího provozu

Blokujte, povolujte a zachytávejte odchozí HTTP požadavky ze sandboxů. Přihlašovací údaje si ponechte ve svém Workeru tak, že do obslužných rutin pro odchozí provoz vložíte autorizační hlavičky.


Případy užití

Vytvářejte výkonné aplikace pomocí Sandbox:

Spouštění kódu pomocí AI

Bezpečně a spolehlivě spouštějte kód vygenerovaný velkými jazykovými modely. Nativní integrace s Workers AI modely jako GPT-OSS umožňuje volání funkcí spolu s prováděním v sandboxu. Ideální pro AI agenty, asistenty pro psaní kódu a autonomní systémy, které potřebují spouštět nedůvěryhodný kód.

Analýza dat a notebooky

Vytvářejte interaktivní prostředí pro analýzu dat s pandas, NumPy a Matplotlib. Generujte grafy, tabulky a vizualizace s automatickým formátováním bohatého výstupu.

Interaktivní vývojová prostředí

Vytvářejte cloudová IDE, programovací playgroundy a nástroje pro spolupráci na vývoji s plnohodnotnými prostředími Linux a náhledovými URL adresami.

CI/CD a systémy sestavování

Spouštějte testy, kompilujte kód a provádějte build pipeline v izolovaných prostředích s paralelním spouštěním a streamovanými logy.


Containers

Serverless kontejnerový runtime, který pohání Sandbox a umožňuje spouštět libovolnou kontejnerizovanou zátěž na edge.

Workers AI

Spouštějte modely strojového učení a LLM v síti. Zkombinujte je se Sandboxem pro bezpečné pracovní postupy spouštění AI kódu.

Durable Objects

Stavová koordinační vrstva, která Sandboxu umožňuje udržovat trvalá prostředí se silnou konzistencí.


Další zdroje

Kódovací agenti

Nainstalujte Cloudflare Skills ↗ pro svého agenta (Nastavení agenta). Použijte sandbox-stable s hlavní dokumentací na tomto webu, pokud používáte aktuální stabilní balíček. Použijte sandbox-next pro @cloudflare/sandbox@next (doporučeno pro nové projekty). Až budete připraveni portovat existující aplikaci, použijte sandbox-migrate-to-next.

Návody

Prohlédněte si kompletní příklady včetně spouštění kódu pomocí AI, analýzy dat a interaktivních prostředí.

Návody

Naučte se řešit konkrétní problémy a implementovat funkce se Sandbox SDK.

1.0 preview

Nainstalujte @cloudflare/sandbox@next a připravte se na vydání Sandbox SDK 1.0.

Základní pojmy

Zjistěte více o klíčových konceptech a architektuře Sandbox SDK.

Konfigurace

Zjistěte více o možnostech konfigurace Sandbox SDK.

Úložiště GitHub

Prohlédněte si zdrojový kód SDK, nahlaste problémy nebo přispějte do projektu.

Ceny

Seznamte se s cenami Sandbox založenými na podkladové platformě Containers.

Limity

Zjistěte více o limitech zdrojů, kvótách a doporučených postupech pro práci v rámci nich.

Komunita na Discordu

Spojte se s komunitou na Discordu. Ptejte se, sdílejte, na čem právě pracujete, a získejte pomoc od dalších vývojářů.

Obsah

79 stránek zrcadlených z dokumentace Cloudflare pro sandbox.

Pages

1.0 preview

Referenční dokumentace API

Sandbox bridge

Základní pojmy

Konfigurace

Návody

Platforma

Návody