# 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

```bash
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](/units-code/contract). Read `./zaroz/unit.json`, write `./zaroz/signals/ready`, and the emulator prints the signal with a timestamp.

## Drive it from another terminal

```bash
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

```dockerfile
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"]
```

```bash
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.

:::note
The emulator image and binaries will be published to the `zaroz-oss` organization at release (the exact image name is announced there; `<registry>` above stands for it). The agent's own source is private; the contract schemas, the emulator, the conformance suite, the helper and the examples are public.
:::