Sandboxes

Create, run, and manage isolated sandboxes from the terminal. Sandboxes are powered by CreateOS — spin up a VM in seconds, run commands, sync files, open shells, and tear down when you're done.

Alias: createos sb

Quick start

Bash
Copy
1createos login
2
3# See available sizes
4createos sandbox shapes
5
6# Create a sandbox
7createos sandbox create --shape s-1vcpu-256mb --name my-box
8
9# Run a command inside it
10createos sandbox exec my-box -- uname -a
11
12# Open an interactive shell
13createos sandbox shell my-box
14
15# Delete when done
16createos sandbox rm my-box --force

Run createos sandbox create with no flags on a terminal to walk through an interactive setup wizard.

Lifecycle

Create

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

Examples:

Bash
Copy
1# Smallest sandbox
2createos sandbox create --shape s-1vcpu-256mb
3
4# With SSH key and public URL
5createos sandbox create --shape s-1vcpu-1gb \
6  --name demo --ssh-key ~/.ssh/id_ed25519.pub --ingress
7
8# Attach S3 disk and private network
9createos sandbox create --shape s-1vcpu-1gb \
10  --disk my-bucket:/mnt/data --network my-net

List

Bash
Copy
1createos sandbox list
2createos sandbox list --all
3createos sandbox list --status paused
4createos sandbox list --quiet   # IDs only — useful for scripting

Get details

Bash
Copy
1createos sandbox get my-box

Shows status, size, IP, public URL, firewall rules, bandwidth usage, and timestamps.

Edit 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 createos sandbox edit my-box with no flags for an interactive menu.

Pause and resume

Pause snapshots the sandbox to durable storage and tears down the live VM:

Bash
Copy
1createos sandbox pause my-box
2createos sandbox resume my-box

Paused sandboxes keep their name, ID, disks, networks, and environment variables.

Fork

Clone a paused sandbox into a new one:

Bash
Copy
1createos sandbox fork my-box
2createos sandbox fork my-box --paused

Delete

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

Use --force in scripts and CI to skip the confirmation prompt.

Run commands

One-shot exec

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

Anything after -- is the command. The sandbox's exit code is preserved.

Interactive shell

Bash
Copy
1createos sandbox shell my-box
2createos sandbox shell my-box --ssh
3createos sandbox shell my-box -i ~/.ssh/id_ed25519

By default, shell opens a keyless PTY through the control plane — your API token is the only auth. Pass --ssh to use the SSH path instead.

Files

Push (upload)

Bash
Copy
1createos sandbox push my-box ./main.py /workspace/main.py
2tar -c mydir | createos sandbox push my-box - /tmp/bundle.tar

Max 500 MB per file. Remote paths must be absolute.

Pull (download)

Bash
Copy
1createos sandbox pull my-box /workspace/result.csv ./result.csv
2createos sandbox pull my-box /workspace/result.csv - | head -5

Sync (bidirectional)

Two-way directory sync between your laptop and a sandbox (uses Mutagen over SSH):

Bash
Copy
1createos sandbox sync my-box --local ~/work/project --remote /root/work

Press Ctrl+C to stop. Refuses to sync sensitive paths like $HOME, .ssh, and system directories by default.

Networking

Port tunnel

Forward a local port to a port inside the sandbox — no SSH key required:

Bash
Copy
1createos sandbox tunnel my-box --local 8080 --remote 8000
2createos sandbox tunnel my-box --remote 5432
3createos sandbox tunnel my-box --remote 80 --bind 0.0.0.0

Press Ctrl+C to stop the tunnel.

Private networks

Sandboxes on the same network can reach each other by name:

Bash
Copy
1createos sandbox network create my-net
2createos sandbox network ls
3createos sandbox network attach my-box my-net
4createos sandbox network detach my-box my-net
5createos sandbox network rm my-net

Attach at creation with --network, or live-attach later with network attach.

Firewall (egress)

Control outbound internet access:

Bash
Copy
1createos sandbox firewall show my-box
2createos sandbox firewall set my-box pypi.org github.com
3createos sandbox firewall clear my-box

When no rules are set, all outbound traffic is allowed.

S3 disks

Register S3-compatible buckets and mount them into sandboxes:

Bash
Copy
1createos sandbox disk create my-disk \
2  --bucket my-bucket \
3  --endpoint https://s3.amazonaws.com \
4  --access-key AKIA... \
5  --secret-key ...
6
7createos sandbox disk ls
8createos sandbox disk attach my-box my-disk:/mnt/data
9createos sandbox disk detach my-box my-disk
10createos sandbox disk rm my-disk

Mount at creation with --disk my-disk:/mnt/data.

Custom images

Build your own sandbox rootfs from a Dockerfile:

Bash
Copy
1createos sandbox template submit my-rails -f Dockerfile
2createos sandbox template ls
3createos sandbox template show my-rails
4createos sandbox template logs my-rails
5createos sandbox template rm my-rails

Use a built template as --rootfs when creating a sandbox.

Catalog

Bash
Copy
1createos sandbox shapes    # Available sizes (vCPU / RAM / disk)
2createos sandbox rootfs    # Built-in OS images

Non-interactive / CI usage

Sandboxes work in scripts with explicit arguments and --force where needed:

Bash
Copy
1# Create headlessly
2createos sandbox create --shape s-1vcpu-256mb --name ci-box
3
4# Run a command and capture output
5createos sandbox exec ci-box -- npm test
6
7# JSON output
8createos sandbox list --output json | jq '.[].id'
9
10# Delete without prompt
11createos sandbox rm ci-box --force

Global flags