Installation & Hello World

Before diving into the APIs, let’s make sure everything works. We’ll install the toolchain, scaffold a project, and prove a simple program end to end.

Prerequisites

• Rust nightly toolchain from rust-toolchain.toml
• clang available in PATH
• cargo-binutils for cargo objcopy
• Docker (only needed for cargo airbender build --reproducible)

Install cargo-binutils:

cargo install cargo-binutils --locked

Install cargo airbender

From a local clone:

cargo install --path crates/cargo-airbender --force

Or directly from the repository:

cargo install --git https://github.com/matter-labs/airbender-platform --branch main cargo-airbender --force

GPU support is enabled by default, so prove --backend gpu and generate-vk work out of the box. To install without GPU support:

cargo install --path crates/cargo-airbender --no-default-features --force

You can compile (but not run) GPU-dependent code without NVIDIA hardware by setting ZKSYNC_USE_CUDA_STUBS=true.

Create Your First Project

Scaffold a new host+guest project:

cargo airbender new ./hello-airbender

The command asks for a project name, whether to enable std, which allocator to use, and which prover backend (dev or gpu). For now, accept the defaults.

For CI or scripted usage, pass --yes to skip prompts: cargo airbender new ./hello-airbender --yes --name hello-airbender

The generated project has two crates:

• guest/ - a RISC-V program that reads a u32 input and returns value + 1
• host/ - a native Rust program that feeds inputs and runs the guest

Build the guest:

cd hello-airbender/guest
cargo airbender build

This produces artifacts in dist/app/:

dist/app/app.bin
dist/app/app.elf
dist/app/app.text
dist/app/manifest.toml

Now run it from the host:

cd ../host
cargo run --release

You should see the execution output. The host feeds 41 as input, the guest returns 42.

Prove Your First Program

Generate and verify a dev proof:

cargo run --release -- --prove

That’s it. The host runs the guest, generates a proof, and verifies it. The dev backend doesn’t require a GPU and is meant for local development.

For real GPU proving, see Proving Hardware below and the CLI Reference.

What Just Happened?

The generated guest/.cargo/config.toml configures the RISC-V target and build flags. This means plain cargo build and cargo check also work for the guest. cargo airbender build adds artifact packaging on top (binary, ELF, text sections, manifest with SHA-256 hashes).

The host uses airbender-host to load the guest binary, serialize inputs with Inputs::push(...), and call the runner/prover APIs. See Host Program API for the full API.

CLI-Only Workflow

You can also run and prove guest programs directly from the CLI without writing a host program.

Create an input file (hex-encoded u32 words, 8 hex chars per word):

This is a codec-v0 payload for u32 = 41.

printf '00000001\n29000000\n' > input.hex

Run:

cargo airbender run ./dist/app/app.bin --input ./input.hex

Prove with the dev backend:

cargo airbender prove ./dist/app/app.bin --input ./input.hex --output ./proof.bin --backend dev

Or with the GPU backend (requires compatible hardware):

cargo airbender prove ./dist/app/app.bin --input ./input.hex --output ./proof.bin --backend gpu --level base
cargo airbender generate-vk ./dist/app/app.bin --output ./vk.bin --level base
cargo airbender verify-proof ./proof.bin --vk ./vk.bin

Real proving defaults to 100-bit security. Add --security 80 to both prove and generate-vk only when you need legacy 80-bit artifacts.

For non-trivial inputs, use the host-side Inputs::push(...) API and write_hex_file(...) to generate input files. See Host Program API.

Proving Hardware

No specialized hardware is needed for development. The proving backends have different requirements:

Next Steps

• Read the Guest Program API to learn how to write real guest programs.
• Read the Host Program API to learn how to feed inputs and verify proofs.
• Browse the examples for complete working projects.