Skip to main content

CLI & environment

Documents the zisk-worker command-line flags — identity, proving keys, backend selection, performance tuning, and diagnostics — and the ZISK_WORKER_* environment variables, noting which the binary reads at runtime versus which the install script consumes.

zisk-worker is configured primarily through worker.toml; this page documents the escape hatches: command-line flags and environment variables that override TOML values for one-off testing, performance tuning, or debugging a wedged worker. CLI flags win over the TOML. The binary itself reads almost no environment variables; see Environment variables.

zisk-worker [OPTIONS]

CLI flags​

The worker CLI is wider than the coordinator's. Many flags exist for one-off testing, performance tuning, or debugging a wedged worker without rewriting the TOML.

Identity and target​

FlagShortDefaultDescription
--config <PATH>(unset)TOML configuration file. When unset, the worker reads ZISK_WORKER_CONFIG_PATH, and with neither it runs on the built-in defaults. There is no well-known path.
-c, --coordinator-url <URL>-c(from TOML)Override [coordinator].url.
--worker-id <ID>(from TOML, else UUID)Override [worker].worker_id.
--compute-capacity <N>(from TOML)Override [worker].compute_capacity.compute_units.
--no-telemetryfalseDon't report host and process telemetry to the coordinator. Same as [telemetry].enabled = false; see Telemetry.

Proving keys​

A worker needs the STARK proving key for every job. To serve final-SNARK jobs it also needs --snark, which loads the SNARK proving key.

FlagShortDefaultDescription
-k, --proving-key <DIR>-k$HOME/.zisk/provingKey (/opt/zisk/provingKey for a system install)Path to the STARK proving key directory. The default is ${ZISK_HOME}/provingKey.
-p, --snark-pfalseLoad the SNARK proving key and serve final-SNARK jobs. See below.
-s, --proving-key-snark <DIR>-s$HOME/.zisk/provingKeySnark (/opt/zisk/provingKeySnark for a system install)Path to the SNARK proving key. The default is ${ZISK_HOME}/provingKeySnark. Read only with --snark.
-P, --preload-snark-PfalseLoad the SNARK key at start-up instead of on first use. Has no effect without --snark.
note

--plonk and --preload-plonk still work as aliases of --snark and --preload-snark.

With --snark, the worker reads the SNARK proving key at start-up and finds which final SNARK it is set up for (PLONK or pilfflonk). It reports that protocol when it registers, and the coordinator requires every worker to report the same one (see zisk-coordinator / Worker registration). A key that isn't a final SNARK key, or one set up for FFLONK, stops the worker at start-up with --snark needs a final SNARK proving key, but ….

Without --snark, the worker reports no SNARK key, and the coordinator rejects every final-SNARK request with SNARK_UNAVAILABLE (1008), even when the key is on disk and --proving-key-snark is set. See Choosing a proof format.

note

The install script's --with-snark, the Ansible role and the Helm chart add --snark together with --proving-key-snark.

Backend selection​

Pick the execution backend. The Assembly backend is the default; --emulator switches to the prebuilt Rust emulator, which is the only option on macOS (the Assembly backend is Linux-only). On macOS the worker selects the emulator on its own; you don't need to pass --emulator.

FlagShortDefaultDescription
-a, --asm <PATH>-a(unset)Path to the ASM file. Mutually exclusive with --emulator.
-l, --emulator-lfalseUse the prebuilt Rust emulator. Mutually exclusive with --asm / --unlock-mapped-memory / --asm-out-file.
-g, --gpu-gfalseEnable GPU proving (CUDA). GPU builds only; see below.
note

The --gpu and --cpu-mops flags are conditionally compiled: #[cfg(not(feature = "cpu-only"))]. They exist only in a GPU build: a from-source build without --features cpu-only, or the GPU build ziskup installs on Linux. The CPU build ziskup installs on Linux and the macOS build are cpu-only, and reject both flags at start-up with a command-line error (unexpected argument '--gpu' found). Whether a GPU build can actually use a GPU at runtime additionally depends on having a CUDA-capable host.

Performance tuning​

Trade off speed against memory or unlock platform acceleration.

FlagShortDefaultDescription
-n, --number-threads-witness <N>-n(auto)Threads used for witness computation. Defaults to physical cores.
-x, --max-witness-stored <BYTES>-x(auto)Cap on in-memory witnesses. Lower trades proving time for memory.
-t, --max-streams <N>-t(auto)Maximum concurrent GPU streams.
--max-recursive-streams <N>(auto)Maximum recursive (aggregation) streams per GPU.
--cpu-mopsfalseRun the memory-operations planner on the CPU even with --gpu, as a fallback for GPU planner issues. GPU builds only: a cpu-only build rejects it with a command-line error.
-m, --minimal-memory-mfalseUse the lowest-memory code path. Slower but safe on tight hosts.
--unlock-mapped-memoryfalseUnlock the memory map of the ROM file, for hosts with limited memory. Mutually exclusive with --emulator.

Diagnostics​

FlagShortDefaultDescription
--verify-constraintsfalseAccepted but has no effect in 1.4.0-alpha: the worker parses it and never uses it.
--asm-out-filefalseRedirect ASM emulator output to a file. Mutually exclusive with --emulator.
-v, --verbose-v0Verbose logging: -v for debug, -vv for trace. The only way to change the worker's log level; [logging] and RUST_LOG are ignored.
-d, --debug [VALUE]-d(unset)Enable debug mode. Accepts an optional value; pass without a value to toggle, or with a value for finer control.

Environment variables​

Unlike zisk-coordinator, the worker's CLI args are not bound to env vars via clap — there are no env = attributes on any flag. As a result the only env vars the worker binary itself reads at runtime are:

VariableRead byEffect
ZISK_WORKER_CONFIG_PATHbinaryPath to worker.toml (used when --config isn't passed).
ZISK_HOME / ZISK_CACHE_DIRbinaryBundle root (default proving-key paths) and cache directory.

RUST_LOG is not one of them: the worker ignores it, as it ignores [logging]. Use -v / -vv to raise its verbosity.

Everything else in the ZISK_WORKER_* family is read by the deploy install script (from .env or the shell environment) at install time, not by the running binary. The script translates them into CLI flags or TOML values during the install.

VariableRead byWhat the install script does with it
ZISK_WORKER_BINARYinstall scriptPath to a pre-built zisk-worker binary to copy into /usr/local/bin/.
ZISK_WORKER_CONFIGinstall scriptPath to a worker.toml to copy into /etc/zisk/.
ZISK_WORKER_COORDINATOR_URLinstall scriptSame as passing --coordinator-url.
ZISK_WORKER_IDinstall scriptSame as passing --worker-id.
ZISK_WORKER_COMPUTE_CAPACITYinstall scriptSame as passing --compute-capacity.
ZISK_WORKER_PROVING_KEYinstall scriptSame as passing --proving-key.
ZISK_WORKER_PROVING_KEY_SNARKinstall scriptSame as passing --proving-key-snark.
ZISK_WORKER_EMULATORinstall scriptAdd --emulator to the unit's ExecStart.
ZISK_WORKER_ASMinstall scriptAdd --asm <PATH> to the unit's ExecStart.
ZISK_WORKER_GPUinstall scriptAdd --gpu to the unit's ExecStart.
ZISK_WORKER_MPIinstall scriptEnable MPI for multi-process workers. Pair with MPI_PROCESSES, MPI_NUMA_PPR, MPI_THREADS.
ZISK_WORKER_WITH_SNARKinstall scriptDownload the SNARK proving key into the bundle and add --snark --proving-key-snark (same as --with-snark). It doesn't add --preload-snark; see Proving keys.
ZISK_HOME / ZISK_CACHE_DIRbundle / cacheOverride the bundle root and cache directory used by the toolchain layer.

For worked invocations combining these flags and env vars, see Examples on the Usage page.