CreateOS Sandbox CLI

The createos binary is the command-line interface for CreateOS. Sandbox commands live under the sandbox subcommand (aliased to sb):

Bash
1createos sandbox <subcommand> [flags]
2# or the shorter alias
3createos sb <subcommand> [flags]

At a glance

Binary: createos (sandbox commands aliased to sb)
Install: curl -sfL https://raw.githubusercontent.com/NodeOps-app/createos-cli/main/install.sh | sh -
Auth: createos login (browser) or createos login --token <token>
Sandbox API: https://api.sb.createos.sh

Installation

curl (Linux / macOS)

Bash
1curl -sfL https://raw.githubusercontent.com/NodeOps-app/createos-cli/main/install.sh | sh -

Homebrew (macOS)

Bash
1brew tap nodeops-app/tap
2brew install createos

Upgrade

Bash
1createos upgrade

Authentication

Bash
1createos login

Opens your browser to complete OAuth sign-in. Your session is saved automatically to ~/.createos/.

API token

Get your token from createos.nodeops.network/profile, then:

Bash
1createos login --token <your-api-token>

CI / non-interactive environments

Pass --token directly. Browser login is not available in headless environments.

Bash
1# Set token as an environment variable and reference it
2createos login --token "$CREATEOS_TOKEN"

Commands that would normally prompt for confirmation (like sandbox rm) require --force in non-interactive mode.

Bash
1createos whoami

Quickstart

Bash
1# 1. Sign in
2createos login
3
4# 2. List available sizes
5createos sandbox shapes
6
7# 3. Create a sandbox
8createos sandbox create --shape s-1vcpu-1gb --name my-box
9
10# 4. Run a command
11createos sandbox exec my-box -- uname -a
12
13# 5. Open a shell
14createos sandbox shell my-box
15
16# 6. Delete when done
17createos sandbox rm my-box --force

`exec`, `shell`, `process`, and `PTY`

Use the simplest command that matches the session you need:

Need	Command
Quick non-interactive command	`createos sandbox exec <sb> -- <cmd>`
Immediate interactive shell, no reconnect needed	`createos sandbox shell <sb>`
Managed command with retained output and controls	`createos sandbox process run <sb> -- <cmd>`
Background command you will inspect later	`createos sandbox process start <sb> -- <cmd>`
Persistent shell you can detach from and reattach to	`createos sandbox process shell <sb>`
REPL, curses app, or terminal-aware command	`createos sandbox process run --pty <sb> -- <cmd>`

sandbox exec is best for one-shot automation. Buffered exec output is capped at 1 MiB; use --stream for larger output. sandbox process is for commands that should have a process ID: attach, list, input, wait, signal, and stop all work after the command starts. Retained process output is bounded to 1 MiB per process and 32 MiB per sandbox. Add --pty only when the command needs terminal behavior; otherwise the default pipe process keeps stdout and stderr separate.

Global flags

These flags are accepted by every createos command:

Flag	Short	Description
`--output <fmt>`	`-o`	Output format: `json` or `table` (default). Auto-switches to JSON when stdout is not a terminal.
`--debug`	`-d`	Print HTTP request/response details (token is masked).
`--api-url <url>`		Override the main API base URL.
`--sandbox-api-url <url>`		Override the sandbox API base URL (default: `https://api.sb.createos.sh`).
`--sandbox-gateway <host:port>`		SSH gateway address used by `sandbox shell --ssh` (default: `gateway.sb.createos.sh:2222`).

Non-interactive / CI usage

Use --output json for machine-readable output that is safe to pipe and parse.
Pass --force (or -y) to commands that prompt for confirmation (e.g. sandbox rm).
Set CREATEOS_TOKEN and authenticate with createos login --token "$CREATEOS_TOKEN" before running other commands.

Bash
1# Example: list running sandboxes as JSON in CI
2createos sandbox list --output json
3
4# Delete all failed sandboxes non-interactively
5createos sandbox list --status failed --quiet | xargs createos sandbox rm --force

Full command reference

See Command Reference for every subcommand, flag table, and usage example.

100,000+ Builders. One Platform.