> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/a16z/jolt/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
jolt run <BINARY> [OPTIONS] [-- EMU_ARGS...]
```

## Arguments

<ParamField path="BINARY" type="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.

  ```bash theme={null}
  jolt run target/riscv64imac-unknown-none-elf/release/guest
  ```
</ParamField>

## Options

<ParamField path="--jolt-emu" type="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`

  ```bash theme={null}
  jolt run guest.elf --jolt-emu /usr/local/bin/jolt-emu
  ```
</ParamField>

<ParamField path="EMU_ARGS" type="string[]">
  Additional arguments passed directly to `jolt-emu`.

  All arguments after `--` are forwarded to the emulator:

  ```bash theme={null}
  jolt run guest.elf -- --trace --verbose
  ```

  <Note>
    The `EMU_ARGS` are emulator-specific and depend on the `jolt-emu` implementation. Refer to `jolt-emu --help` for available options.
  </Note>
</ParamField>

## Environment Variables

<ParamField path="JOLT_EMU_PATH" type="path">
  Path to the `jolt-emu` binary. Alternative to `--jolt-emu` flag.

  ```bash theme={null}
  export JOLT_EMU_PATH=/usr/local/bin/jolt-emu
  jolt run guest.elf
  ```
</ParamField>

<ParamField path="JOLT_BACKTRACE" type="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

  ```bash theme={null}
  JOLT_BACKTRACE=1 jolt run guest.elf
  ```

  <Note>
    The emulator always captures the call stack. `JOLT_BACKTRACE` controls symbol resolution only.
  </Note>
</ParamField>

<ParamField path="RUST_LOG" type="string">
  Log level for the emulator. Valid values: `error`, `warn`, `info`, `debug`, `trace`.

  ```bash theme={null}
  RUST_LOG=debug jolt run guest.elf
  ```
</ParamField>

## Examples

### Basic Execution

Run a compiled guest binary:

```bash theme={null}
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:

```bash theme={null}
jolt run guest.elf --jolt-emu ./target/release/jolt-emu
```

### With Backtrace Enabled

Run with backtrace support for debugging:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
jolt run guest.elf -- --memory-limit 1G --trace
```

### With Environment Variable

Set emulator path via environment:

```bash theme={null}
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:

```bash theme={null}
# 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

```bash theme={null}
jolt run guest.elf
echo $?  # Check exit code
```

## Debugging Guest Programs

### Enable Backtraces

For panic debugging:

```bash theme={null}
# 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:

```rust theme={null}
// In no_std guests
use jolt::println;

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

```rust theme={null}
// 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:

```rust theme={null}
// 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

```bash theme={null}
# 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

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

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

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
JOLT_BACKTRACE=1 jolt build
JOLT_BACKTRACE=1 jolt run target/.../guest
```

## Related Commands

<CardGroup cols={2}>
  <Card title="jolt build" icon="hammer" href="/cli/build">
    Build guest binaries for the emulator
  </Card>

  <Card title="CLI Overview" icon="terminal" href="/cli/overview">
    Learn about all CLI commands
  </Card>
</CardGroup>