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

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

<Steps>
  <Step title="Install rustup">
    If you don't have Rust installed, get rustup from [rustup.rs](https://rustup.rs):

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
      ```

      ```powershell Windows theme={null}
      # Download and run rustup-init.exe from:
      # https://rustup.rs
      ```
    </CodeGroup>

    After installation, restart your terminal or run:

    ```bash theme={null}
    source $HOME/.cargo/env
    ```
  </Step>

  <Step title="Clone the Jolt repository">
    Clone the repository to access the CLI source:

    ```bash theme={null}
    git clone https://github.com/a16z/jolt.git
    cd jolt
    ```

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

  <Step title="Verify the toolchain">
    Check that rustup has activated the correct toolchain:

    ```bash theme={null}
    rustup show
    ```

    You should see output indicating:

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

    <Tip>
      The RISC-V targets are automatically installed when needed. You don't need to manually add them.
    </Tip>
  </Step>

  <Step title="Install the Jolt CLI">
    Build and install the `jolt` command-line tool:

    ```bash theme={null}
    cargo install --path .
    ```

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

    <Warning>
      After pulling updates from the Jolt repository, reinstall the CLI with `cargo install --path . --locked` to ensure guest builds work correctly.
    </Warning>
  </Step>

  <Step title="Verify installation">
    Confirm the CLI is available:

    ```bash theme={null}
    jolt --version
    ```

    You should see version information with a git hash and build date.
  </Step>
</Steps>

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

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

<Tip>
  Use the `--wasm` flag to generate WASM-compatible project files:

  ```bash theme={null}
  jolt new my-project --wasm
  ```
</Tip>

### `jolt build`

Builds a guest program for the Jolt zkVM:

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

<CodeGroup>
  ```bash Standard build theme={null}
  jolt build
  ```

  ```bash With debugging symbols theme={null}
  JOLT_BACKTRACE=1 jolt build
  ```

  ```bash Custom optimization level theme={null}
  JOLT_GUEST_OPT=2 jolt build
  ```
</CodeGroup>

### `jolt run`

Runs an ELF binary on the Jolt emulator:

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

<CodeGroup>
  ```bash Target spec theme={null}
  jolt generate target --profile default -o riscv64imac.json
  ```

  ```bash Linker script theme={null}
  jolt generate linker --ram-start 0x80000000 --ram-size 0x10000 -o linker.ld
  ```
</CodeGroup>

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

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Create your first provable function
  </Card>

  <Card title="Examples" icon="code" href="https://github.com/a16z/jolt/tree/main/examples">
    Explore example projects
  </Card>
</CardGroup>