Getting started
This page takes you from zero to a running sandbox with a port you can open in the browser. You install the zbox CLI, log in to Zerops, create a workspace and start a sandbox in it.
You need a Zerops account. If you don't have one yet, zbox register creates it (see Log in).
Install the zbox CLI
The zbox CLI (zbox-cli repository) runs on Linux, macOS and Windows, on amd64 and arm64.
On Linux and macOS:
The script downloads the latest release, verifies its SHA-256 checksum and installs zbox to /usr/local/bin if it's writable, otherwise to ~/.local/bin. If that directory isn't on your PATH, the script tells you how to add it.
On Windows, in PowerShell:
The binary is installed to %LOCALAPPDATA%\Programs\zbox and added to your user PATH. Open a new terminal for the change to apply.
Both scripts accept two environment variables: ZBOX_VERSION installs a specific release (for example v0.24) instead of the latest one, and ZBOX_INSTALL_DIR sets the install directory. Pre-releases (tags with a hyphen, like v0.24-rc1) are only installed when ZBOX_VERSION names them.
You can also download a binary and checksums.txt from the releases page by hand, or install from source with Go 1.25 or newer:
Run zbox --version to check the installed version.
Log in
zbox login opens a consent page in the Zerops GUI, where you sign in and confirm the code the CLI printed. zbox register opens the same page and lets you create an account first.
See Personal access tokens for how to create a token. The token and the email login suit machines without a browser. The email login can't answer two-factor authentication, so with 2FA on use the browser or a token. zbox register --email creates the account from the terminal in the same way.
Create a workspace
A workspace is one Zerops service of type Box Workspace. The quickest way to create one is zbox setup:
It creates a new project named zbox-<timestamp> (--project names it) with a Box Workspace service named zbox, turns on subdomain access and waits for the workspace to answer. Then it adds the subdomain of port 8081 as the workspace's first domain and pulls the default sandbox image as its first base. The new workspace becomes the current one for the CLI. Subdomain access gives sandbox ports their public URLs. With --no-subdomain it stays off, sandbox ports get no URL and zbox open has nothing to open.
For the minimum and maximum sizes, and what a later resize does, see resizing. --base and --build give the workspace your own bases in place of the default image, and --template warms templates on them, see Images.
Check the login, the workspace, its capacity and what is in use:
In the Zerops GUI or with import YAML
You can also create a workspace in the GUI: choose Add new service in your project and pick Box Workspace from the service catalog. Or describe it in a zerops-import.yaml:
Import it with the zCLI, or paste the YAML in the GUI (Import services in the left menu of your project):
Supported versions:
zbox@1,zbox@latest
A workspace created this way starts empty: it has no base and no domain for sandbox ports. Store it in the CLI and add both:
# find the service ID of the workspace
zbox workspace list
# store it in the CLI; it becomes the current one if you have no other
zbox workspace authorize <service-id>
# pull a base, here the default sandbox image
zbox base add https://storage.cdn.zerops.app/4ga3k-boxstorage/zbox/zbox-base.tar.gz --name default
# publish sandbox ports under the Zerops subdomain of port 8081
zbox workspace domain add <port-8081-subdomain> --form dash
The domain needs subdomain access turned on for the service. The GUI's service form leaves it off by default. To find the subdomain of port 8081, see Zerops subdomain. If you have several workspaces, see Several workspaces.
Run your first sandbox
A sandbox boots from a base. On a new workspace the only base is used; when there are several, pick one with --base. If you run zbox new before you have a workspace, the CLI offers to run the setup.
The sandbox gets the default size. --cpus, --memory and --disk set another one, see Create a sandbox.
Start a small web server as a detached process and open its port in the browser:
By default a port is a members port, which only those who can use the workspace reach: zbox open signs the browser in with a one-time ticket. To make a port public or reachable in other ways, see Access modes and Ports. More on exec, shells and detached processes in Running commands.
When you don't need the sandbox for a while, park it. Parking keeps its disk and memory and frees the RAM it took, so the server keeps running after the wake:
See Sandbox lifecycle for parking, forks, snapshots and TTLs.
Where to go next
- Managing and accessing the workspace: the web console, the HTTP API and
zbox mcpfor AI agents. - Images: bases and templates: your own images and warm templates.
- Sandbox lifecycle: park, wake, fork and snapshot.
- Networking and access: ports, SSH and egress.
Remove the workspace
zbox workspace teardown deletes the current workspace's service with everything in it: sandboxes, bases and snapshots. The CLI forgets the workspace. The project stays, together with any other services in it; delete an empty project in the Zerops GUI. You can also delete the service in the Zerops GUI like any other service.