Installation

Install Rust and the Jolt CLI to start building zkVM applications

Prerequisites

Jolt requires Rust nightly version 1.88 with RISC-V target support.

1. Install rustup

   If you don’t have Rust installed, get rustup from rustup.rs:

   macOS/Linux

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

   After installation, restart your terminal or run:

   source $HOME/.cargo/env
   
2. Clone the Jolt repository

   Clone the repository to access the CLI source:

   git clone https://github.com/a16z/jolt.git
   cd jolt
   

   The repository includes a rust-toolchain.toml file that automatically configures the correct Rust version and targets when you run cargo commands.

3. Verify the toolchain

   Check that rustup has activated the correct toolchain:

   rustup show
   

   You should see output indicating:

   • Rust channel: 1.88
   • Targets: riscv32imac-unknown-none-elf, riscv64imac-unknown-none-elf

   The RISC-V targets are automatically installed when needed. You don’t need to manually add them.

4. Install the Jolt CLI

   Build and install the jolt command-line tool:

   cargo install --path .
   

   This compiles the Jolt CLI and places it in ~/.cargo/bin/. The installation may take a few minutes.

   After pulling updates from the Jolt repository, reinstall the CLI with cargo install --path . --locked to ensure guest builds work correctly.

5. Verify installation

   Confirm the CLI is available:

   jolt --version
   

   You should see version information with a git hash and build date.

Jolt CLI Commands

The Jolt CLI provides several commands for working with zkVM projects:

jolt new

Creates a new Jolt project with the specified name:

jolt new my-project

This generates a workspace with:

• src/main.rs - Host program that compiles, proves, and verifies the guest
• guest/ - Guest program directory containing provable functions
• Cargo.toml - Workspace configuration with Jolt dependencies
• rust-toolchain.toml - Rust toolchain specification

Use the --wasm flag to generate WASM-compatible project files:

jolt new my-project --wasm

jolt build

Builds a guest program for the Jolt zkVM:

jolt build

This command:

• Compiles guest code to RISC-V ELF binaries
• Applies Jolt-specific optimizations (-Copt-level=3, -Cpasses=lower-atomic)
• Configures the custom linker script for zkVM memory layout
• Strips symbols by default (use JOLT_BACKTRACE=1 to preserve them)

Standard build

jolt build

jolt run

Runs an ELF binary on the Jolt emulator:

jolt run path/to/binary.elf

This executes the program using Jolt’s RISC-V tracer without generating a proof. Useful for quick testing and debugging.

jolt generate

Generates target specifications or linker scripts:

Target spec

jolt generate target --profile default -o riscv64imac.json

Environment Variables

Customize Jolt’s behavior with these environment variables:

Variable	Default	Description
JOLT_GUEST_OPT	3	Guest optimization level (0, 1, 2, 3, s, z)
JOLT_BACKTRACE	(unset)	Enable backtrace support. Set to 1 for symbols, full for detailed traces
JOLT_EMU_PATH	(auto-detected)	Path to jolt-emu binary

Next Steps

Quickstart Guide

Create your first provable function

Examples

Explore example projects