CLI

Sandboxes

The sb (alias for sandboxes) command group — lifecycle, exec, files, PTY, snapshots, backups, restore.

froglet sb ls
froglet sb new --template <slug> [--size xs|s|m|l] [--name <slug>] [--volume <vol[:path[:mode]]>]
froglet sb get <id|slug>
froglet sb start <id|slug>             # resume a `suspended` sandbox
froglet sb stop <id|slug>              # → `suspended` (state preserved)
froglet sb rm <id|slug>                # destroy
froglet sb exec <id|slug> '<cmd>'      # quote the whole command
froglet sb ls2 <id|slug> <path>        # list a directory in the guest
froglet sb cat <id|slug> <path> [-o <local-file>]
froglet sb put <id|slug> <path> [--from <local-file>]
froglet sb pty-ticket <id|slug>        # mint a wss:// PTY URL (60s ttl)
froglet sb snap <id|slug> [--label x]    # fast on-host snapshot (NOT uploaded)
froglet sb backup <id|slug> [--label x]  # R2-backed backup
froglet sb backups <id|slug>             # list backups
froglet sb restore <id|slug> --from <snapshot-id>

Accepts the slug (demo) or the full UUID.

Sizes

Size	vCPU	Memory	Disk
xs	1	512 MB	10 GB
s	2	2048 MB	20 GB
m	4	8192 MB	40 GB
l	8	16 GB	80 GB

First sandbox

$ froglet sb new --template ubuntu-24.04 --size xs --name demo
✓ created demo · id fb7e61a0-…

$ froglet sb exec demo 'uname -a'
Linux fb7e61a0-… 6.6.62 #1 SMP … x86_64 GNU/Linux
[exit 0 · 6ms]

$ froglet sb rm demo
✓ destroying fb7e61a0-…

Boot is ~1s. rm is final.

Files in and out

$ cat localfile.txt | froglet sb put demo /tmp/input.txt
wrote 128 bytes to sandbox:/tmp/input.txt

$ froglet sb exec demo 'tac /tmp/input.txt > /tmp/output.txt'

$ froglet sb cat demo /tmp/output.txt -o ./reversed.txt
wrote 128 bytes to ./reversed.txt

put reads from stdin by default; pass --from <file> to read from a local path.

PTY

$ froglet sb pty-ticket demo
wss://…?ticket=eyJhbGciOiJI…

The URL is a one-shot WebSocket with a 60s TTL — open it in any terminal frontend (xterm.js, etc.) to get a live shell. The dashboard's terminal panel uses the same ticket.

Snapshots vs backups

sb snap — fast on-host checkpoint. Not uploaded. Lost if the host dies. Use for quick "try something, roll back".
sb backup — full snapshot uploaded to R2. Survives host loss. Restore drops the sandbox back to the exact instant the backup was taken (RAM + disk).

$ froglet sb backup demo --label pre-experiment
✓ backup queued · 7054919a
  size  89.0 MB
  uri   r2://froglet-volumes/backups/fb7e61a0-…/7054919a-….tar.zst

$ froglet sb backups demo
$ froglet sb restore demo --from 7054919a-…
✓ restore queued · f2a05926 · in_progress

Boot with a volume already mounted

froglet sb new --template ubuntu-24.04 --size s --name worker \
  --volume 3ff092d9-…:/data:rw

--volume is repeatable — pass it once per mount.

Gotchas

Quote sb exec. clap parses stray flags otherwise. sb exec demo 'uname -a', not sb exec demo -- uname -a.
sb stop can exceed 60s because the host takes an auto-snapshot before suspending. The CLI spinner waits it out.
sb ls2 is a temporary name — the SDK calls this listFiles. Rename pending.
Response bodies for exec and ls2 are snake_case (exit_code, modified_ms). The CLI hides this; matters only if you hit the REST API directly.