Skip to main content

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:

FlagDefaultEnvDescription
--coordinator <URL>http://localhost:7000ZISK_COORDINATOR_URLCoordinator gRPC URL.
--connect-timeout <SECS>10Connection timeout in seconds.
--request-timeout <SECS>3600Per-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​

SubcommandDescription
uploadUpload a guest program (ELF) to the coordinator.
setupGenerate the proving setup on the remote service.
proveGenerate a proof on the remote service.
executeExecute a guest program on the remote service.
wrapWrap an existing proof on the remote service.
aggregateFold 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.

FlagShortDefaultDescription
--elf <ELF>-eauto-detectedPath to the guest ELF to upload. Auto-detected from the current project if omitted.
--aggregation <TOML>-aRegister 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​

FlagShortDefaultDescription
--elf <ELF>-eauto-detectedPath 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>-aSet 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.
--hintsfalseEnable precompiles hints support for this program.
--emulator-onlyfalseGenerate setup for the emulator only (supports execute, not prove).
note

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).

FlagShortDefaultDescription
--elf <ELF>-eautoPath to the guest ELF. Auto-detected from the current project if omitted.
--inputs <INPUTS>-iInput 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 seedUse 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.binSave the generated proof to this local path.
--minimal-cfalseSmaller STARK proof at the cost of longer proving time. Mutually exclusive with --pilfflonk and --plonk.
--pilfflonkfalsepilfflonk final SNARK proof for on-chain verification via the EVM verifier. Mutually exclusive with --plonk and --minimal.
--plonkfalsePLONK final SNARK proof. Advanced: only for workers loaded with a self-built Poseidon PLONK key. Mutually exclusive with --pilfflonk and --minimal.
--timeout <SECS>0Client-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​

FlagShortDefaultDescription
--elf <ELF>-eautoPath to the guest ELF. Auto-detected if omitted.
--inputs <INPUTS>-iInput 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 seedUse 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>0Client-side wait in seconds (0 = no timeout). On expiry the job is cancelled on the cluster.

remote wrap​

FlagShortDefaultDescription
--proof <PROOF>-prequiredPath to the STARK (VADCOP) proof file to wrap.
--output <OUTPUT>-o<unix-ts>-<job_id>-proof.binOutput file path.
--minimal-cfalseWrap into a smaller STARK proof. Mutually exclusive with --pilfflonk and --plonk.
--pilfflonkfalseWrap into a pilfflonk final SNARK proof for on-chain verification. Mutually exclusive with --plonk and --minimal.
--plonkfalseWrap 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>0Client-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.

FlagShortDefaultDescription
--aggregation <TOML>-arequiredAggregation definition: <programs>/aggregations/<name>.toml.
--proof-a <PATH>requiredFirst input proof (a prove or aggregate output file).
--proof-b <PATH>requiredSecond 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 verkeyrootCRecurserAgg 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.binSave the recurser proof to this local path.
--timeout <SECS>0Client-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).

note

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