Sandbox Command Reference

All commands are under createos sandbox (alias: createos sb). Arguments in [brackets] are optional; those without brackets are required. Many commands prompt interactively when a required argument is omitted and stdin is a terminal.

At a glance

• Binary: createos, with 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

Lifecycle

sandbox create

Create a new sandbox VM.

Alias: createos sb c

createos sandbox create --shape s-1vcpu-1gb --name my-box

# Smallest sandbox
createos sandbox create --shape s-1vcpu-256mb
 
# With SSH key and public HTTPS URL
createos sandbox create --shape s-1vcpu-1gb \
  --name demo --ssh-key ~/.ssh/id_ed25519.pub --ingress
 
# Attach an S3 disk and join a private network
createos sandbox create --shape s-1vcpu-1gb \
  --disk my-bucket:/mnt/data --network my-net
 
# Auto-pause after 30 minutes of inactivity
createos sandbox create --shape s-1vcpu-1gb --auto-pause 30m

sandbox list

List sandboxes. Shows running sandboxes by default.

Alias: createos sb list

createos sandbox list
createos sandbox list --all
createos sandbox list --status paused

sandbox get

Show details for a single sandbox.

createos sandbox get my-box
createos sandbox get sb-01k...

Pass a sandbox name or ID. Runs interactively (picker) when no argument is given on a terminal.

sandbox edit

Change a running sandbox's settings.

createos sandbox edit my-box --ingress on
createos sandbox edit my-box --add-ssh-key ~/.ssh/id_ed25519.pub
createos sandbox edit my-box --auto-pause 30m
createos sandbox edit my-box --auto-pause off

Run with no flags on a terminal for an interactive settings menu.

sandbox pause

Snapshot and pause a running sandbox.

createos sandbox pause my-box

Pass a sandbox name or ID. Prompts interactively when no argument is given on a terminal. The sandbox can be resumed or forked from its paused snapshot.

sandbox resume

Resume a paused sandbox.

createos sandbox resume my-box

sandbox fork

Clone a paused sandbox into a new sandbox.

createos sandbox fork my-box
createos sandbox fork my-box --paused

The source sandbox must be paused. Run with no argument on a terminal to pick from your paused sandboxes.

sandbox rm

Delete one or more sandboxes. Irreversible.

createos sandbox rm my-box
createos sandbox rm sb-01k... sb-02k...
createos sandbox rm my-box --force

# Delete all failed sandboxes non-interactively
createos sandbox list --status failed --quiet | xargs createos sandbox rm --force

Run

sandbox exec

Run a one-shot command inside a sandbox.

createos sandbox exec <sandbox> -- <cmd> [args...]

The literal -- separator is required. The command's exit code is forwarded to the CLI process.

Use sandbox exec for quick non-interactive commands. For reconnectable output, background jobs, later input, signals, wait/stop controls, or PTY terminal behavior, use sandbox process.

Buffered exec output is capped at 1 MiB. Use --stream for larger output.

createos sandbox exec my-box -- uname -a
createos sandbox exec my-box --stream -- pip install requests
createos sandbox exec my-box -- python3 -c 'print("hello")'

sandbox shell

Open an interactive shell inside a sandbox.

Alias: createos sb sh

createos sandbox shell [<sandbox>]

By default opens a keyless PTY through the control plane. Your API token is the only authentication needed.

createos sandbox shell my-box            # keyless PTY (default)
createos sandbox shell my-box --ssh      # SSH path, auto-detect ~/.ssh key
createos sandbox shell my-box -i ~/.ssh/id_ed25519
createos sandbox shell my-box --user app

sandbox process

Manage long-running and reconnectable sandbox processes.

Alias: createos sandbox proc

Use this when a command should keep running independently of your CLI, or when you want to list it, reconnect to output, send input, wait for it, signal it, or stop it later.

Use sandbox exec for quick non-interactive one-shot commands. Use sandbox shell for an immediate interactive terminal that does not need to be listed or reattached. Use --pty (--tty, -t) when the managed command needs terminal behavior instead of plain stdout/stderr pipes.

Retained process output is bounded to 1 MiB per managed process and 32 MiB total per sandbox. When the retained window is exceeded, oldest output is discarded first; attaching from an expired sequence reports that the output offset has expired.

sandbox process run

Run a command as a managed process, attach to output, wait for it to exit, and return its exit code.

createos sandbox process run my-box -- npm test
createos sandbox process run my-box -- bash -lc 'npm install && npm test'
createos sandbox process run --pty my-box -- python3

sandbox process start

Start a managed command without attaching by default.

createos sandbox process start my-box -- python -m http.server 8000
createos sandbox process start --follow my-box -- npm run dev

Use this for background work you want to inspect later with process list, process attach, process wait, process signal, or process stop.

sandbox process shell

Start a managed PTY shell session.

createos sandbox process shell my-box
createos sandbox process shell my-box --no-attach

This does not replace sandbox shell. Use process shell when the shell should survive detach and be reattached later. It creates a process ID, appears in process list, and supports switching between running shell sessions from attach.

sandbox process attach

Reconnect to a managed process or shell session.

createos sandbox process attach my-box proc_abc123
createos sandbox process attach my-box

For PTY shell sessions, attach is interactive. For pipe processes, attach follows retained stdout/stderr output. If you omit the process ID in an interactive terminal, attach shows a picker of running managed processes.

Inside a managed PTY shell session:

Other process controls

createos sandbox process list my-box
createos sandbox process get my-box proc_abc123
createos sandbox process input my-box proc_abc123 --text "hello\n"
createos sandbox process close-stdin my-box proc_abc123
createos sandbox process resize my-box proc_abc123 --rows 40 --cols 120
createos sandbox process signal my-box proc_abc123 SIGINT
createos sandbox process wait my-box proc_abc123 --all
createos sandbox process stop my-box proc_abc123 --grace 1s

process input accepts exactly one of --text, --file <path|->, or --base64 <bytes>. process close-stdin only applies to pipe processes; PTYs do not have a separate stdin-close operation. process resize only applies to PTYs. process wait --all waits for the command and anything it started. process stop sends SIGTERM, waits for the grace period, then force-kills remaining descendants.

sandbox editor

Connect a remote editor (Zed, Cursor, or VS Code) to a sandbox over SSH.

createos sandbox editor [<sandbox>]

In one command this registers your local SSH key on the sandbox, starts sshd inside it, writes a ~/.ssh/config entry so plain ssh <sandbox-id> works, and launches your editor with the remote pre-selected. Each sandbox gets a dedicated throwaway keypair stored under ~/.config/createos/keys; the command never touches your ~/.ssh/ keys.

Requirements:

• The sandbox must be running.
• The sandbox image must ship sshd (the devbox:1 rootfs does).
• The shape needs more than 2 GiB of memory (e.g. s-4vcpu-4gb). Remote editor language servers OOM on 1 GiB shapes.

Transports (--via):

Interactive by default (prompts for sandbox, transport, and editor). Pass a sandbox plus --via, --editor, and --yes to run without prompts.

Flag options must appear before the sandbox positional argument.

# Interactive: pick sandbox, transport, and editor
createos sandbox editor
 
# Non-interactive: Zed over the gateway tunnel
createos sandbox editor my-box --via tunnel --editor zed --yes
 
# Write the SSH config entry without launching an editor
createos sandbox editor my-box --editor none
 
# Remove the SSH config entry and dedicated key
createos sandbox editor --remove my-box

After connecting, you can also reach the sandbox with any SSH-based tool:

ssh my-box
zed ssh://my-box/root
code --remote ssh-remote+my-box /root
cursor --folder-uri vscode-remote://ssh-remote+my-box/root

Files

sandbox push

Copy a local file into a sandbox.

Aliases: upload, cp-up

createos sandbox push <sandbox> <local-path> <remote-path>

The remote path must be absolute. Parent directories are created automatically. Max 500 MB per file.

# Upload a single file
createos sandbox push my-box ./main.py /workspace/main.py
 
# Stream a tarball from stdin
tar -c mydir | createos sandbox push my-box - /tmp/bundle.tar

Pass - as <local-path> to read from stdin.

sandbox pull

Copy a file out of a sandbox.

Aliases: download, cp-down

createos sandbox pull <sandbox> <remote-path> <local-path|->

The remote path must be absolute. Pass - as <local-path> to stream to stdout.

# Download to a file
createos sandbox pull my-box /workspace/result.csv ./result.csv
 
# Stream to stdout
createos sandbox pull my-box /workspace/result.csv - | head -5

sandbox sync

Two-way file sync between your local machine and a sandbox. Runs in the foreground; press Ctrl+C to stop.

createos sandbox sync [<sandbox>]

Built on Mutagen. Downloads Mutagen on first use. Uses the SSH path (requires an SSH key in the sandbox).

createos sandbox sync my-box --local ~/work/project --remote /root/work
createos sandbox sync my-box -i ~/.ssh/id_ed25519 --local . --remote /app
 
# Skip files you don't want synced (repeatable)
createos sandbox sync my-box --exclude '*.log' --exclude node_modules
 
# Push-only: laptop wins, never pull changes back
createos sandbox sync my-box --mode one-way
 
# Mirror: make the sandbox identical, deleting extra files there
createos sandbox sync my-box --mode mirror
 
# Run silently until Ctrl+C
createos sandbox sync my-box --quiet

Networking

sandbox tunnel

Forward a local TCP port to a port inside the sandbox. No SSH key required.

Alias: tun

createos sandbox tunnel [<sandbox>]

Press Ctrl+C to stop.

# Forward localhost:8080 → sandbox:8000
createos sandbox tunnel my-box --local 8080 --remote 8000
 
# Mirror the remote port (local = remote = 5432)
createos sandbox tunnel my-box --remote 5432
 
# Expose to the local network
createos sandbox tunnel my-box --remote 80 --bind 0.0.0.0

sandbox network

Manage private overlay networks that let sandboxes reach each other by IP.

Aliases: net, networks

createos sandbox network create prod-net
createos sandbox network ls
createos sandbox network attach my-box prod-net
createos sandbox network show prod-net
createos sandbox network detach my-box prod-net
createos sandbox network rm prod-net

Firewall (egress)

sandbox firewall

Control what a sandbox can reach on the internet (egress allowlist). Rules update live without restarting the sandbox.

Alias: fw

# See what the sandbox is allowed to reach
createos sandbox firewall show my-box
 
# Lock down to specific destinations
createos sandbox firewall set my-box api.github.com pypi.org
 
# Open the firewall completely
createos sandbox firewall clear my-box

firewall set accepts hostnames, IP addresses, and CIDR ranges. An empty list or firewall clear allows all outbound traffic.

Disks

sandbox disk

Manage S3-compatible buckets registered as mountable disks.

Alias: disks

disk create flags:

Run interactively (prompts for any missing field, masks the secret key) or pass all flags directly.

# Register a bucket interactively
createos sandbox disk create my-data
 
# Register non-interactively
createos sandbox disk create my-data \
  --bucket my-bucket \
  --endpoint https://s3.amazonaws.com \
  --access-key AKIAIOSFODNN7EXAMPLE \
  --secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
 
# Mount into a running sandbox
createos sandbox disk attach my-box my-data /mnt/data
 
# Unmount
createos sandbox disk detach my-box my-data /mnt/data

Custom images

sandbox template

Build custom sandbox images from a Dockerfile. The Dockerfile must use a base image from the operator's allowlist (e.g. nodeops/sandbox:debian), must be single-stage, and must not use COPY or ADD.

Aliases: templates, tpl

template submit flags:

# Submit and stream build logs until done
createos sandbox template submit my-image
 
# Submit using a custom Dockerfile path
createos sandbox template submit my-image -f docker/Sandbox.dockerfile
 
# Submit without waiting for the build
createos sandbox template submit my-image --no-follow
 
# Use a template when creating a sandbox
createos sandbox create --shape s-1vcpu-1gb --rootfs my-image
 
# Watch logs for an in-progress build
createos sandbox template logs my-image --follow

Once a template's status is ready, use its name as --rootfs when creating a sandbox.

Catalog

sandbox shapes

List available sandbox sizes.

createos sandbox shapes
createos sandbox shapes --output json

Prints a table of shape IDs with their vCPU count, RAM, and default disk size. Pass the shape ID to sandbox create --shape.

sandbox rootfs

List built-in OS images available for new sandboxes.

createos sandbox rootfs
createos sandbox rootfs --output json

Prints the catalog of base images. Pass a name to sandbox create --rootfs. User-built templates (from sandbox template submit) are listed separately.

Webhooks

Register HTTPS endpoints that receive a signed POST on sandbox, disk, network, and template lifecycle events. Unlike the rest of this page, these live under the top-level createos webhooks group (not createos sandbox). Full event catalog, delivery payload, and signature verification: REST API → Webhooks.

Endpoint-targeting commands accept the endpoint ID as a positional argument or --endpoint <id>, and prompt interactively when omitted on a terminal.

webhooks create

Create a webhook endpoint. Omit --event to subscribe to every action; repeat --event to filter. The signing secret is printed once, save it.

# Subscribe to all events
createos webhooks create --url https://example.com/webhook
 
# Subscribe to specific events
createos webhooks create --url https://example.com/webhook \
  --event sandbox.create --event sandbox.destroy
 
# Interactive (TTY): prompts for URL and events
createos webhooks create

webhooks list

List your webhook endpoints. Alias: createos webhooks ls

createos webhooks list

webhooks get

Show one endpoint's config plus its recent deliveries (status, attempts, timestamps).

createos webhooks get <endpoint-id>
createos webhooks get --endpoint <endpoint-id>

webhooks suspend

Stop deliveries without deleting the endpoint.

createos webhooks suspend <endpoint-id>

webhooks resume

Reactivate a suspended endpoint and reset its failure count. Endpoints are auto-suspended after repeated delivery failures.

createos webhooks resume <endpoint-id>

webhooks delete

Delete an endpoint and all its pending deliveries.

createos webhooks delete <endpoint-id>
createos webhooks delete <endpoint-id> --force   # skip confirmation (alias: -f)