Quick Start

Clone the Boundless Repo

To get started, first clone the Boundless monorepo on your proving machine, and switch to the latest release:

git clone https://github.com/boundless-xyz/boundless
cd boundless
git checkout release-0.9

Install Dependencies

To run a Boundless prover, you'll need the following dependencies:

• Docker compose
• Docker Nvidia Support (Note: the install process requires enabling NVIDIA’s experimental packages)

For a quick set up of Boundless dependencies on Ubuntu 22.04 LTS (see Operating System Requirements), please run:

sudo ./scripts/setup.sh

Running a Test Proof

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:

cargo install --git https://github.com/risc0/risc0 bento-client --bin bento_cli

Once installed, you can run bento with:

just bento

This will spin up bento without the broker. You can check the logs at any time with:

just bento logs

To run the test proof:

RUST_LOG=info bento_cli -c 32

If everything works, you should see something like the following:

Running the Broker

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.

Install the Boundless CLI

Before we start, we'll need to install the Boundless CLI (which is separate to the Bento CLI we installed earlier):

cargo install --locked boundless-cli

Setup Environment Variables

To set the VERIFIER_ADDRESS, SET_VERIFIER_ADDRESS, BOUNDLESS_MARKET_ADDRESS automatically for Ethereum Sepolia, run:

source <(just env testnet)

You'll need to set two more environment variables yourself:

export PRIVATE_KEY=""
export RPC_URL=""

This is your wallet which will represent your prover on the market; make sure it has funds. For the RPC url, we recommend using Alchemy.

Deposit Stake

With the environment variables set, you can now deposit USDC tokens as stake to your account balance:

boundless account deposit-stake 100

Start Broker

You can now start broker (which runs both bento + broker i.e. the full proving stack!):

just broker

To check the proving logs, you can use:

just broker logs

Stop Broker

To stop broker, you can run:

just broker down

Or remove all volumes and data from the service:

just broker 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:

cp .env.broker-template .env.broker

After which, you can use a text editor to adjust the environment variables as required.

To run broker with a custom environment file:

just broker up ./.env.broker
just broker 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:

# 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:

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          device_ids: ['0']
          capabilities: [gpu]

To add a second GPU, first check your GPUs are recognised with:

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:

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

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:

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?

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.