Usage
How to invoke zisk-coordinator, the cluster orchestrator that accepts proof requests and fans work out to workers. Covers its three configuration sources and override precedence, the operationally relevant defaults, signal handling, and worked examples.
zisk-coordinator is the cluster orchestrator.
It accepts proof requests from clients, fans work out to
registered workers, and serves /metrics and /health. CPU and
memory needs are modest; what matters is network headroom.
zisk-coordinator [OPTIONS]
Configuration
zisk-coordinator reads its settings from three sources, plus
built-in defaults for anything you don't set:
- TOML config files, from the well-known paths below and from
--config <PATH>. The canonical home for long-lived settings: ports, bind addresses, logging, metrics, coordinator-core tuning. The full schema is documented on Configuration. - Environment variables with the
ZISK_COORDINATOR_*prefix, plus the standardRUST_LOG. Use these for values that come from the deployment substrate rather than the application. Full mapping on CLI & environment. - Command-line flags for ports, log level, and the config path
itself. The narrowest layer; use for one-off testing,
container entrypoints, or the systemd unit's
ExecStart. Full flag list on CLI & environment.
Config file search order
The coordinator merges every config file it finds, in this order. A key set in a later file wins over the same key in an earlier one:
/etc/zisk/coordinator.toml(system-wide).$XDG_CONFIG_HOME/zisk/coordinator.toml, or~/.config/zisk/coordinator.tomlwhenXDG_CONFIG_HOMEis unset (per user)../coordinator.tomlin the working directory.- The file passed with
--configorZISK_COORDINATOR_CONFIG.
The first three are optional and skipped when missing. The
--config file must exist.
Override precedence
Settings are resolved in four layers, with later sources winning:
- Built-in defaults.
- TOML config files, in the search order above.
- Environment variables.
- Command-line flags.
Example: a TOML with [server].port = 7000 is shifted to 7001
by ZISK_COORDINATOR_API_PORT=7001, and to 8000 by
--api-port 8000 as CLI wins over env, env wins over TOML.
The log level doesn't follow this order. When RUST_LOG is set,
it decides the level and wins over both --log-level and
[logging].level; --log-level applies only while RUST_LOG is
unset.
Defaults
If you start zisk-coordinator with no flags and no config file,
the built-in defaults take over. The full schema is on
Configuration; the most operationally relevant
defaults are:
| Setting | Default | Override |
|---|---|---|
| Client-facing gRPC port | 7000 | [server].port / --api-port |
| Worker-facing gRPC port | 50051 | [coordinator].port / --cluster-port |
Metrics + /health port | 9090 | [metrics].port / --metrics-port |
| Bind address (API and metrics) | 0.0.0.0 | [server].host, [metrics].host |
| Bind address (worker port) | 0.0.0.0 | Not configurable |
| Log level | info | [logging].level / --log-level / RUST_LOG |
| Log format | pretty | [logging].format (no effect in 1.4.0-alpha) |
| Shutdown drain window | 30s | [server].shutdown_timeout_seconds |
| Environment label | development | [service].environment |
Worker registration
Any worker may take part in any job, and the one that aggregates also wraps the SNARK. So every worker in the cluster must share the same proving key. The coordinator checks two values each worker reports when it registers, and rejects a worker whose values differ from the workers already in the pool:
- Aggregation arity, a constant of the STARK proving key. A worker too old to report one is rejected too.
- SNARK protocol of its SNARK proving key (PLONK or
pilfflonk), or no SNARK key. A worker started without
--snarkreports no SNARK key. See zisk-worker / Proving keys.
The rejected worker logs Registration rejected: <reason>, for
example Worker <id> reports aggregation arity <n> but the cluster is on <m>; workers must share a proving key, and tries again
every [connection].reconnect_interval_seconds. When the pool is empty (the whole fleet
restarted, maybe with new keys), the first worker to register sets
the values again.
The coordinator keeps the programs set up on its workers only in
memory. After a coordinator restart, a prove or execute request
for a program fails with
PROGRAM_NOT_SETUP (1003) until the client runs
the setup again.
Signals
| Signal | Effect |
|---|---|
SIGTERM / SIGINT | Graceful shutdown. The coordinator stops accepting new jobs and waits up to [server].shutdown_timeout_seconds for in-flight jobs to drain. Jobs still running at the deadline are abandoned and surface as Failed from the client's view. |
SIGKILL | Forced exit. In-flight jobs are abandoned with no notification to workers; workers detect the disconnect via heartbeat timeout and clear their assignments. |
The coordinator does not persist job state across restarts; restarting drops every in-flight job. Plan capacity and restart windows accordingly.
Examples
Run with the canonical config installed by the deploy script:
zisk-coordinator --config /etc/zisk/coordinator.toml
Override ports — useful when running alongside another coordinator on the same host (Docker Compose's default for the supplied example) or behind a reverse proxy:
zisk-coordinator --config /etc/zisk/coordinator.toml \
--api-port 7001 --cluster-port 50052 --metrics-port 9091
Bump log verbosity for one-off debugging without touching the TOML:
zisk-coordinator --config /etc/zisk/coordinator.toml --log-level debug
The flag applies only while RUST_LOG is unset in the
coordinator's environment.