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

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

Bash
Copy
1# Smallest sandbox
2createos sandbox create --shape s-1vcpu-256mb
3
4# With SSH key and public HTTPS URL
5createos sandbox create --shape s-1vcpu-1gb \
6  --name demo --ssh-key ~/.ssh/id_ed25519.pub --ingress
7
8# Attach an S3 disk and join a private network
9createos sandbox create --shape s-1vcpu-1gb \
10  --disk my-bucket:/mnt/data --network my-net
11
12# Auto-pause after 30 minutes of inactivity
13createos sandbox create --shape s-1vcpu-1gb --auto-pause 30m

sandbox list

List sandboxes. Shows running sandboxes by default.

Alias: createos sb list

Bash
Copy
1createos sandbox list
2createos sandbox list --all
3createos sandbox list --status paused

sandbox get

Show details for a single sandbox.

Bash
Copy
1createos sandbox get my-box
2createos 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.

Bash
Copy
1createos sandbox edit my-box --ingress on
2createos sandbox edit my-box --add-ssh-key ~/.ssh/id_ed25519.pub
3createos sandbox edit my-box --auto-pause 30m
4createos 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.

Bash
Copy
1createos 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.

Bash
Copy
1createos sandbox resume my-box

sandbox fork

Clone a paused sandbox into a new sandbox.

Bash
Copy
1createos sandbox fork my-box
2createos 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.

Bash
Copy
1createos sandbox rm my-box
2createos sandbox rm sb-01k... sb-02k...
3createos sandbox rm my-box --force

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

Run

sandbox exec

Run a one-shot command inside a sandbox.

Bash
Copy
1createos sandbox exec <sandbox> -- <cmd> [args...]

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

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

sandbox shell

Open an interactive shell inside a sandbox.

Alias: createos sb sh

Bash
Copy
1createos sandbox shell [<sandbox>]

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

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

Files

sandbox push

Copy a local file into a sandbox.

Aliases: upload, cp-up

Bash
Copy
1createos sandbox push <sandbox> <local-path> <remote-path>

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

Bash
Copy
1# Upload a single file
2createos sandbox push my-box ./main.py /workspace/main.py
3
4# Stream a tarball from stdin
5tar -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

Bash
Copy
1createos sandbox pull <sandbox> <remote-path> <local-path|->

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

Bash
Copy
1# Download to a file
2createos sandbox pull my-box /workspace/result.csv ./result.csv
3
4# Stream to stdout
5createos 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.

Bash
Copy
1createos sandbox sync [<sandbox>]

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

Bash
Copy
1createos sandbox sync my-box --local ~/work/project --remote /root/work
2createos sandbox sync my-box -i ~/.ssh/id_ed25519 --local . --remote /app
3
4# Skip files you don't want synced (repeatable)
5createos sandbox sync my-box --exclude '*.log' --exclude node_modules
6
7# Push-only: laptop wins, never pull changes back
8createos sandbox sync my-box --mode one-way
9
10# Mirror: make the sandbox identical, deleting extra files there
11createos sandbox sync my-box --mode mirror
12
13# Run silently until Ctrl+C
14createos 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

Bash
Copy
1createos sandbox tunnel [<sandbox>]

Press Ctrl+C to stop.

Bash
Copy
1# Forward localhost:8080 → sandbox:8000
2createos sandbox tunnel my-box --local 8080 --remote 8000
3
4# Mirror the remote port (local = remote = 5432)
5createos sandbox tunnel my-box --remote 5432
6
7# Expose to the local network
8createos 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

Bash
Copy
1createos sandbox network create prod-net
2createos sandbox network ls
3createos sandbox network attach my-box prod-net
4createos sandbox network show prod-net
5createos sandbox network detach my-box prod-net
6createos 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

Bash
Copy
1# See what the sandbox is allowed to reach
2createos sandbox firewall show my-box
3
4# Lock down to specific destinations
5createos sandbox firewall set my-box api.github.com pypi.org
6
7# Open the firewall completely
8createos 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.

Bash
Copy
1# Register a bucket interactively
2createos sandbox disk create my-data
3
4# Register non-interactively
5createos sandbox disk create my-data \
6  --bucket my-bucket \
7  --endpoint https://s3.amazonaws.com \
8  --access-key AKIAIOSFODNN7EXAMPLE \
9  --secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
10
11# Mount into a running sandbox
12createos sandbox disk attach my-box my-data /mnt/data
13
14# Unmount
15createos 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:

Bash
Copy
1# Submit and stream build logs until done
2createos sandbox template submit my-image
3
4# Submit using a custom Dockerfile path
5createos sandbox template submit my-image -f docker/Sandbox.dockerfile
6
7# Submit without waiting for the build
8createos sandbox template submit my-image --no-follow
9
10# Use a template when creating a sandbox
11createos sandbox create --shape s-1vcpu-1gb --rootfs my-image
12
13# Watch logs for an in-progress build
14createos 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.

Bash
Copy
1createos sandbox shapes
2createos 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.

Bash
Copy
1createos sandbox rootfs
2createos 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.