Configuration
The full worker.toml schema for zisk-worker, documenting the [worker], [coordinator], [connection], [telemetry], and [logging] tables — identity, advertised compute capacity, coordinator URL, connection tuning, telemetry, and logging. Backend selection happens via CLI flags, not TOML.
The TOML file describes zisk-worker's long-lived configuration.
Every table is optional; if you omit a key, the built-in default
applies. CLI flags override values set here. The
ZISK_WORKER_* environment variables are read by the install
script, not by the binary. See CLI & environment for the full flag list.
[worker]
# worker_id = "worker-a" # default: random UUID; pin for stable logs
compute_capacity = { compute_units = 10 }
environment = "production"
# inputs_folder = "." # default: the working directory
[coordinator]
url = "http://coord.lan:50051"
[connection]
reconnect_interval_seconds = 5
heartbeat_timeout_seconds = 30
[telemetry]
enabled = true
interval_seconds = 10
[logging] # accepted but not read by zisk-worker; use -v / -vv
level = "info"
format = "pretty"
The worker has no [backend] table — backend selection (Assembly
vs Rust emulator, GPU, final SNARK) happens entirely via CLI flags, not
TOML.
[worker]
Identity and how much work this worker is willing to take. The
compute_units value is an abstract weight the coordinator uses
when assigning segments; a worker advertising 10 units gets
roughly twice the load of one advertising 5. See
Compute units explained on the overview page for sizing
guidance.
| Setting | Default | Notes |
|---|---|---|
worker_id | random UUID | Pin to e.g. the hostname so log correlation works at scale. CLI: --worker-id. |
compute_capacity.compute_units | 10 | One unit per physical CPU core (minus two for OS overhead), plus one per GPU stream. CLI: --compute-capacity. |
environment | development | development, staging or production. |
inputs_folder | . (current dir) | Intermediate input files. The install script's sample config leaves it commented out, so under its unit the worker uses the unit's working directory, /var/lib/zisk-worker (/usr/local/var/zisk-worker on macOS). |
[coordinator]
| Setting | Default | Notes |
|---|---|---|
url | http://127.0.0.1:50051 | gRPC URL of the coordinator's worker-facing port. CLI: --coordinator-url. Use HTTPS in prod. |
[connection]
| Setting | Default | Notes |
|---|---|---|
reconnect_interval_seconds | 5 | Backoff between reconnect attempts when the coordinator is unreachable. |
heartbeat_timeout_seconds | 30 | Accepted but unused in 1.4.0-alpha. |
[telemetry]
What the worker reports to its coordinator about its host and
processes. Rank 0 sends it with its heartbeats, and the coordinator
publishes it as the coordinator_worker_* series.
It is informational: the coordinator bounds it and never acts on
it, and nothing about the jobs is in it.
| Setting | Default | Notes |
|---|---|---|
enabled | true | Report telemetry. CLI: --no-telemetry turns it off. |
interval_seconds | 10 | Seconds between two samples. The heartbeat is sent this often too, clamped to 1–30 s. With telemetry off the heartbeat runs every 30 s. |
A background thread samples, every interval_seconds:
| What | Source (Linux) | Series on the coordinator |
|---|---|---|
| Uptime and start-up times | the process clock | coordinator_worker_uptime_seconds, coordinator_worker_start_to_seconds{milestone} (registration, ready) |
Memory of each process in the worker's cgroup, by role (rankN, asm-<service>-rankN, mpirun, other) | /proc/<pid>/status | coordinator_worker_process_memory_bytes{role, kind} with kind rss, anon, file, shmem |
| ZisK shared memory on the host, by segment kind and whether its owner process is still alive | /dev/shm (ZISK_* and sem.ZISK_*) | coordinator_worker_shm_bytes, coordinator_worker_shm_segments (kind, owner_alive) |
| Memory and CPU of the worker's cgroup (v2) | /sys/fs/cgroup/<cgroup>/memory.*, cpu.stat | coordinator_worker_cgroup_memory_bytes{kind} (current, peak, anon, file, shmem), coordinator_worker_cgroup_cpu_seconds_total |
On macOS and other non-Linux hosts the worker reports only its uptime and start-up times.
When a worker ends itself with exit status 75 (a panic in a
multi-rank worker, or a failed or timed-out recovery), the rank
that ends it writes the reason to zisk-worker-exit-rank<N> in
the cache directory (ZISK_CACHE_DIR). The next run reports it
when it registers, and removes the file. The coordinator counts it
in coordinator_worker_exits_total{reason} and, for panics,
coordinator_worker_panics_total{location}. With telemetry off,
the previous exit isn't reported.
[logging]
Accepted for the same keys as the coordinator's [logging] — level, format, optional file_path — but zisk-worker doesn't read it: none of the three changes its output, and neither does RUST_LOG. The worker logs at info to stdout; raise it with -v (debug) or -vv (trace) on the command line. The start-up banner's Logging line still echoes the TOML's level/format.