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
| Flag | Short | Default | Description |
|---|---|---|---|
--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-telemetry | false | Don'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.
| Flag | Short | Default | Description |
|---|---|---|---|
-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 | -p | false | Load 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 | -P | false | Load the SNARK key at start-up instead of on first use. Has no effect without --snark. |
--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.
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.
| Flag | Short | Default | Description |
|---|---|---|---|
-a, --asm <PATH> | -a | (unset) | Path to the ASM file. Mutually exclusive with --emulator. |
-l, --emulator | -l | false | Use the prebuilt Rust emulator. Mutually exclusive with --asm / --unlock-mapped-memory / --asm-out-file. |
-g, --gpu | -g | false | Enable GPU proving (CUDA). GPU builds only; see below. |
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.
| Flag | Short | Default | Description |
|---|---|---|---|
-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-mops | false | Run 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 | -m | false | Use the lowest-memory code path. Slower but safe on tight hosts. |
--unlock-mapped-memory | false | Unlock the memory map of the ROM file, for hosts with limited memory. Mutually exclusive with --emulator. |
Diagnostics
| Flag | Short | Default | Description |
|---|---|---|---|
--verify-constraints | false | Accepted but has no effect in 1.4.0-alpha: the worker parses it and never uses it. | |
--asm-out-file | false | Redirect ASM emulator output to a file. Mutually exclusive with --emulator. | |
-v, --verbose | -v | 0 | Verbose 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:
| Variable | Read by | Effect |
|---|---|---|
ZISK_WORKER_CONFIG_PATH | binary | Path to worker.toml (used when --config isn't passed). |
ZISK_HOME / ZISK_CACHE_DIR | binary | Bundle 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.
| Variable | Read by | What the install script does with it |
|---|---|---|
ZISK_WORKER_BINARY | install script | Path to a pre-built zisk-worker binary to copy into /usr/local/bin/. |
ZISK_WORKER_CONFIG | install script | Path to a worker.toml to copy into /etc/zisk/. |
ZISK_WORKER_COORDINATOR_URL | install script | Same as passing --coordinator-url. |
ZISK_WORKER_ID | install script | Same as passing --worker-id. |
ZISK_WORKER_COMPUTE_CAPACITY | install script | Same as passing --compute-capacity. |
ZISK_WORKER_PROVING_KEY | install script | Same as passing --proving-key. |
ZISK_WORKER_PROVING_KEY_SNARK | install script | Same as passing --proving-key-snark. |
ZISK_WORKER_EMULATOR | install script | Add --emulator to the unit's ExecStart. |
ZISK_WORKER_ASM | install script | Add --asm <PATH> to the unit's ExecStart. |
ZISK_WORKER_GPU | install script | Add --gpu to the unit's ExecStart. |
ZISK_WORKER_MPI | install script | Enable MPI for multi-process workers. Pair with MPI_PROCESSES, MPI_NUMA_PPR, MPI_THREADS. |
ZISK_WORKER_WITH_SNARK | install script | Download 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_DIR | bundle / cache | Override 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.