Usage

How to invoke zisk-worker, the stateless proving process that dials the coordinator and proves assigned segments. Covers its three configuration sources and override precedence, the operationally relevant defaults, signal handling, compute-unit sizing, and worked examples.

A worker is the proving process. It dials the coordinator, registers a compute capacity, and proves the segments it's assigned. Workers are stateless across jobs — add, remove, or restart them at will. A worker host needs ~32 GB RAM and, optionally, a CUDA-capable GPU.

zisk-worker [OPTIONS]

---

Configuration

zisk-worker reads its settings from three sources, plus built-in defaults for anything you don't set:

• TOML config file passed via --config <PATH>. The canonical home for long-lived settings: coordinator URL, advertised capacity, connection tuning, logging. The full schema is documented on Configuration.
• Environment variables with the ZISK_WORKER_* prefix, plus the standard RUST_LOG. Use these for values that come from the deployment substrate rather than the application. Full mapping on CLI & environment.
• Command-line flags for identity overrides, proving keys, backend selection, performance tuning, and diagnostics. The narrowest layer; use for one-off testing, container entrypoints, or the systemd unit's ExecStart. Full flag list on CLI & environment.

Override precedence

Settings are resolved in four layers, with later sources winning:

1. Built-in defaults.
2. TOML config file.
3. Environment variables.
4. Command-line flags.

Example: a TOML with [worker].compute_capacity.compute_units = 10 is shifted to 16 by ZISK_WORKER_COMPUTE_CAPACITY=16, and to 32 by --compute-capacity 32 as CLI wins over env, env wins over TOML.

---

Defaults

If you start zisk-worker with no flags and no config file, the built-in defaults take over. The full schema is on Configuration; the most operationally relevant defaults are:

Setting	Default	Override
Coordinator URL	http://127.0.0.1:50051	[coordinator].url / --coordinator-url
Compute units advertised	10	[worker].compute_capacity / --compute-capacity
Worker identifier	random UUID	[worker].worker_id / --worker-id
STARK proving key path	~/.zisk/provingKey	[worker] (env) / --proving-key
SNARK proving key path	(unset; required for --plonk)	--proving-key-snark
Backend	Assembly (unless --emulator is set; macOS hosts must pass --emulator)	--asm <PATH> / --emulator / --gpu
Inputs folder	. (current dir; the install script overrides this to /var/lib/zisk-worker/inputs)	[worker].inputs_folder
Reconnect interval	5s	[connection].reconnect_interval_seconds
Heartbeat timeout	30s	[connection].heartbeat_timeout_seconds
Log level	info	[logging].level / RUST_LOG
Log format	pretty	[logging].format

---

Signals

Signal	Effect
SIGTERM / SIGINT	Graceful shutdown. The worker stops accepting new assignments but lets the segments it's already proving finish before exiting. The coordinator marks the worker offline once its heartbeat stops.
SIGKILL	Forced exit. Any in-flight segments are dropped; the coordinator detects the disconnect via heartbeat timeout and reassigns segments to a fresh worker on a new job (in-flight jobs may fail if no replacement is available in time).

---

Compute units explained

Compute units are an abstract weight the coordinator uses when splitting a job. A worker advertising compute_units = 10 gets roughly twice the load of one advertising 5.

---

Examples

Run with the config installed by the deploy script:

zisk-worker --config /etc/zisk/worker.toml

Connect to a remote coordinator with a stable worker id and a larger capacity than the default:

zisk-worker --config /etc/zisk/worker.toml \
    --coordinator-url http://coord.lan:50051 \
    --worker-id worker-a-gpu1 --compute-capacity 32

Use the GPU build with four concurrent streams:

zisk-worker --config /etc/zisk/worker.toml --gpu --max-streams 4

Produce on-chain-verifiable PLONK proofs (requires the SNARK key on disk and --with-snark at install time):

zisk-worker --config /etc/zisk/worker.toml \
    --plonk --preload-plonk \
    --proving-key-snark /opt/zisk/provingKeySnark