CreateOS Sandbox CLI

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

createos sandbox <subcommand> [flags]
# or the shorter alias
createos 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

Command availability depends on your CLI version. Check createos version and createos sandbox --help before using newer groups such as process, editor, setup, or devices. If your installation lacks a command, update the CLI or use its documented REST/SDK equivalent.

curl (Linux / macOS)

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

Homebrew (macOS)

brew tap nodeops-app/tap
brew install createos

Upgrade

createos upgrade

Authentication

createos login

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

API token

Get your token from createos.sh/app/profile, then:

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

CI / non-interactive environments

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

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

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

createos whoami

Quickstart

# 1. Sign in
createos login
 
# 2. List available sizes
createos sandbox shapes
 
# 3. Create a sandbox
createos sandbox create --shape s-1vcpu-1gb --name my-box
 
# 4. Run a command
createos sandbox exec my-box -- uname -a
 
# 5. Open a shell
createos sandbox shell my-box
 
# 6. Delete when done
createos 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.

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

Full command reference

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