Quickstart
The fastest path to a running ZisK prover. Start a coordinator
and a worker on your own machine and submit a real proving job
to it via the in-tree sha-hasher example. Plan for 15 to 20
minutes end-to-end: the smoke-test proof alone takes about 7
minutes on a 24-core CPU-only host.
Install ZisK
The Quickstart assumes you already have ZisK installed via
ziskup. The developer install guide is the canonical source,
it covers system prerequisites (shared memory, Rust toolchain,
package dependencies) plus the ziskup flow that drops
cargo-zisk, zisk-coordinator, zisk-worker, and the
proving-key bundle on your machine:
On a Linux host without a supported NVIDIA driver, ziskup first
asks whether to install the CPU or the GPU build; press enter for
the CPU build. Then pick option 1 at the proving-key prompt to
install the full proving key so the worker can produce proofs. Come back here
once zisk-coordinator --version works from a fresh shell.
Clone the repository
A few steps below use files that ship with the ZisK repo — ready-to-go example configs for the coordinator and worker, plus the host example used for the smoke test. Clone it into a working directory:
git clone https://github.com/0xPolygonHermez/zisk.git
cd zisk
The rest of the Quickstart runs from inside this clone.
Start the coordinator
The repo ships an example coordinator config at
distributed/deploy/config/coordinator.toml:
[service]
name = "ZisK Coordinator"
environment = "production"
[server]
host = "0.0.0.0"
port = 7001 # client-facing gRPC
shutdown_timeout_seconds = 30
[metrics]
enabled = true
host = "0.0.0.0"
port = 9091
[logging]
level = "info"
format = "json"
[backend]
mode = "coordinator"
[coordinator]
port = 50052 # worker-facing gRPC
It's tuned for a Docker Compose deployment, so its ports
(7001 / 50052 / 9091) are offset by one from the canonical
defaults to coexist with a host install. For the Quickstart, point
the coordinator at it and override the ports back to the
defaults on the command line:
zisk-coordinator --config distributed/deploy/config/coordinator.toml \
--api-port 7000 --cluster-port 50051 --metrics-port 9090
Leave the terminal open. The coordinator now listens on:
| Port | Purpose |
|---|---|
7000 | Client-facing gRPC API. Clients connect here. |
50051 | Worker-facing cluster gRPC. Workers connect here. |
9090 | Prometheus /metrics and /health HTTP endpoint. |
On macOS the AirPlay Receiver (ControlCenter) listens on port
7000. The coordinator then logs
zisk-coordinator listening on 0.0.0.0:7000 followed by
Address already in use (os error 48) and exits. Either turn off
AirPlay Receiver (System Settings → General → AirDrop &
Handoff) or pick another --api-port. The example clients
hard-code http://127.0.0.1:7000, so if you change the port, change
the URL in examples/sha-hasher/host/bin/remote/prove.rs to match.
Start a worker
The repo also ships an example worker config at
distributed/deploy/config/worker.toml:
[worker]
compute_capacity.compute_units = 10
environment = "production"
[coordinator]
url = "http://127.0.0.1:50052"
[connection]
reconnect_interval_seconds = 5
heartbeat_timeout_seconds = 30
[logging]
level = "info"
format = "json"
In a second terminal (still inside the zisk clone), start a
worker using this config. Override the coordinator URL so the
worker dials the canonical :50051 you bound the coordinator on:
zisk-worker --config distributed/deploy/config/worker.toml \
--coordinator-url http://127.0.0.1:50051
The worker opens a bidirectional WorkerStream, registers
itself with a random worker_id, and starts heartbeating. You
should see a registered successfully line in the coordinator
terminal. You now have a one-worker cluster running locally.
On worker console:
2026-10-29T14:04:10.270481Z [rank=0] INFO: Connecting to coordinator at http://127.0.0.1:50051
2026-10-29T14:04:10.274504Z [rank=0] INFO: Registration accepted: Registration successful
On Coordinator console:
2026-10-29T14:04:10.274271Z INFO: Registered worker: WorkerId(7cb4dca4…) (total: 1 CC: 10CU ACC: 0CU)
2026-10-29T14:04:10.274403Z INFO: WorkerId(7cb4dca4…) registered successfully
Both configs set format = "json", but in 1.4.0-alpha the
format setting has no effect: pretty, json and compact
all print the plain-text lines shown above.
Health check
Before submitting a job, confirm the coordinator is live. Its
metrics server exposes a /health endpoint that returns
200 OK when the binary is healthy:
curl -i http://127.0.0.1:9090/health
HTTP/1.1 200 OK
Content-Length: 2
If you don't get a 200, scroll back to the coordinator
terminal — most failures (port conflict, missing config field)
show up there immediately.
Submit a smoke-test job
The sha-hasher example in the clone you made earlier ships a
host program that submits a real proving job over the
coordinator's public gRPC API. It uses the in-tree
ProverClient::remote(...) helper, so you exercise the same code
path your own host applications will use — no separate CLI
involved.
In a third terminal, from inside the zisk clone:
cd examples/sha-hasher/host
cargo run --release --bin prove-remote
prove-remote builds a
ProverClient::remote("http://127.0.0.1:7000"), uploads the
sha-hasher guest ELF, waits for the coordinator to drive the
job through the worker, verifies the proof, and writes it to
tmp/sha_hasher_proof.bin (relative to
examples/sha-hasher/host).
While it runs, watch the other two terminals. The coordinator log shows the job going through its three phases:
INFO: [Job] Started JobId(082af14f…) successfully Capacity: 10CU Workers: 1 Random seed: 517cf7c1…
INFO: [Phase1] Started with 1 workers for JobId(082af14f…)
INFO: [Phase2] Started with 1 workers for JobId(082af14f…)
INFO: [Phase3] Aggregation started for JobId(082af14f…) (arity 2, distributed true)
INFO: [Job] Finished JobId(082af14f…) successfully ✔ Duration: 406.527s (25.586s+364.750s+16.193s) Steps: 2.309.095 Instances: 15 Capacity: 10CU
The worker log shows the program setup, witness generation and
proof generation, and ends with
Aggregation task completed for JobId(…).
The coordinator fails a job whose Prove phase runs longer than
phase2_timeout_seconds (default 600). On a CPU-only host
with few cores, or on macOS where the worker runs the emulator,
the smoke test can exceed it: the coordinator logs
[Monitor] Phase Prove timed out for job JobId(…) (601s > 600s)
and fails the job. Raise the timeout in a coordinator-core
tuning file and point [coordinator].config_file at it (see
Coordinator-core tuning):
[coordinator]
phase2_timeout_seconds = 1800
Next steps
- Pick a real deployment style in Deploying your prover — local dev, Linux server, Docker Compose, container images, or Kubernetes.
- Wire
/metricsinto Prometheus and Grafana.