jolt run

Run ELF binaries on the Jolt emulator

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:

1. JOLT_EMU_PATH environment variable
2. System PATH
3. 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:

1. --jolt-emu flag - Explicit path provided
2. JOLT_EMU_PATH env var - Environment variable
3. System PATH - Uses which jolt-emu
4. 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

Related Commands

jolt build

Build guest binaries for the emulator

CLI Overview

Learn about all CLI commands