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.

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.

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

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.

Bash
Copy
1createos sandbox process run my-box -- npm test
2createos sandbox process run my-box -- bash -lc 'npm install && npm test'
3createos sandbox process run --pty my-box -- python3

sandbox process start

Start a managed command without attaching by default.

Bash
Copy
1createos sandbox process start my-box -- python -m http.server 8000
2createos 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.

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

Bash
Copy
1createos sandbox process attach my-box proc_abc123
2createos 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

Bash
Copy
1createos sandbox process list my-box
2createos sandbox process get my-box proc_abc123
3createos sandbox process input my-box proc_abc123 --text "hello\n"
4createos sandbox process close-stdin my-box proc_abc123
5createos sandbox process resize my-box proc_abc123 --rows 40 --cols 120
6createos sandbox process signal my-box proc_abc123 SIGINT
7createos sandbox process wait my-box proc_abc123 --all
8createos 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.

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

Bash
Copy
1# Interactive: pick sandbox, transport, and editor
2createos sandbox editor
3
4# Non-interactive: Zed over the gateway tunnel
5createos sandbox editor my-box --via tunnel --editor zed --yes
6
7# Write the SSH config entry without launching an editor
8createos sandbox editor my-box --editor none
9
10# Remove the SSH config entry and dedicated key
11createos sandbox editor --remove my-box

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

Bash
Copy
1ssh my-box
2zed ssh://my-box/root
3code --remote ssh-remote+my-box /root
4cursor --folder-uri vscode-remote://ssh-remote+my-box/root

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.

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.

Bash
Copy
1# Subscribe to all events
2createos webhooks create --url https://example.com/webhook
3
4# Subscribe to specific events
5createos webhooks create --url https://example.com/webhook \
6  --event sandbox.create --event sandbox.destroy
7
8# Interactive (TTY): prompts for URL and events
9createos webhooks create

webhooks list

List your webhook endpoints. Alias: createos webhooks ls

Bash
Copy
1createos webhooks list

webhooks get

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

Bash
Copy
1createos webhooks get <endpoint-id>
2createos webhooks get --endpoint <endpoint-id>

webhooks suspend

Stop deliveries without deleting the endpoint.

Bash
Copy
1createos webhooks suspend <endpoint-id>

webhooks resume

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

Bash
Copy
1createos webhooks resume <endpoint-id>

webhooks delete

Delete an endpoint and all its pending deliveries.

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