Skip to main content

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:

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

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:

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

PortPurpose
7000Client-facing gRPC API. Clients connect here.
50051Worker-facing cluster gRPC. Workers connect here.
9090Prometheus /metrics and /health HTTP endpoint.
macOS: port 7000 is taken

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:

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:

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

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

bash
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(…).

Slow hosts: Phase 2 timeout

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-core.toml
[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 /metrics into Prometheus and Grafana.