The local emulator

The emulator is the same agent binary that runs next to your unit in the cluster, started in a different mode. It cannot drift from the real thing. It creates the /zaroz tree, sets the contract environment, runs your command, prints every signal it receives, and enforces the same validation.

Run your server under it

Code
zaroz-unit-agent emulate --dir ./zaroz --key match-1 --label mode=2v2 \
  --user-data roster.json -- ./my-server

Your process sees ZAROZ_DIR=./zaroz, ZAROZ_UNIT_KEY=match-1, ZAROZ_CONTRACT_VERSION=1 and the other variables of the contract. Read ./zaroz/unit.json, write ./zaroz/signals/ready, and the emulator prints the signal with a timestamp.

Drive it from another terminal

Code
zaroz-unit-agent ctl --dir ./zaroz allocate --user-data match.json   # what allocate would do
zaroz-unit-agent ctl --dir ./zaroz labels mode=2v2
zaroz-unit-agent ctl --dir ./zaroz drain --reason stop               # the draining notice
zaroz-unit-agent ctl --dir ./zaroz undrain
zaroz-unit-agent ctl --dir ./zaroz release
zaroz-unit-agent ctl --dir ./zaroz status

The control socket (./zaroz/.control.sock) exists only in the emulator, never in a real pod.

In Docker

Code
FROM eclipse-temurin:21-jre
COPY --from=<registry>/zaroz-unit-agent:emulate /zaroz-unit-agent /usr/local/bin/
COPY server.jar /srv/server.jar
ENTRYPOINT ["zaroz-unit-agent", "emulate", "--dir", "/zaroz", "--key", "dev-1", "--", "java", "-jar", "/srv/server.jar"]

Code
docker exec <container> /usr/local/bin/zaroz-unit-agent ctl allocate --user-data /roster.json

Static binaries are built for Linux (amd64 and arm64). On Windows use WSL. A macOS build is not available yet.

The conformance suite

The conformance crate is MIT licensed. It starts a unit and checks the contract end to end: files present before start, signals reflected, allocation delivered and acknowledged, the draining notice before SIGTERM, and every file against its JSON Schema. The same assertion ids run against the emulator in your CI and against a real unit on the platform, so a unit that passes locally behaves the same in the cluster.