CreateOS Sandbox SDKs
Create, control, and clean up isolated Linux sandboxes from your application. Choose TypeScript, Python, or Go in any example—the selection stays in sync across the page.
| Language | Package | Requirements |
|---|---|---|
| TypeScript | @nodeops-createos/sandbox | Node.js 20+, Bun, Deno, edge runtimes, or a browser |
| Python | createos-sandbox | Python 3.10+ |
| Go | github.com/NodeOps-app/createos-go-sdk | Go 1.25+ |
All SDKs read CREATEOS_SANDBOX_API_KEY and
CREATEOS_SANDBOX_BASE_URL from the environment.
Install the SDK
Bash
1npm install @nodeops-createos/sandboxCreate a sandbox and run a command
The create call returns a connected sandbox that is ready to accept commands. Always destroy it when the work is complete.
TypeScript
1import { createClient } from "@nodeops-createos/sandbox";2
3const client = createClient();4const sandbox = await client.createSandbox({5 shape: "s-1vcpu-1gb",6 rootfs: "devbox:1",7});8
9try {10 const response = await sandbox.runCommand("echo", ["Hello from CreateOS"]);11 console.log(response.result.stdout);12} finally {13 await sandbox.destroy();14}Stream command output
Receive output as it is produced instead of waiting for the command to finish. These snippets use the running sandbox created above.
TypeScript
1import { createClient } from "@nodeops-createos/sandbox";2
3const client = createClient();4const sandbox = await client.createSandbox({5 shape: "s-1vcpu-1gb",6 rootfs: "devbox:1",7});8
9try {10 const command = "for n in 1 2 3; do echo result-$n; sleep 1; done";11 for await (const event of sandbox.streamCommand("sh", ["-c", command])) {12 if (event.type === "stdout") process.stdout.write(event.data);13 }14} finally {15 await sandbox.destroy();16}Upload files
Upload a file without shell escaping. These snippets assume the
sandbox or instance from the previous example is still running.
TypeScript
1import { createClient } from "@nodeops-createos/sandbox";2
3const client = createClient();4const sandbox = await client.createSandbox({5 shape: "s-1vcpu-1gb",6 rootfs: "devbox:1",7});8
9try {10 await sandbox.files.upload("/workspace/hello.txt", "Hello from TypeScript");11 const file = await sandbox.files.download("/workspace/hello.txt");12 console.log(new TextDecoder().decode(file));13} finally {14 await sandbox.destroy();15}Publish a live preview
Start a service and generate its public URL. Create the sandbox with ingress enabled before running this example.
TypeScript
1import { createClient } from "@nodeops-createos/sandbox";2
3const client = createClient();4const sandbox = await client.createSandbox({5 shape: "s-1vcpu-1gb",6 rootfs: "devbox:1",7 ingress_enabled: true,8});9
10try {11 await sandbox.processes.create({12 cmd: "python3",13 args: ["-m", "http.server", "8080", "--bind", "0.0.0.0"],14 });15 await sandbox.waitForPortReady(8080);16 console.log(sandbox.previewUrl(8080));17} finally {18 await sandbox.destroy();19}Run managed processes
Keep a stable process ID, reconnect to output, send input, and wait for the entire process tree.
TypeScript
1import { createClient } from "@nodeops-createos/sandbox";2
3const client = createClient();4const sandbox = await client.createSandbox({5 shape: "s-1vcpu-1gb",6 rootfs: "devbox:1",7});8
9try {10 const process = await sandbox.processes.create({11 cmd: "sh",12 args: ["-c", "echo finished"],13 });14 const result = await sandbox.processes.wait(process.process_id, {15 scope: "tree",16 });17 console.log(result.exit_code);18} finally {19 await sandbox.destroy();20}Spawn an interactive terminal
Create a PTY-backed shell, resize its terminal, send commands, and reconnect to its retained output after it exits.
TypeScript
1import { createClient } from "@nodeops-createos/sandbox";2
3const client = createClient();4const sandbox = await client.createSandbox({5 shape: "s-1vcpu-1gb",6 rootfs: "devbox:1",7});8
9try {10 const terminal = await sandbox.processes.create({11 cwd: "/workspace",12 pty: { rows: 24, cols: 80 },13 });14
15 await sandbox.processes.resize(terminal.process_id, {16 rows: 32,17 cols: 100,18 });19 await sandbox.processes.input(20 terminal.process_id,21 "echo 'CreateOS terminal ready'; uname -s; pwd; exit\n",22 );23
24 const result = await sandbox.processes.wait(terminal.process_id, {25 scope: "tree",26 });27 if (result.exit_code !== 0) {28 throw new Error(`Terminal exited with code ${result.exit_code}`);29 }30
31 for await (const event of sandbox.processes.connect(terminal.process_id)) {32 if (event.type === "data" && event.stream === "pty") {33 process.stdout.write(event.data);34 }35 }36} finally {37 await sandbox.destroy();38}Automate a cloud desktop
Open the NodeOps website in a graphical cloud browser and capture a validated
PNG screenshot. This example requires the desktop:1 image.
TypeScript
1import { createClient } from "@nodeops-createos/sandbox";2
3const client = createClient();4const sandbox = await client.createSandbox({5 shape: "s-2vcpu-4gb",6 rootfs: "desktop:1",7});8
9try {10 let screen;11 for (let attempt = 0; attempt < 60; attempt++) {12 screen = await sandbox.computer.screen({ screenId: "screen-0" })13 .catch(() => undefined);14 if (screen) break;15 await new Promise((resolve) => setTimeout(resolve, 2_000));16 }17 if (!screen) throw new Error("Desktop did not become ready");18
19 const target = "https://nodeops.network";20 await sandbox.computer.open(target, { screenId: "screen-0" });21 await new Promise((resolve) => setTimeout(resolve, 3_000));22
23 const screenshot = await sandbox.computer.screenshot({24 screenId: "screen-0",25 timeoutMs: 45_000,26 });27 const view = new DataView(screenshot);28 const width = view.getUint32(16, false);29 const height = view.getUint32(20, false);30 console.log(`Opened ${target} and captured a ${width}x${height} screenshot`);31} finally {32 await sandbox.destroy();33}