Skip to main content

​
Requirements

A recommended minimum configuration for proving performance:
  • CPU - 16 threads, reasonable single core boost performance (>3Ghz)
  • RAM - 32 GB
  • Disk - 200 GB of solid state storage, NVME / SSD preferred
  • GPUs: at least one NVIDIA GPU with >= 8GB of VRAM.
    • In testing, we’ve found the best performance on the following NVIDIA GPUs: 4090, and L4.
    • While it’s possible to use a single GPU, we recommend at least 10 GPUs to run a competitive prover.
  • OS: Ubuntu 24.04 Full Virtual Machine or Bare Metal
The following tutorial will not work on standard dockerized cloud providers such as Vast.ai as the proving stack relies on Docker. We are in the process of working on some supervisord scripts and Docker images that would allow for a much cleaner setup in dockerized environments.

​
Clone the Boundless Repo

We recommend using Ubuntu 24.04 for your proving node.
To get started, first clone the Boundless monorepo on your proving machine, and switch to the latest release:
Terminal
git clone https://github.com/boundless-xyz/boundless
cd boundless
git checkout release-1.1

​
Install Dependencies

This stage can be skipped if you already have docker and docker-nvidia installed.
To run a Boundless prover, you’ll need the following dependencies: For a quick set up of Boundless dependencies on Ubuntu 24.04, please run: 
sudo ./scripts/setup.sh

​
Setup Environment Variables

You’ll need to set two environment variables:
Terminal
export PRIVATE_KEY=""
export RPC_URL=""
This is the private key to the wallet which will represent your prover on the market; make sure it has funds. For the RPC url, we recommend using either Alchemy or Quicknode paid RPC endpoints.
Note that the free RPC plans from either provider will not work for longer than a few hours, and therefore this may cause a prover to get slashed, if free RPC limits are hit, after some orders are locked.

​
Running a Test Proof

We make use of just to make running complex commands easier. To see available just commands for Boundless, run just within the root boundless/ folder.
Boundless is comprised of two major components:
  1. Bento is the local proving infrastructure. Bento will take requests, prove them and return the result.
  2. The Broker interacts with the Boundless market. Broker can submit or request proves from the market.
To get started with a test proof on a new proving machine, you’ll need to install the bento_cli:
Terminal
cargo install --locked --git https://github.com/boundless-xyz/boundless bento-client --branch release-1.1 --bin bento_cli
Once installed, you can run bento with:
Terminal
just bento
This will spin up bento without the broker. You can check the logs at any time with:
Terminal
just bento logs
To run the test proof:
Terminal
RUST_LOG=info bento_cli -c 32
If everything works, you should see something like the following: Bento CLI Test Proof Success

​
Running the Prover Setup Wizard

Once Bento is running successfully, it is time to configure the broker. The Boundless CLI provides an interactive setup wizard to help configure the broker.toml and compose.yml files.

​
Install the Boundless CLI

First, install the Boundless CLI (the Boundless CLI is separate to the Bento CLI we installed earlier): 
cargo install --locked --git https://github.com/boundless-xyz/boundless boundless-cli --branch release-1.1 --bin boundless
Once installed, run boundless to check it has been installed properly: Boundless CLI Homescreen

​
Run the Prover Setup Wizard

To run the prover setup wizard, run: 
boundless prover generate-config
and an interactive prompt will appear: Boundless CLI Prover Setup Wizard Answer the questions as required, based on your setup and requirements. Once finished, the broker.toml and compose.yml files will be created/edited.

​
Running the Broker

For technical support, please post your questions on the Boundless Discussions Forum.
We have checked that bento successfully generated a test proof. We are now ready to run the broker so that we can start proving on Boundless.

​
Deposit Collateral

$ZKC is only on Ethereum mainnet.Therefore, to use ZKC∗asprovingcollateral,provershavetofirst[bridge∗ZKC* as proving collateral, provers have to first [bridge *ZKC](/zkc/collateral) from Ethereum mainnet to Base mainnet.
With the environment variables set, you can now deposit $ZKC tokens as collateral to your account balance:
Terminal
boundless account deposit-collateral 50

​
Start Prover

You can now start the prover (which runs both bento + broker i.e. the full proving stack!):
Terminal
just prover
To check the proving logs, you can use:
Terminal
just prover logs

​
Stop Broker

To stop broker, you can run:
Terminal
just prover down
Or remove all volumes and data from the service:
Terminal
just prover clean

​
Configuring Broker

​
Custom Environment

Instead of passing environment variables for each shell session as we did above, you can set them in .env.broker. There is an .env.broker-template available for you to get started:
Terminal
cp .env.broker-template .env.broker
After which, you can use a text editor to adjust the environment variables as required. To run prover with a custom environment file:
Terminal
just prover up ./.env.broker
just prover down ./.env.broker

​
Broker.toml

Broker can be configured using the Broker.toml configuration file. For example, to adjust the maximum number of proofs that can be processed at once, you can set:
[boundless/Broker.toml]
# Maximum number of concurrent proofs that can be processed at once
max_concurrent_proofs = 2 # change "2"
To see all Broker.toml configuration settings, please see Broker Configuration & Operation/Settings in Broker.toml.

​
Multi Host

Services can be run on other hosts, as long as the IP addresses for things link PostgreSQL / Redis / MinIO are updated on the remote host. See the .env.broker-template HOST configuration options here to adjust them.

​
Configuring Bento

The compose.yml file defines all services within Bento. The Boundless repo includes a starter compose.yml which you can see here.

​
Multi GPU

Under the exec_agent service in compose.yml, the default configuration utilises a single GPU:
compose.yml
deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          device_ids: ['0']
          capabilities: [gpu]
To add a second GPU, first check your GPUs are recognised with:
Terminal
nvidia-smi -L
which should output something like: 
GPU 0: NVIDIA GeForce RTX 3090 (UUID: GPU-abcde123-4567-8901-2345-abcdef678901)
GPU 1: NVIDIA GeForce RTX 3090 (UUID: GPU-fedcb987-6543-2109-8765-abcdef123456)
We can see that GPU 1 is listed with the device ID of 1. To add this GPU, uncomment gpu_prove_agent1 from compose.yml:
compose.yml
gpu_prove_agent1: 
  <<: *agent-common
  runtime: nvidia
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            device_ids: ['1'] 
            capabilities: [gpu]
For 3 or more GPUs, add the corresponding gpu_prove_agentX where X matches the device ID of each GPU, making sure that the device_ids field is populated with a matching X: ['X'].

​
Segment Size

Larger SEGMENT_SIZE values also impact the proving systems conjectured security bits slightly (see RISC Zero - Cryptographic Security Model).
SEGMENT_SIZE is specified in powers-of-two (po2). Larger segment sizes are preferable for performance, but require more GPU VRAM. To pick the right SEGMENT_SIZE for your GPU VRAM, see the performance optimization page.

​
Setting SEGMENT_SIZE

The recommended way to change the segment size is to set the environment variable SEGMENT_SIZE, before running broker, to your specified value. This can be done through the .env.broker file. You can also configure the SEGMENT_SIZE in compose.yml under the exec_agent service; it defaults to 21:
compose.yml
exec_agent:
  <<: *agent-common
  runtime: nvidia

  mem_limit: 4G
  cpus: 4

  environment:
    <<: *base-environment
    RISC0_KECCAK_PO2: ${RISC0_KECCAK_PO2:-17}
    entrypoint: /app/agent -t exec --segment-po2 ${SEGMENT_SIZE:-21}

​
What next?

For technical support, please post your questions on the Boundless Discussions Forum.
Next, you’ll need to tune your Broker’s settings, please see Broker Optimization. If you’d like to learn more about the technical design of Bento, please see the Bento Technical Design. To see your prover market statistics, check out the provers page on the Boundless Explorer.