Skip to main content

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.toml
[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.

SettingDefaultNotes
worker_idrandom UUIDPin to e.g. the hostname so log correlation works at scale. CLI: --worker-id.
compute_capacity.compute_units10One unit per physical CPU core (minus two for OS overhead), plus one per GPU stream. CLI: --compute-capacity.
environmentdevelopmentdevelopment, 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]​

SettingDefaultNotes
urlhttp://127.0.0.1:50051gRPC URL of the coordinator's worker-facing port. CLI: --coordinator-url. Use HTTPS in prod.

[connection]​

SettingDefaultNotes
reconnect_interval_seconds5Backoff between reconnect attempts when the coordinator is unreachable.
heartbeat_timeout_seconds30Accepted 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.

SettingDefaultNotes
enabledtrueReport telemetry. CLI: --no-telemetry turns it off.
interval_seconds10Seconds 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:

WhatSource (Linux)Series on the coordinator
Uptime and start-up timesthe process clockcoordinator_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>/statuscoordinator_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.statcoordinator_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.