Copy page

Units your code controls

Units your code controls

A Workload normally scales by itself: you set a count, or CPU and memory targets, and the platform decides how many units run. Some programs need to decide for themselves: a Minecraft network that opens a server per match, a render farm that runs one unit per job, a hub that wakes a private world when its owner logs in. For those, set the policy to code mode and let your program say which units exist.

The pieces

Concept	One sentence	Where
Key	The name you give a unit; it never changes and is the unit's private network name	Create by key
Labels	Up to 16 queryable tags, changeable any time	Labels and user data
user_data	Up to 64 KiB of JSON the unit reads at start: the match, the job, the world	Labels and user data
Origin	Who made the unit: policy, code or warm
Warm buffer	Started, idle units the platform keeps ready for you	Warm buffer and allocate
Allocate	Atomically hand one warm unit to a caller, with input	Warm buffer and allocate
Signals	What a unit tells the platform: ready, accepting, idle, busy, shutdown	Signals
Rollout rules	How a new image replaces running units without ending a match	Rollout rules
Events and webhooks	A gapless log of everything that happens to your units	Events
Service principal	The Workload's own identity to call the API from inside	Service principals
Unit contract	The files, environment and sockets a unit's process can rely on	The contract

A unit's life

Code
created (stopped) --start--> starting --ready--> running --stop--> draining --> stopped
                                  \                  |                            |
                                   \--failed         |--exit: restart / stop / destroy
                                                     \--destroy--> destroyed <-----/

• Allocated is not a separate state: it is a fact about a running unit (allocation is set). An allocation is never undone.
• A stopped unit has no pod and costs nothing. Its key, labels and user_data are kept.
• When the unit's process exits, on_exit decides: restart (same pod, new process), stop or destroy.
• Before a unit is stopped, destroyed or replaced, it is drained: it receives a notice (/zaroz/state.json), stops accepting new work, and gets time to finish before the process is signalled.

What it costs

There is no new meter. A code-made, warm or allocated unit is an ordinary unit pod, billed like any extra unit: per hour while it runs, with a 5-minute minimum per start. Warm units are billed because they hold CPU and memory. Stopped units are free. Events, webhooks and service principals are included at no charge. Your spend cap, your unit limit (default 50 per organization) and your start rate (default 600 per hour) apply to every call that starts a pod.

Guarantees

These are promises of the platform. Each one is checked by the conformance suite against both the local emulator and a real unit.

1. Ready means ready. With readiness: signal, a unit receives traffic and can be allocated only after it has signalled ready.
2. Allocate is atomic. Two callers never receive the same unit, and an allocated unit is never chosen by a scale-down or by warm-excess removal.
3. Drain before kill. A unit that is stopped, destroyed or replaced sees draining: true before its process is signalled.
4. Stopped costs nothing. No pod, no cluster object, no billed interval.
5. Fast refusal. A call past a limit is refused immediately with a stable code, and never leaves a half-made unit.
6. Out of load balancing in about a second. accepting false removes the unit from the service and from allocation inside its region, without waiting for the platform's control plane.
7. Events never skip. A cursor never misses an event that commits late.