| name | proof-server:proof-server-configuration |
| description | This skill covers proof server CLI flags, environment variables, and tuning guidance. Use it when the user asks about proof server configuration, num-workers, job-capacity, job-timeout, no-fetch-params, how many workers should I use, proof server slow, proof server out of memory, proof server environment variables, proof server Docker configuration, port configuration, verbose mode, memory requirements, startup time, resource planning, or production settings. |
| version | 0.1.0 |
Proof Server Configuration
Complete reference for all CLI flags and environment variables that control the Midnight proof server. For basic Docker setup and running, see midnight-tooling:proof-server. For internal architecture, see proof-server:proof-server-architecture.
Replace <version> in image tags below with the version matching your target Midnight network. Check midnight-tooling:release-notes for current versions.
CLI Flags & Environment Variables
Every CLI flag has a corresponding environment variable. When both are set, the CLI flag takes precedence.
| Flag | Env Var | Default | Description |
|---|
-p, --port | MIDNIGHT_PROOF_SERVER_PORT | 6300 | HTTP listen port |
-v, --verbose | MIDNIGHT_PROOF_SERVER_VERBOSE | false | Enable DEBUG-level logging |
--job-capacity | MIDNIGHT_PROOF_SERVER_JOB_CAPACITY | 0 (unlimited) | Maximum number of pending jobs in the queue |
--num-workers | MIDNIGHT_PROOF_SERVER_NUM_WORKERS | 2 | Number of parallel proving threads |
--job-timeout | MIDNIGHT_PROOF_SERVER_JOB_TIMEOUT | 600.0 (10 min) | Job time-to-live in seconds before garbage collection |
--no-fetch-params | MIDNIGHT_PROOF_SERVER_NO_FETCH_PARAMS | false | Skip pre-fetching ZK parameters and proving keys on startup |
Flag Details
-p, --port
The HTTP port the proof server listens on. Change this when running multiple proof server instances or when port 6300 conflicts with another service.
midnight-proof-server --port 6301
MIDNIGHT_PROOF_SERVER_PORT=6301 midnight-proof-server
docker run -d --name midnight-proof-server -p 6301:6301 \
midnightntwrk/proof-server:<version> -- midnight-proof-server --port 6301
When changing the port with Docker, update both the container port (--port flag inside the container) and the Docker port mapping (-p flag).
-v, --verbose
Enables DEBUG-level logging output. Without this flag, only INFO and above are logged. Verbose mode is useful for diagnosing proving failures, timing issues, and key material fetching.
midnight-proof-server -v
docker run -d --name midnight-proof-server -p 6300:6300 \
midnightntwrk/proof-server:<version> -- midnight-proof-server -v
--num-workers
Controls how many proof generation tasks can run in parallel. Workers run on the shared tokio runtime and offload each job via spawn_blocking; a fresh current-thread tokio runtime is created per job inside the blocking closure.
midnight-proof-server --num-workers 4
MIDNIGHT_PROOF_SERVER_NUM_WORKERS=4 midnight-proof-server
docker run -d --name midnight-proof-server -p 6300:6300 \
midnightntwrk/proof-server:<version> -- midnight-proof-server --num-workers 4
Worker count does not need to match CPU core count exactly. Proving is CPU-intensive, so more workers than cores leads to contention. Fewer workers than cores leaves headroom for the HTTP server and garbage collection.
--job-capacity
Sets the maximum number of pending jobs in the worker pool queue. When the queue is full, new /prove requests receive HTTP 429 (Too Many Requests). A value of 0 (default) means unlimited queue depth.
midnight-proof-server --job-capacity 20
MIDNIGHT_PROOF_SERVER_JOB_CAPACITY=20 midnight-proof-server
Setting a capacity limit is recommended for production to prevent unbounded memory growth when the server receives more requests than it can process.
--job-timeout
Sets the time-to-live (TTL) in seconds for each job. A background garbage collector runs every 10 seconds and removes jobs that have exceeded this timeout. Applies to jobs in any state (pending, processing).
midnight-proof-server --job-timeout 300
MIDNIGHT_PROOF_SERVER_JOB_TIMEOUT=300 midnight-proof-server
The default of 600 seconds (10 minutes) is generous for most circuits. Complex circuits with high k-values may need longer timeouts. Simple circuits typically complete in under 30 seconds.
--no-fetch-params
Skips the pre-fetching of ZK public parameters (k=10 through k=15) and built-in proving keys (midnight/zswap/spend, midnight/zswap/output, midnight/zswap/sign, midnight/dust/spend) on startup. This makes the server available faster but defers the fetch cost to the first proof request for each circuit.
midnight-proof-server --no-fetch-params
MIDNIGHT_PROOF_SERVER_NO_FETCH_PARAMS=true midnight-proof-server
docker run -d --name midnight-proof-server -p 6300:6300 \
midnightntwrk/proof-server:<version> -- midnight-proof-server --no-fetch-params -v
Environment Profiles
Development
Default settings work well for development. The server starts with 2 workers and pre-fetches parameters.
docker run -d --name midnight-proof-server -p 6300:6300 \
midnightntwrk/proof-server:<version> -- midnight-proof-server -v
For faster startup during iterative development, skip parameter pre-fetching:
docker run -d --name midnight-proof-server -p 6300:6300 \
midnightntwrk/proof-server:<version> -- midnight-proof-server --no-fetch-params -v
Production
Scale workers based on available CPU cores and set capacity limits to prevent resource exhaustion:
docker run -d --name midnight-proof-server -p 6300:6300 \
--memory=8g \
midnightntwrk/proof-server:<version> -- midnight-proof-server \
--num-workers 8 \
--job-capacity 50 \
--job-timeout 300
CI / Testing
Minimal configuration for automated testing where fast startup matters more than throughput:
docker run -d --name midnight-proof-server -p 6300:6300 \
midnightntwrk/proof-server:<version> -- midnight-proof-server \
--no-fetch-params \
--num-workers 1 \
--job-capacity 5
Tuning Rationale
The configuration knobs map directly onto two phases of the proving pipeline. Workers control parallelism at the CPU level: each proof runs inside a spawn_blocking closure, pinning one physical core for its entire duration, so --num-workers should not exceed the cores available for proving work. The --no-fetch-params flag trades startup time for first-proof latency: omitting it causes the server to download ZK public parameters and built-in proving keys before the HTTP listener binds, which means the server is unavailable for several minutes but serves the first proof immediately; passing it inverts this trade-off and defers the fetch cost to the first request for each circuit. For a full description of how parameters and proving keys are stored and loaded at runtime, see proof-server:proof-server-architecture.
Tuning Guidance
Worker Count
| Scenario | Recommended --num-workers |
|---|
| Development (local machine) | 2 (default) |
| CI / testing | 1 |
| Production (4-core) | 3-4 |
| Production (8-core) | 6-8 |
| Production (16+ core) | 12-14 (leave cores for OS/HTTP) |
Proving is CPU-bound. Each worker occupies one core during proof generation. Leave 1-2 cores free for the HTTP server, garbage collection, and OS tasks.
Job Capacity
| Scenario | Recommended --job-capacity |
|---|
| Development | 0 (unlimited, default) |
| Production (small) | 10-20 |
| Production (large) | 50-100 |
Unlimited capacity is fine for development where request volume is low. In production, set capacity to prevent OOM when bursts of requests arrive faster than workers can process them.
Memory Requirements
| Configuration | Minimum RAM |
|---|
| Development (2 workers) | 4 GB |
| Production (4 workers) | 8 GB |
| Production (8 workers) | 16 GB |
Each worker holds proving keys and intermediate state in memory during proof generation. Complex circuits (high k-values) require more memory per worker. When running in Docker, set the container memory limit using --memory to match.
Startup Time
| Mode | Typical Startup Time |
|---|
| With pre-fetch (default) | 2-5 minutes (network and cache dependent) |
With --no-fetch-params | Under 5 seconds |
Pre-fetching downloads public parameters and proving keys from the network. Subsequent starts are faster if the cache is warm. The --no-fetch-params flag defers this cost to the first proof request, making the server available immediately but causing a delay on the first proof for each circuit.
Job Timeout
| Circuit Complexity | Recommended --job-timeout |
|---|
| Simple (k <= 12) | 120-300 seconds |
| Medium (k = 13-15) | 300-600 seconds |
| Complex (k > 15) | 600-1200 seconds |
The default 600-second timeout accommodates most circuits. Increase it only if you observe timeout-related job cancellations in the logs for legitimate proving requests.
