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 env vars, which
win over the TOML.
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> | /etc/zisk/worker.toml | TOML configuration file. | |
-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. |
Proving keys
A worker needs the STARK proving key to produce --proof stark
or --proof stark-minimal outputs. Producing --proof plonk
also requires the SNARK key.
| Flag | Short | Default | Description |
|---|---|---|---|
-k, --proving-key <DIR> | -k | ~/.zisk/provingKey | Path to the STARK proving key directory. |
-s, --proving-key-snark <DIR> | -s | (unset) | Path to the SNARK proving key (needed for --proof plonk). |
-P, --preload-plonk | -P | false | Pre-load the Plonk key on startup instead of on first use. |
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).
| 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). Available unless the binary was built with the cpu-only feature. |
-p, --plonk | -p | false | Emit the Plonk proof format. Requires --proving-key-snark. |
The --gpu flag is conditionally compiled: #[cfg(not(feature = "cpu-only"))]. The flag is present by default and removed only
when the binary is built explicitly with --features cpu-only.
ziskup ships a build that exposes --gpu; whether the binary
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. |
-m, --minimal-memory | -m | false | Use the lowest-memory code path. Slower but safe on tight hosts. |
--unlock-mapped-memory | false | Disable memory-locking on the input map. Mutually exclusive with --emulator. |
Diagnostics
| Flag | Short | Default | Description |
|---|---|---|---|
--verify-constraints | false | Re-verify constraints after witness generation. Slow; debugging only. | |
--asm-out-file | false | Redirect ASM emulator output to a file. Mutually exclusive with --emulator. | |
-v, --verbose | -v | 0 | Verbose logging. Repeatable (-v, -vv, …) to increase verbosity. |
-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). |
RUST_LOG | tracing | Per-module log filter. Overrides [logging].level from the TOML. |
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 | Pre-load the SNARK proving key on startup (--preload-plonk). |
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.