Remote
Offloads proving to a remote coordinator instead of running the prover in-process. Documents the connection options and the upload, setup, prove, execute, wrap, and aggregate subcommands that mirror the local commands, plus job metadata, random seeds, cancellation and large inputs.
The cargo-zisk remote subcommands send work to a remote
coordinator instead of running the prover in-process. They mirror
the local commands (setup, prove, execute, wrap, aggregate) and add
upload, which ships the guest ELF to the coordinator.
cargo-zisk remote <SUBCOMMAND> [OPTIONS]
Connecting to the coordinator
These options are global to every remote subcommand:
| Flag | Default | Env | Description |
|---|---|---|---|
--coordinator <URL> | http://localhost:7000 | ZISK_COORDINATOR_URL | Coordinator gRPC URL. |
--connect-timeout <SECS> | 10 | Connection timeout in seconds. | |
--request-timeout <SECS> | 3600 | Per-request transport timeout in seconds. |
prove, execute, wrap and aggregate also have their own --timeout
(default 0 = no timeout). It is a client-side wait, separate from the
transport-level --request-timeout: when it expires, the CLI cancels the
job on the cluster and fails with job timed out after <N>s.
Pressing Ctrl-C while the CLI waits for a setup, prove, execute, wrap
or aggregate job also cancels it on the cluster, and the command fails with
job interrupted. The CLI logs Job <why>; cancelled it, or
Job <why>; it had already ended if the job finished first.
Subcommands
| Subcommand | Description |
|---|---|
upload | Upload a guest program (ELF) to the coordinator. |
setup | Generate the proving setup on the remote service. |
prove | Generate a proof on the remote service. |
execute | Execute a guest program on the remote service. |
wrap | Wrap an existing proof on the remote service. |
aggregate | Fold two proofs into one recurser proof on the remote service. |
remote upload
Uploads the guest ELF so the coordinator has the program to run and
prove. Later commands can reference it by its returned hash_id.
| Flag | Short | Default | Description |
|---|---|---|---|
--elf <ELF> | -e | auto-detected | Path to the guest ELF to upload. Auto-detected from the current project if omitted. |
--aggregation <TOML> | -a | Register an aggregation definition (<programs>/aggregations/<name>.toml) as a recurser instead of a guest ELF. Idempotent: the same definition always resolves to the same content-addressed recurser ID. Conflicts with --elf and --bin. |
--release / --debug / --bin select the profile and binary when
auto-detecting the ELF. remote setup, remote prove and remote execute
accept the same three flags. The default is the debug profile, so without
--release the command fails with could not detect a debug project ELF when
only a release build exists.
remote setup
| Flag | Short | Default | Description |
|---|---|---|---|
--elf <ELF> | -e | auto-detected | Path to the guest ELF. Uploads the program, then runs setup. Conflicts with --hash-id and --aggregation. |
--hash-id <HASH_ID> | hash_id of an already-uploaded program. Runs setup only, skipping the upload. | ||
--aggregation <TOML> | -a | Set up an aggregation definition as a recurser. Uploads the recurser spec (idempotent), then runs the setup job. Conflicts with --hash-id, --bin, --hints and --emulator-only. | |
--hints | false | Enable precompiles hints support for this program. | |
--emulator-only | false | Generate setup for the emulator only (supports execute, not prove). |
For a recurser setup, the local vadcop_final verkey must match the workers'
(the same setup version), or the derived recurser ID diverges.
remote prove
The program must already be registered and set up (run remote setup first).
| Flag | Short | Default | Description |
|---|---|---|---|
--elf <ELF> | -e | auto | Path to the guest ELF. Auto-detected from the current project if omitted. |
--inputs <INPUTS> | -i | Input for the guest. Accepts a file path, file://path, or inline inline://[[1,2],[3]]. | |
--hints <HINTS> | Precompiles hints URI for the guest, read and sent inline to the coordinator. quic:// is not supported from the CLI. | ||
--random-seed <HEX> | fresh seed | Use this random seed instead of drawing a fresh one. See Random seeds. | |
--metadata <KEY=VALUE> | Attach a label to the job. Repeatable. See Job metadata. | ||
--output <OUTPUT> | -o | <unix-ts>-<job_id>-proof.bin | Save the generated proof to this local path. |
--minimal | -c | false | Smaller STARK proof at the cost of longer proving time. Mutually exclusive with --pilfflonk and --plonk. |
--pilfflonk | false | pilfflonk final SNARK proof for on-chain verification via the EVM verifier. Mutually exclusive with --plonk and --minimal. | |
--plonk | false | PLONK final SNARK proof. Advanced: only for workers loaded with a self-built Poseidon PLONK key. Mutually exclusive with --pilfflonk and --minimal. | |
--timeout <SECS> | 0 | Client-side wait in seconds (0 = no timeout). On expiry the job is cancelled on the cluster. |
The SNARK protocol is set by the workers' SNARK proving key, and the flag must
name it. The coordinator refuses a SNARK the workers cannot prove with error
1008 (SNARK_UNAVAILABLE), and the client checks that the SNARK it gets back
is the protocol it asked for. See
Choosing a proof format.
remote execute
| Flag | Short | Default | Description |
|---|---|---|---|
--elf <ELF> | -e | auto | Path to the guest ELF. Auto-detected if omitted. |
--inputs <INPUTS> | -i | Input for the guest. File path, file://path, or inline inline://[[1,2],[3]]. | |
--hints <HINTS> | Precompiles hints URI for the guest, read and sent inline. quic:// is not supported. | ||
--random-seed <HEX> | fresh seed | Use this random seed instead of drawing a fresh one. See Random seeds. | |
--metadata <KEY=VALUE> | Attach a label to the job. Repeatable. See Job metadata. | ||
--timeout <SECS> | 0 | Client-side wait in seconds (0 = no timeout). On expiry the job is cancelled on the cluster. |
remote wrap
| Flag | Short | Default | Description |
|---|---|---|---|
--proof <PROOF> | -p | required | Path to the STARK (VADCOP) proof file to wrap. |
--output <OUTPUT> | -o | <unix-ts>-<job_id>-proof.bin | Output file path. |
--minimal | -c | false | Wrap into a smaller STARK proof. Mutually exclusive with --pilfflonk and --plonk. |
--pilfflonk | false | Wrap into a pilfflonk final SNARK proof for on-chain verification. Mutually exclusive with --plonk and --minimal. | |
--plonk | false | Wrap into a PLONK final SNARK proof (self-built Poseidon PLONK key on the workers). Mutually exclusive with --pilfflonk and --minimal. | |
--metadata <KEY=VALUE> | Attach a label to the job. Repeatable. See Job metadata. | ||
--timeout <SECS> | 0 | Client-side wait in seconds (0 = no timeout). On expiry the job is cancelled on the cluster. |
As with the local wrap, one of --minimal, --pilfflonk or --plonk is required.
remote aggregate
Folds two proofs into one recurser proof. The recurser must already be set up
(run remote setup --aggregation first); the command re-registers the spec
(idempotent) before submitting the job. See
Aggregate for the aggregation TOML and the
local equivalent.
| Flag | Short | Default | Description |
|---|---|---|---|
--aggregation <TOML> | -a | required | Aggregation definition: <programs>/aggregations/<name>.toml. |
--proof-a <PATH> | required | First input proof (a prove or aggregate output file). | |
--proof-b <PATH> | required | Second input proof. | |
--free-inputs-a <U64,...> | Comma-separated u64s: proof_a's free array. Must be exactly n_free values; omit only when the recurser declares n_free = 0. | ||
--free-inputs-b <U64,...> | Comma-separated u64s: proof_b's free array, under the same rule. | ||
--root-c-recurser-agg <LIMBS> | recurser verkey | rootCRecurserAgg as 4 comma-separated decimal limbs. Omit to use the recurser's own verkey. | |
--metadata <KEY=VALUE> | Attach a label to the job. Repeatable. See Job metadata. | ||
--output <OUTPUT> | -o | <unix-ts>-<job_id>-proof.bin | Save the recurser proof to this local path. |
--timeout <SECS> | 0 | Client-side wait in seconds (0 = no timeout). On expiry the job is cancelled on the cluster. |
Job metadata
--metadata KEY=VALUE attaches a label to a prove, execute, wrap or
aggregate job. The coordinator keeps it with the job and logs it when the job
completes. Repeat the flag for more labels; a key given twice keeps its last
value. The entry is split at the first =, so the value may contain more.
The coordinator accepts at most 32 entries, with keys of up to 128 bytes and
values of up to 1024 bytes. A coordinator with allow_job_metadata = false
refuses any job that carries metadata with error 1007
(JOB_METADATA_NOT_ALLOWED).
The CLI prints only the coordinator's gRPC error message, not the numeric codes listed on this page. Use the message text, or the coordinator's logs, to match an error to its code.
Random seeds
--random-seed <HEX> (or ZISK_RANDOM_SEED) on prove and execute pins the
host randomness seed, up to 64 hex characters zero-padded on the left. The
coordinator rejects it with error 1006 (CLIENT_RANDOM_SEED_NOT_ALLOWED)
unless it is configured with allow_client_random_seed = true. Without the
flag the cluster draws a fresh seed, and the summary prints the Random seed:
the job used. See Host randomness.
Large inputs
The input travels inline with the job request when it fits, together with the
hints, in 127 MiB. A larger input is streamed to the coordinator over gRPC
automatically; you don't need to change anything. An input larger than the
guest's input region (2 GiB − 16 bytes) is refused by the CLI before it is
sent, and a pushed stream that exceeds it fails with error 1009
(INPUT_TOO_LARGE). Hints are always sent inline, so hints data over 127 MiB
is refused.
See Coordinator error codes for the full list.
Example
Point the CLI at a coordinator, then upload, set up, prove, and verify the downloaded proof locally:
export ZISK_COORDINATOR_URL=http://my-prover:7000
cargo-zisk build --release
cargo-zisk remote upload --release
cargo-zisk remote setup --release
cargo-zisk remote prove --release -i input.bin -o proof.bin
cargo-zisk verify -p proof.bin
Request a pilfflonk final SNARK, label the job, and give up (cancelling it on the cluster) after one hour:
cargo-zisk remote prove --release -i input.bin --pilfflonk \
--metadata team=bridge --metadata run=nightly \
--timeout 3600 -o proof.snark