jolt run

The jolt run command executes a compiled RISC-V ELF binary on the Jolt emulator (jolt-emu), which emulates the zkVM environment for testing and development.

Usage

jolt run <BINARY> [OPTIONS] [-- EMU_ARGS...]

Arguments

BINARY

path

required

Path to the RISC-V ELF binary to execute.This should be a binary compiled with jolt build or a compatible RISC-V toolchain targeting RV64IMAC.

jolt run target/riscv64imac-unknown-none-elf/release/guest

Options

--jolt-emu

path

Path to the jolt-emu emulator binary.If not specified, the command searches in this order:

JOLT_EMU_PATH environment variable
System PATH
Common relative locations:
- target/release/jolt-emu
- target/debug/jolt-emu
- ../jolt/target/release/jolt-emu
- ../jolt/target/debug/jolt-emu

jolt run guest.elf --jolt-emu /usr/local/bin/jolt-emu

EMU_ARGS

string[]

Additional arguments passed directly to jolt-emu.All arguments after -- are forwarded to the emulator:

jolt run guest.elf -- --trace --verbose

The EMU_ARGS are emulator-specific and depend on the jolt-emu implementation. Refer to jolt-emu --help for available options.

Environment Variables

JOLT_EMU_PATH

path

Path to the jolt-emu binary. Alternative to --jolt-emu flag.

export JOLT_EMU_PATH=/usr/local/bin/jolt-emu
jolt run guest.elf

JOLT_BACKTRACE

string

Controls backtrace output when the guest panics.

1 - Enable backtraces with function names and file:line
full - Include register snapshots and cycle counts per frame

JOLT_BACKTRACE=1 jolt run guest.elf

The emulator always captures the call stack. JOLT_BACKTRACE controls symbol resolution only.

RUST_LOG

string

Log level for the emulator. Valid values: error, warn, info, debug, trace.

RUST_LOG=debug jolt run guest.elf

Examples

Basic Execution

Run a compiled guest binary:

jolt run target/riscv64imac-unknown-none-elf/release/guest

Output:

Running on Jolt emulator...

<guest program output>

With Explicit Emulator Path

Specify the emulator location:

jolt run guest.elf --jolt-emu ./target/release/jolt-emu

With Backtrace Enabled

Run with backtrace support for debugging:

JOLT_BACKTRACE=1 jolt run target/riscv64imac-unknown-none-elf/debug/guest

If the guest panics:

PANIC: panicked at guest/src/lib.rs:42:5: index out of bounds
ERROR tracer: Guest program terminated due to panic after 3696 cycles.
stack backtrace:
   0: 0x80000b38 - core::panicking::panic_fmt
                             at library/core/src/panicking.rs:75:14
   1: 0x800001ea - my_guest::process_data
                             at guest/src/lib.rs:42:5
   2: 0x80000192 - main
                             at guest/src/main.rs:8:5
   ...

With Full Debug Info

Show register state and cycle counts:

JOLT_BACKTRACE=full jolt run guest.elf

Output includes:

stack backtrace:
   0: 0x80000b38 - core::panicking::panic_fmt
                             at library/core/src/panicking.rs:75:14
                  registers: ra=0x800001e6, sp=0x80102fd0, gp=0x80003700
                  cycle: 357
   ...

Passing Emulator Arguments

Forward custom arguments to the emulator:

jolt run guest.elf -- --memory-limit 1G --trace

With Environment Variable

Set emulator path via environment:

export JOLT_EMU_PATH=/opt/jolt/bin/jolt-emu
jolt run guest.elf

Emulator Location

The jolt run command searches for jolt-emu in the following order:

--jolt-emu flag - Explicit path provided
JOLT_EMU_PATH env var - Environment variable
System PATH - Uses which jolt-emu
Common relative paths:
- target/release/jolt-emu
- target/debug/jolt-emu
- ../jolt/target/release/jolt-emu
- ../jolt/target/debug/jolt-emu

If none are found, the command fails with:

Error: jolt-emu not found. Please specify --jolt-emu or set JOLT_EMU_PATH environment variable

Installing jolt-emu

The emulator is part of the Jolt repository. To build it:

# Clone the Jolt repository
git clone https://github.com/a16z/jolt.git
cd jolt

# Build the emulator
cargo build --release -p tracer

# The binary is at: target/release/jolt-emu
# Optionally, install it to PATH
cargo install --path tracer

Exit Codes

The jolt run command exits with:

0 - Guest program completed successfully
1 - Guest program panicked or returned non-zero
Exit code - Propagates guest program’s exit code

jolt run guest.elf
echo $?  # Check exit code

Debugging Guest Programs

Enable Backtraces

For panic debugging:

# 1. Rebuild guest with symbols
JOLT_BACKTRACE=1 jolt build

# 2. Run with backtrace enabled
JOLT_BACKTRACE=1 jolt run target/.../debug/guest

Print Statements

Guest programs support println! for debugging:

// In no_std guests
use jolt::println;

#[jolt::provable]
fn my_function(x: u32) -> u32 {
    println!("Debug: x = {}", x);
    x * 2
}

// In std guests (automatic)
#[jolt::provable]
fn my_function(x: u32) -> u32 {
    println!("Debug: x = {}", x);  // Works out of the box
    x * 2
}

Trace Analysis

For detailed execution tracing without proving:

// Use trace_analyze instead of prove
let (output, device) = guest::trace_analyze_fib(50);

This runs the guest on the emulator but skips the expensive proving step, enabling faster iteration during development.

Emulator vs. Prover

Aspect	`jolt run` (Emulator)	`cargo run` (Prover)
Purpose	Test execution, debug	Generate proofs
Speed	Fast (seconds)	Slow (minutes)
Output	Program output	Proof + verification
Use case	Development, testing	Production proving

Workflow Example

# 1. Develop and test with emulator (fast iteration)
jolt build
jolt run target/.../guest  # Quick testing

# 2. Once working, generate proof
cargo run --release  # Full prove + verify

Limitations

The emulator does not produce cryptographic proofs. It only executes guest code for testing. To generate proofs, use the host code via cargo run.

Emulator Capabilities

✅ Executes RISC-V RV64IMAC instructions
✅ Supports syscalls (print, panic, I/O)
✅ Captures execution traces
✅ Detects panics and provides backtraces
✅ Measures cycle counts
❌ Does not generate zero-knowledge proofs
❌ Does not verify proofs

Troubleshooting

Binary Not Found

Error: Binary not found: target/.../guest

Solution: Build the guest first:

jolt build -- --release

Emulator Not Found

Error: jolt-emu not found. Please specify --jolt-emu or set JOLT_EMU_PATH

Solution: Install or build the emulator:

# Option 1: Set path to existing binary
export JOLT_EMU_PATH=/path/to/jolt-emu

# Option 2: Build from Jolt repo
git clone https://github.com/a16z/jolt.git
cd jolt
cargo build --release -p tracer
export JOLT_EMU_PATH=$(pwd)/target/release/jolt-emu

Execution Fails

Error: Failed to execute jolt-emu at /path/to/jolt-emu

Possible causes:

Emulator binary is not executable: chmod +x /path/to/jolt-emu
Wrong architecture (emulator must match host, not guest)
Corrupted binary: rebuild with cargo build -p tracer

Panic Without Backtrace

ERROR tracer: Guest program terminated due to panic after 3696 cycles.
  <no backtrace available>

Solution: Rebuild with symbols:

JOLT_BACKTRACE=1 jolt build
JOLT_BACKTRACE=1 jolt run target/.../guest

jolt build

Build guest binaries for the emulator

CLI Overview

Learn about all CLI commands

Get Started

Core Concepts

CLI Reference

Development

Usage

Arguments

Options

Environment Variables

Examples

Basic Execution

With Explicit Emulator Path

With Backtrace Enabled

With Full Debug Info

Passing Emulator Arguments

With Environment Variable

Emulator Location

Installing jolt-emu

Exit Codes

Debugging Guest Programs

Enable Backtraces

Print Statements

Trace Analysis

Emulator vs. Prover

Workflow Example

Limitations

Emulator Capabilities

Troubleshooting

Binary Not Found

Emulator Not Found

Execution Fails

Panic Without Backtrace

jolt build

CLI Overview

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Reference

Development

​Usage

​Arguments

​Options

​Environment Variables

​Examples

​Basic Execution

​With Explicit Emulator Path

​With Backtrace Enabled

​With Full Debug Info

​Passing Emulator Arguments

​With Environment Variable

​Emulator Location

​Installing jolt-emu

​Exit Codes

​Debugging Guest Programs

​Enable Backtraces

​Print Statements

​Trace Analysis

​Emulator vs. Prover

​Workflow Example

​Limitations

​Emulator Capabilities

​Troubleshooting

​Binary Not Found

​Emulator Not Found

​Execution Fails

​Panic Without Backtrace

​Related Commands

jolt build

CLI Overview

Build docs developers (and LLMs) love

Usage

Arguments

Options

Environment Variables

Examples

Basic Execution

With Explicit Emulator Path

With Backtrace Enabled

With Full Debug Info

Passing Emulator Arguments

With Environment Variable

Emulator Location

Installing jolt-emu

Exit Codes

Debugging Guest Programs

Enable Backtraces

Print Statements

Trace Analysis

Emulator vs. Prover

Workflow Example

Limitations

Emulator Capabilities

Troubleshooting

Binary Not Found

Emulator Not Found

Execution Fails

Panic Without Backtrace

Related Commands