Zerops Box

Beta

Zerops Box is in beta, and we're still shaping it. Its behavior, API and CLI may change as we go, and it doesn't come with an SLA yet. We'd love to hear your feedback, and more documentation is on the way.

Zerops Box runs sandboxes for AI agents on Zerops. One Zerops Box service is one workspace: a persistent Ubuntu virtual machine. Inside the workspace, each sandbox is a Firecracker microVM that you create, park, wake, fork and snapshot with the zbox CLI. Each workspace also serves a web console.

The service type is called Box Workspace, after its unit: one service is one workspace. It is a managed service, like a database. There is nothing to deploy: it has no zerops.yaml, no build and no deploy pipeline.

Install the zbox CLI

Workspaces and sandboxes are managed with the zbox CLI (zbox-cli repository). It runs on Linux, macOS and Windows, on amd64 and arm64.

On Linux and macOS:

curl -fsSL https://box.zerops.io/install.sh | sh

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:

irm https://box.zerops.io/install.ps1 | iex

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. Run zbox --version to check the installed version.

You can also download a binary from the releases page by hand, or install from source with Go 1.25 or newer:

go install github.com/zeropsio/zbox-cli/cmd/zbox@latest

Log in to your Zerops account. zbox login opens a consent page in the Zerops GUI where you confirm the code the CLI printed. If you don't have an account yet, zbox register opens the same page to create one first.

zbox login
# or log in with a personal access token created in the Zerops GUI
zbox login --token <personal-access-token>

Create a workspace

The quickest way is zbox setup. It creates a Box Workspace service, by default named zbox in a new project named zbox-<timestamp>, and waits until the default sandbox image is pulled as the first base.

zbox setup
# use an existing project and a custom service name
zbox setup --project-id <project-id> --name mybox
# set the VM size; the defaults are 2 CPU cores, 4 GiB RAM and 10 GiB disk
zbox setup --cpu 4 --ram 8 --disk 20

Check the login, the workspace, its capacity and what is in use with:

zbox workspace status

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:

zerops-import.yaml

services:
  - hostname: box
    type: zbox@1

Import it with the zCLI, or paste the YAML in the GUI (Import services in the left menu of your project):

zcli project service-import zerops-import.yaml

Supported versions:

• zbox@1, zbox@latest

Work with sandboxes

Create a sandbox, run commands in it and open its ports:

# new sandbox "app" with port 3000
zbox new app -p 3000
zbox exec app -- echo hello
zbox shell app
# open the port URL in the browser with a one-time ticket valid for 60 seconds
zbox open app 3000
# keep disk and memory state but free the RAM; zbox wake app resumes it
zbox park app
zbox remove app

Without --base, the only ready base is used. Ports are written as port[/protocol][/access]. By default, opening a port needs a one-time ticket.

To start sandboxes without a cold boot, create a warm template. Sandboxes created from it resume from memory:

zbox template create --name dev --base <base-name-or-digest> --cpus 2 --memory 4g --warm
zbox new app --template dev -p 3000/public

Commands have short aliases, like ls for list, rm for remove, ws for workspace and create for new. Every command accepts --json for scripting and -q to print only IDs.

Scaling

A workspace is a single VM, so it scales vertically only: CPU cores, RAM and disk. There is no horizontal scaling and no minimum or maximum container count. Disk space can be increased but never decreased. See Resource management for how vertical scaling works on Zerops.