Workspace as a Zerops service

A workspace is one Zerops service of the type Box Workspace (zbox@1): a single Ubuntu VM in your project. It is a managed service, like a database. Zerops runs the VM and the orchestrator inside it, and you manage the sandboxes through the workspace's API. This page covers the Zerops side: the service lifecycle, resizing, environment variables and networking.

What Zerops manages

Zerops provides and runs:

• The VM and its operating system. You don't deploy anything to it. A Box Workspace has no zerops.yaml, build, deploy or pipelines. The Zerops GUI offers no web terminal, file browser or backups for it.
• The orchestrator, which runs your sandboxes as microVMs and serves the API and the web console. It starts on its own whenever the VM boots. New orchestrator versions come with the platform. The orchestrator restarts itself to pick up a new version, and running sandboxes keep running while it does.
• The data disk. Bases, templates, sandboxes and snapshots live on a separate, encrypted disk of the VM (isolation). The disk persists across restarts, stops and resizes, and it is deleted only with the service.

To see which orchestrator version and VM image a workspace runs, use zbox workspace. The console's Workspace page shows the same:

# Version is the orchestrator, Image the VM image
zbox workspace

Everything inside the workspace is yours to manage through the API, the CLI or the console. That includes sandboxes, bases, templates, the workspace policy, domains, integrations and webhooks. In Zerops you manage only the service itself:

In Zerops (GUI, zCLI, import YAML)	In the workspace (API, zbox, console)
Restart, stop, start, reload, delete	Sandboxes, bases, templates, snapshots
Size: CPU cores, RAM, disk	The workspace policy and capacity
Service environment variables	Domains, integrations, connectors, webhooks
Subdomain access, logs	Events and sandbox metrics

Service lifecycle

Every lifecycle action of the service also affects the sandboxes inside it:

Action	The VM	Running sandboxes	Parked sandboxes
Reload	Keeps running. Zerops restarts the orchestrator with the current service variables.	Keep running, with their processes. Nothing is parked.	Stay parked with their memory
Restart	Reboots	Parked with their memory first, within 30 seconds, PARKED when the workspace is back	Stay parked with their memory
Stop, then Start	Shuts down, then boots	Parked with their memory on the stop, within 30 seconds. The start finds them PARKED.	Stay parked with their memory
Resize (below)	Reboots at once with the new size	Parked with their memory first, within 30 seconds, PARKED when the workspace is back	Stay parked with their memory
Delete	Deleted, with its data disk	Deleted, nothing is parked	Deleted

You find these actions on the service in the Zerops GUI. A reload is the one that leaves the sandboxes running. zCLI can stop and start the service:

zcli service stop --serviceId <workspace-service-id>
zcli service start --serviceId <workspace-service-id>

While the workspace is stopped, the API, the console and every sandbox URL are unreachable, and zbox exits with code 7 (unavailable). Operations still in flight when the VM goes down fail. Sandboxes that were still being created end up FAILED.

Before a restart, a stop, a resize or a move, the workspace parks its running sandboxes with their memory. First every running sandbox syncs its disk, all of them at once. Then the sandboxes are parked one after another. When the workspace is back, they are PARKED, and the next wake resumes them where they left off, with their processes and with everything they wrote.

If Zerops shuts down or reboots the server that runs the workspace, the VM shuts down the same way, and the workspace parks its running sandboxes as on a stop.

Parking has 30 seconds

The workspace stops within a minute, and its sandboxes get 30 seconds of it for their parks. How many fit depends on how much memory they hold: a park writes the sandbox's memory to the workspace disk. Sandboxes that the 30 seconds don't reach come back PARKED without a memory image. Their processes are gone and the next wake is a cold boot, but their disk keeps everything they wrote up to the disk sync at the start of the stop. With several large sandboxes, park them yourself before you restart, stop or resize the workspace.

Deleting the service deletes everything

Zerops does not back up a workspace. Deleting the service deletes its data disk and every base, template, sandbox and snapshot on it.

Resizing

A workspace is a single VM with fixed resources. It scales vertically only, and only when you change its size: CPU cores, RAM and disk. It never autoscales and never adds a second VM. You change the size in the service's scaling settings in the Zerops GUI. zbox setup sets the size at create time (getting started).

Resource	Minimum	Default	Technical maximum
CPU cores	2	2, shared	24
RAM	2 GiB	4 GiB	48 GiB
Disk	10 GiB	10 GiB	1024 GiB

Your Zerops account can have lower maximums than the technical ones. The scaling settings in the Zerops GUI show the limits that apply to you. A larger value is lowered to them silently: the change succeeds with the lowered size and no error, so check the size afterwards.

To resize through the Zerops API, use PUT /api/rest/public/service-stack/{id}/autoscaling ↗. The body must wrap the sizes in customAutoscaling, and the keys differ from import YAML: cpuCoreCount, memoryGBytes and diskGBytes under minResource and maxResource. Set both to the same size. A body without the wrapper, or with the import YAML keys such as minDisk, changes nothing.

curl -X PUT "https://api.app-prg1.zerops.io/api/rest/public/service-stack/<workspace-service-id>/autoscaling" \
  -H "Authorization: Bearer $ZEROPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customAutoscaling": {"verticalAutoscaling": {
        "minResource": {"cpuCoreCount": 4, "memoryGBytes": 8, "diskGBytes": 40},
        "maxResource": {"cpuCoreCount": 4, "memoryGBytes": 8, "diskGBytes": 40}}}}'

• Every change restarts the VM at once. CPU, RAM and disk alike, and the running sandboxes are parked with their memory first, as on a restart (service lifecycle). Plan resizes like restarts.
• Disk can only grow. The data disk is enlarged on the boot after the resize and keeps its contents. Zerops refuses a smaller disk size. To get a smaller disk, you need a new workspace.
• The size sets the capacity. The CPU, RAM and disk of the VM are what sandboxes are admitted against (capacity).

CPU can be shared or dedicated, like in any Zerops service. See resource management for CPU modes, and fixed resource allocation for how VM-based services differ from containers.

Environment variables

The service creates two environment variables of its own:

Variable	What it is
ZBOX_WORKSPACE_API_KEY	The workspace API key. It is generated when the service is created, and it is sensitive and editable.
ZBOX_WORKSPACE_VOLUME_KEY	The key that unlocks the encrypted data disk. It is generated when the service is created, and it is sensitive and not editable (isolation).

The orchestrator reads ZBOX_WORKSPACE_API_KEY only when it starts, so an edited key takes effect on the next reload, restart, or stop and start of the service, never on its own. A reload applies it without parking the sandboxes. See rotate the API key for the steps.

Your own service variables, and the project variables the service sees, are where sandbox secrets and integration credentials come from (secrets). Edits to them apply right away, without a reload or restart: new sandboxes and integrations use the new value, and sandboxes that were given the old one become stale. Connector credentials you store through the API are saved as service variables too (connectors). The bucket keys for an export to a bucket are service variables as well. For how Zerops variables work in general, see environment variables.

Subdomain access

A workspace publishes two HTTP ports. With Zerops subdomain access enabled, each gets its own Zerops subdomain:

Port	Serves	Example
8080	The API and the web console	https://zbox-6da-8080.prg1.zerops.app
8081	Sandbox ingress: the ports your sandboxes expose	https://<port>-<sandbox-id>-zbox-6da-8081.prg1.zerops.app

zbox setup turns subdomain access on and adds the 8081 subdomain as the workspace's first domain (domains).

Turning subdomain access off doesn't touch the sandboxes. Both subdomains stop answering (502): the API URL, the console at it, and every sandbox port URL on the Zerops subdomain. The workspace still lists the subdomain among its domains and in the sandboxes' URLs. The API stays reachable through Zerops with your Zerops login, the way the GUI and a logged-in CLI reach it. To give sandbox ports public URLs without it, route your own wildcard domain to port 8081. Turning subdomain access on again brings back the same URLs. For Zerops subdomains in general, see public access.

Project network

A workspace is a service in your project's private network, like any other Zerops service.

• Sandboxes reach other services of the project by hostname when their network mode includes the project network, which the default mode does. See project services for the details.
• Other services reach the workspace API at http://<hostname>:8080 with the API key as a bearer token, for example a runtime service that creates sandboxes for its users. Over the Zerops VPN, your own machine can reach it the same way.
• Other services reach sandbox ports at http://<hostname>:8081 with the bare {port}-{id} as the Host header, without any workspace domain. See reach a sandbox from the project.

Logs

The orchestrator logs to the service's runtime log in Zerops, which the project's log overview shows too. See logs.

Node moves

Zerops may move a workspace to another server, for example for maintenance. The data disk moves with the VM. The VM is stopped for the move and started again afterwards, so the running sandboxes are parked with their memory first, as on a stop (service lifecycle). On a server with another CPU, a sandbox may fail to resume from its memory image and end up FAILED. Wake it again, and it boots from its disk (failed sandboxes).