Deploy binaries directly
A step-by-step guideline for the lightest prover deployment: the
binaries on your PATH, started by hand, configured via two
short TOML files. By the end of this page a coordinator and one
worker are running on your machine.
When to pick this
Pick this path when you want no service-manager and no container in the loop — you launch the binaries yourself and own their lifecycle. Right shape for:
- A developer workstation testing a real cluster locally.
- Custom orchestrators where systemd / launchd / Docker would get in the way.
For a 24/7 production prover, see Deploy as services; for a Compose stack with Prometheus and Grafana attached, see Deploy with Docker.
Install the binaries
Both install paths: the prebuilt ziskup flow and the
from-source build are documented end to end in the developer
install guides, alongside system dependencies (apt / brew),
shared-memory tuning, and proving-key setup:
Get the configuration files
The cluster reads two TOMLs: one for the coordinator, one for the
worker. You can either copy them out of a repo clone or write
them yourself with any editor. Both end with the same files at
~/zisk-cluster/.
Download from the repo
Grab the two files directly from GitHub repository:
mkdir -p ~/zisk-cluster
curl -fsSL -o ~/zisk-cluster/coordinator.toml \
https://raw.githubusercontent.com/0xPolygonHermez/zisk/main/distributed/deploy/config/coordinator.toml
curl -fsSL -o ~/zisk-cluster/worker.toml \
https://raw.githubusercontent.com/0xPolygonHermez/zisk/main/distributed/deploy/config/worker.toml
If you already have the repo cloned (e.g. for the source build),
cp distributed/deploy/config/{coordinator,worker}.toml ~/zisk-cluster/ works just the same.
Write them yourself
mkdir -p ~/zisk-cluster && cd ~/zisk-cluster
Open coordinator.toml in nano, vim, or your editor of
choice and paste:
[service]
name = "ZisK Coordinator"
environment = "production" # development | staging | production
[server]
host = "0.0.0.0"
port = 7001 # client-facing gRPC (overridden on the CLI below)
shutdown_timeout_seconds = 30
[metrics]
enabled = true
host = "0.0.0.0"
port = 9091 # Prometheus + /health (overridden on the CLI below)
[logging]
level = "info" # trace | debug | info | warn | error
format = "json" # no effect in 1.4.0-alpha
[backend]
mode = "coordinator"
[coordinator]
port = 50052 # worker-facing gRPC (overridden on the CLI below)
Open worker.toml and paste:
[worker]
# worker_id = "worker-a" # default: random UUID; pin for stable logs
compute_capacity = { compute_units = 10 }
environment = "production"
# inputs_folder = "." # default: current directory
[coordinator]
url = "http://127.0.0.1:50052" # overridden on the CLI below
[connection]
reconnect_interval_seconds = 5
heartbeat_timeout_seconds = 30
[logging] # not read by zisk-worker; use -v
level = "info"
format = "json"
~/zisk-cluster/ is just a convention used by this page, you
can drop the TOMLs anywhere and point --config at whatever path
you choose.
Configure the coordinator
The table below explains everything zisk-coordinator reads:
| Table | Purpose |
|---|---|
[service] | Identity used in log labels. environment is a free-form tag (development / staging / production). |
[server] | The public gRPC API where clients submit jobs. shutdown_timeout_seconds is the drain window applied on SIGTERM. |
[coordinator] | The cluster gRPC port workers dial to register and stream segments. |
[metrics] | GET /metrics returns Prometheus text; GET /health returns 200 OK while alive. |
[logging] | level sets the log level. format has no effect in 1.4.0-alpha: pretty, json and compact print the same lines. |
[backend] | Internal — keep coordinator. |
Edit it freely; service name, log format / level, environment
label, bind addresses, ports. The launch command in this guide
overrides the three ports back to canonical defaults
(7000 / 50051 / 9090) regardless of what's in the TOML.
Settings resolve in four layers, later wins: built-in defaults →
TOML → env vars (ZISK_COORDINATOR_*) → CLI flags. The log level
is the exception: a set RUST_LOG wins over both --log-level
and [logging].level. Full reference on
zisk-coordinator.
Configure the worker
The supplied worker.toml points the worker at
coordinator on port 50052. The four tables it reads:
| Table | Purpose |
|---|---|
[worker] | Identity + capacity. compute_units is an abstract weight the coordinator uses to assign segments. |
[coordinator] | Where the worker dials. |
[connection] | How the worker reacts to network blips. Only reconnect_interval_seconds is used; heartbeat_timeout_seconds is accepted but unused. |
[logging] | Accepted but not read: zisk-worker ignores [logging] and RUST_LOG. Raise verbosity with -v / -vv. |
There's intentionally no [backend] table — backend selection
(Assembly emulator, Rust emulator, GPU, Plonk) is done on the
command line. See zisk-worker for every flag.
Edit it freely, pin a stable worker_id, raise or lower
compute_units, tune the reconnect window. The
--coordinator-url override in the launch command in this guide
points the worker at the canonical :50051 regardless of what's
in the TOML.
Settings resolve in three layers, later wins: built-in defaults →
TOML → CLI flags. The only environment variables the worker
reads are ZISK_WORKER_CONFIG_PATH (config path when --config
is not given) and ZISK_HOME; there are no other ZISK_WORKER_*
overrides. Full reference on
zisk-worker.
Start the coordinator
In your first terminal, launch the coordinator in the foreground.
The --*-port flags override the Docker-tuned ports back to
canonical defaults:
zisk-coordinator \
--config ~/zisk-cluster/coordinator.toml \
--api-port 7000 \
--cluster-port 50051 \
--metrics-port 9090
You should see three "listening on" lines for 0.0.0.0:7000,
0.0.0.0:50051, and 0.0.0.0:9090. Sanity-check from any other
shell:
curl -i http://127.0.0.1:9090/health # → HTTP/1.1 200 OK
Leave the terminal open.
Override only the conflicting port (e.g. --metrics-port 9095).
Keep the others on the defaults so the worker and smoke-test
client below find them.
Start the worker
In your second terminal, launch the worker, pointing it at the
coordinator on the canonical :50051 you just bound:
zisk-worker \
--config ~/zisk-cluster/worker.toml \
--coordinator-url http://127.0.0.1:50051
The worker resolves the proving key (default
~/.zisk/provingKey), opens a bidirectional WorkerStream to
127.0.0.1:50051, registers, and starts heartbeating. The
coordinator's log shows:
INFO: Registered worker: WorkerId(15017972…) (total: 1 CC: 10CU ACC: 0CU)
INFO: WorkerId(15017972…) registered successfully
You now have a one-coordinator, one-worker cluster running locally.
A handful of flags are worth knowing without flipping to the full reference:
| Flag | Purpose |
|---|---|
--gpu | Turn on GPU proving. The single biggest performance lever — proving throughput typically scales several-fold versus the CPU/ASM path. |
--worker-id | Pin a stable id for log correlation instead of the random UUID. |
--compute-capacity | Raise / lower the advertised weight without editing the TOML. |
--proving-key | Use a non-default proving-key location. |
On a CUDA-capable host, --gpu is the biggest single performance
unlock the worker offers. Add --max-streams N (start with one
stream per ~8 GB of GPU memory) and raise --compute-capacity
accordingly so the coordinator assigns it proportionally more
segments. See
zisk-worker / Performance tuning.
Submit a smoke-test job
The repo ships a gcd example whose remote-host binary submits
a real proving job over the public gRPC API. Open a third
terminal and pull the repo if you haven't already, then run the
example:
# Skip the clone if you already have one (e.g. from the source-build install)
git clone https://github.com/0xPolygonHermez/zisk.git
cd zisk/examples/gcd/host
cargo run --release --bin remote-host
The binary builds a
ProverClient::remote("http://localhost:7000") internally — the
same code path your own host applications use.
While it runs:
- The coordinator log shows the job going through its
phases, from
[Job] Started JobId(…)through[Phase1],[Phase2]and[Phase3] Aggregation started …to[Job] Finished JobId(…) successfully ✔. - The worker log shows witness generation and proof
generation, and ends with
Aggregation task completed for JobId(…).
When remote-host exits cleanly it prints
Proof was verified successfully. and gcd(5, 10) => 5. It
verifies the proof but does not save it. To get a proof file,
run the sha-hasher example's prove-remote binary instead
(cd zisk/examples/sha-hasher/host && cargo run --release --bin prove-remote),
which writes tmp/sha_hasher_proof.bin.
Stop the cluster
Each binary runs in the foreground, so Ctrl-C (or SIGTERM) in
the terminal you launched it from triggers a graceful shutdown.
The coordinator stops accepting new jobs and waits up to
[server].shutdown_timeout_seconds (default 30s) for in-flight
jobs to drain — anything still running when that window closes
surfaces as Failed on the client side.
The worker doesn't drain. On Ctrl-C, SIGTERM or SIGUSR1 it
cancels the job in flight, kills its ASM services, unlinks their
shared memory and exits within about 5 s. A job it was computing
fails on the coordinator (Worker <id> connection dropped) once
reconnect_grace_period_ms passes, and isn't reassigned: submit it
again. Under mpirun, send SIGUSR1 to mpirun, not SIGTERM.
See zisk-worker / Signals.