macOS Sandboxes

A macOS sandbox is a macOS 26 virtual machine you can manage from the command line with the wb CLI. You can run commands in it, copy files in and out, and open an interactive shell. Pausing a sandbox saves its disk and stops it. Resuming starts a new VM from that disk, so your files and the tools you installed are still there.

Sandboxes get the same full macOS 26 image as the macOS 26 runners, with Xcode and the same suite of preinstalled tools.

Quick start

Install the wb CLI on macOS or Linux:

curl -fsSL https://packages.warpbuild.com/wb-cli/install.sh | bash

Create an API key with the CI scope and export it:
```
export WB_TOKEN=wkey-...
```
Create a sandbox. wb waits until it is ready:
```
wb sbx create demo
```
A name must be unique among your organization's live sandboxes.

Run commands, copy files in and out, or open a shell:

wb sbx exec demo sw_vers
wb sbx fs put demo ./app.zip app.zip
wb sbx exec demo unzip app.zip
wb sbx fs cat demo build.log > build.log
wb sbx pty create demo

Pause the sandbox when you're done and resume it later. Kill it when you no longer need it:
```
wb sbx pause demo
wb sbx resume demo
wb sbx kill demo --yes
```

Runner labels and pricing

Runner label	vCPU	Memory	Disk	Price
`warp-macos-26-arm64-6x` (default)	6	14 GB	60 GB	$0.08/minute
`warp-macos-26-arm64-12x`	12	28 GB	60 GB	$0.16/minute

Sandboxes run on the macOS 26 labels of the macOS M4 Pro runners. Pass one with --runner-label when you create the sandbox, for example wb sbx create demo --runner-label warp-macos-26-arm64-12x. A sandbox keeps its runner label when you resume it.

A running sandbox is billed per second at the macOS 26 runner rate. A paused sandbox has no compute charge.

Saved disks

Each pause compresses the sandbox's disk and save it to WarpBuild cache, billed at cache pricing: $0.20 per GB-month of storage, plus $0.0001 per cache operation to save and restore it. For example, a 5 GB save kept for a week costs about $0.23.

What persists

When you resume a sandbox:

Kept:
- home folder (/Users/runner)
- Homebrew under /opt/homebrew, including packages you installed with brew.
Not kept:
- ~/Library, ~/.warpbuild, /tmp, /usr/local and /Applications
- running processes, memory is not persisted

Lifetime

A sandbox lasts 7 days from when you created it, running or paused. After that it is expired and can't be resumed. Check wb sbx info <name> to see when the sandbox expires.

CLI reference

Every command accepts -f json or -f pretty for the output format, and -v to print API calls to stderr. Output goes to stdout and messages to stderr, so wb sbx list -f json | jq works. Before use, you need to export your API token as WB_TOKEN env variable. wb version prints the CLI's version. wb checks for a new release once a day and tells you when one is available; run the install command again to update.

Command	What it does
`wb sbx create <name> [--runner-label <label>] [--wait <seconds>]`	Creates a sandbox and waits until it is ready, for up to 900 seconds by default.
`wb sbx list [--all]`	Lists your sandboxes that haven't been killed. With `--all`, owners and admins see every sandbox in the organization.
`wb sbx info <name>`	Shows a sandbox's state, size and endpoint, and when it was created, last saved and expires.
`wb sbx pause <name> [--wait <seconds>]`	Saves the sandbox's disk and stops it, waiting for up to 900 seconds by default.
`wb sbx resume <name> [--wait <seconds>]`	Starts the sandbox again from its last save, waiting for up to 900 seconds by default. A failed sandbox that has a save can be resumed too.
`wb sbx kill <name> --yes`	Deletes the sandbox without saving its disk.
`wb sbx sizes`	Lists the runner labels you can use, with their vCPU and memory.
`wb sbx exec <name> <command...>`	Runs a command, streams its output and exits with its exit code. Everything after `<name>` is the command, flags included, so `exec`'s own options go before `<name>`.
`wb sbx exec -c <dir> <name> <command...>`	Runs the command in `<dir>`.
`wb sbx exec -u <user> <name> <command...>`	Runs the command as the macOS user `<user>`.
`wb sbx exec -i <name> <command...>`	Streams your local stdin to the command.
`wb sbx exec --background <name> <command...>`	Starts the command, prints its pid and returns.
`wb sbx commands list <name>`	Lists running processes.
`wb sbx commands connect <name> <pid>`	Follows a process's output and exits with its exit code.
`wb sbx commands send-stdin <name> <pid> <data>`	Writes to a process's stdin. Use `-` as the data to stream your local stdin.
`wb sbx commands close-stdin <name> <pid>`	Closes a process's stdin.
`wb sbx commands kill <name> <pid>`	Kills a process.
`wb sbx pty create <name>`	Opens an interactive shell. Press Ctrl-] to detach.
`wb sbx pty connect <name> <pid>`	Reattaches to a shell.
`wb sbx pty kill <name> <pid>`	Kills a shell.
`wb sbx fs ls <name> <dir>`	Lists a directory. In `fs` commands, relative paths are in the home folder. Quote `~`, or your shell replaces it with your own home folder.
`wb sbx fs cat <name> <path>`	Prints a file.
`wb sbx fs put <name> <local> <remote>`	Uploads a file. `<remote>` is the path of the new file, for example `wb sbx fs put demo ./notes.txt notes.txt`.
`wb sbx fs stat <name> <path>`	Shows a file's metadata.
`wb sbx metrics <name>`	Shows CPU and memory use.
`wb sbx envs <name>`	Shows the environment variables.

macOS Sandboxes

Quick startCopy Anchor Link

Runner labels and pricingCopy Anchor Link

Saved disksCopy Anchor Link

What persistsCopy Anchor Link

LifetimeCopy Anchor Link

CLI referenceCopy Anchor Link