Skip to content
LogoLogo

Quickstart

Create your first sandbox, run a command in it, and tear it down. This page shows the CLI and the SDK side by side. Both authenticate with a CreateOS API token (generate one from your dashboard).

CLI

1. Install

curl -sfL https://raw.githubusercontent.com/NodeOps-app/createos-cli/main/install.sh | sh -
# or with Homebrew
brew tap nodeops-app/tap && brew install createos

2. Sign in

createos login

This opens a browser to sign in. For CI, pass a token instead: createos login --token <your-token>.

3. Create a sandbox

# See available sizes
createos sandbox shapes
 
# Create one
createos sandbox create --shape s-1vcpu-1gb --name my-box

4. Run a command

createos sandbox exec my-box -- uname -a

5. Start a reconnectable process

Use process when you want a command to keep a process ID so you can attach, wait, signal, or stop it later.

createos sandbox process start my-box -- python -m http.server 8000
createos sandbox process list my-box

For a quick one-shot command, stay with exec. For a persistent shell you can detach from and reattach to, use createos sandbox process shell my-box. Add --pty to process run or process start for REPLs, curses apps, or other terminal-aware commands.

6. Open a shell

createos sandbox shell my-box

7. Clean up

createos sandbox rm my-box --force

See the CLI reference for the full command set.

SDK

1. Install

npm install @nodeops-createos/sandbox

2. Create, run, destroy

import { createClient } from "@nodeops-createos/sandbox";
 
const client = createClient({
  apiKey: process.env.CREATEOS_SANDBOX_API_KEY!,
  // baseUrl defaults to https://api.sb.createos.sh
});
 
const sandbox = await client.createSandbox({ shape: "s-1vcpu-1gb" });
 
const { result } = await sandbox.runCommand("uname", ["-a"]);
console.log(result.stdout);
 
await sandbox.destroy();

See the SDK quickstart and tutorial to go further.

REST API

Every operation is also a plain HTTP call:

# Create
curl -X POST https://api.sb.createos.sh/v1/sandboxes \
  -H "X-Api-Key: $CREATEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shape": "s-1vcpu-1gb"}'
 
# Run a command (replace :id with the returned sandbox id)
curl -X POST https://api.sb.createos.sh/v1/sandboxes/:id/exec \
  -H "X-Api-Key: $CREATEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cmd": "uname", "args": ["-a"]}'

See the REST API reference for every endpoint.

Next

  • Before a real workload, read Limits & defaults: the free plan runs one sandbox at a time, Pro runs twenty, and egress is open until you pass an allowlist.
  • Lock outbound traffic with two rules for a Python job: see Egress.
  • Rate card and credits: createos.sh/pricing/sandbox. SDK source: GitHub · npm.