Swarm on Zerops

Swarm is a service that gives you a pool of containers (or virtual machines) and an HTTP API to control them. You create a container, reserve it, run commands in it, snapshot it, fork it and remove it with plain HTTP calls that answer in seconds. It is built for workloads where containers come and go all the time: CI jobs, per-user or per-task workspaces, sandboxes for AI agents, and one-off commands that need a clean environment.

Note

Zerops Swarm has nothing to do with Docker Swarm.

Why not a regular runtime service

A regular runtime service is managed through the Zerops API. Every change is queued, runs as a process you can follow in the GUI, and horizontal autoscaling decides how many containers exist. That is the right model for an application. It is too slow and too indirect when your code needs a fresh container now, a command executed in it, and the container gone a minute later.

In a Swarm service, horizontal autoscaling is off and you decide which containers exist. The pool can be empty. Requests go to an orchestrator that runs inside your project and talks to the platform directly, so creating, starting and stopping a container are synchronous calls: when the response arrives, the work is done.

How it works

A Swarm service has two parts:

The orchestrator, a small always-on container that serves the control API, a web UI and the API reference. It is created with the service and reachable on the project's private network at orch.<hostname>.zerops.
The pool, the containers your work runs in. They are ordinary Zerops containers: they sit on the project's private network, get the service's environment variables, and show up in the GUI with their logs and metrics.

Everything else behaves like a runtime service. You can deploy a zerops.yaml to it to prepare a custom image, and vertical autoscaling works the same way. The difference is who controls the containers.

Quick start

Add a Swarm service to your project with a zerops-import.yaml:

zerops-import.yaml

services:
  - hostname: sandbox
    type: swarm@1
    # usable right away, without a first deploy
    startWithoutCode: true

Import it with the zCLI:

zcli project service-import zerops-import.yaml

Connect to the project with the Zerops VPN and reserve a container. Requests coming from the VPN need no token:

curl -s -X POST http://orch.sandbox.zerops/container/acquire

The response contains the container and a lease, which proves the container is yours. Run a command in it and release it when you are done:

curl -s -X POST "http://orch.sandbox.zerops/container/<id>/exec?lease=<lease>" \
  -H "Content-Type: application/json" \
  -d '{"command": ["bash", "-lc", "uname -a"]}'

curl -s -X POST "http://orch.sandbox.zerops/container/<id>/release?lease=<lease>&reset=true"

If all you need is to run one command somewhere, a single call picks a free container (or creates a temporary one), runs the command and cleans up:

curl -s -X POST http://orch.sandbox.zerops/container/run \
  -H "Content-Type: application/json" \
  -d '{"command": ["bash", "-lc", "echo hello"]}'

See Work with the pool for the whole API and Connect & authenticate for calling it from your services.

Containers or virtual machines

Swarm comes in two types. They have the same API and the same orchestrator, and differ in what the pool is made of. The type is fixed for the life of the service.

Type	Pool	When to choose it
`swarm@1`	Linux containers (Ubuntu 26.04)	The default. Containers are created and started in seconds, scale vertically without a restart and use the least resources. You can deploy any container-based runtime to the pool.
`swarm-vm@1`	Virtual machines (the Docker VM)	When the work needs its own kernel: running Docker, or code you want separated from its neighbours by more than a container boundary. VMs boot slower, their resources are fixed values and only VM bases can be deployed to the pool.

Containers share the kernel of the machine they run on. That is the same isolation every Zerops runtime service has, and it is fine for your own code and your CI jobs. If you plan to run code you do not trust, consider the VM type. The general trade-offs are described in Containers vs VMs.