# How to Run the Rust-Based wren-core Engine Locally for Development

> Easily run the Rust wren-core engine locally for development. Clone Canner/WrenAI, install Rust, and run the engine or REPL demo with simple Cargo commands.

- Repository: [Canner/WrenAI](https://github.com/Canner/WrenAI)
- Tags: how-to-guide
- Published: 2026-07-20

---

**To run the Rust-based wren-core engine locally for development, clone the Canner/WrenAI repository, install a Rust toolchain, and execute `cargo run --example view` for a quick REPL-style demo or `cargo run --release --bin wren` for the full command-line engine.**

The wren-core engine is the Rust-based query planning core of the WrenAI project, built on Apache DataFusion and organized as a pure Rust library inside the `core/wren-core` crate. Running the engine on your local machine requires only `rustup` and `cargo`, plus a few standard commands to build, test, and execute the provided examples. This guide walks through the exact steps to compile wren-core, launch the example binaries, and embed the planner in your own Rust code.

## Clone the Repository and Build the Workspace

Start by pulling the entire codebase and compiling the Rust workspace that contains the core crate.

### Clone the Source Code

```bash
git clone https://github.com/Canner/WrenAI.git
cd WrenAI

```

This downloads the full project, including the `core/wren-core` crate and its examples.

### Install the Rust Toolchain

If you do not already have Rust installed, follow the official installer at https://www.rust-lang.org/tools/install. This provides `rustc`, `cargo`, and the standard build utilities needed by the workspace.

### Compile All Crates

```bash
cargo build --workspace

```

This command compiles every crate in the workspace, including dependencies for the DataFusion-based engine. Incremental compilation means subsequent builds are fast when you edit source files.

## Run Tests and Example Binaries

Once the workspace compiles, you can verify functionality and explore the engine through built-in examples.

### Run the Unit Test Suite

```bash
cargo test

```

As documented in [`core/wren-core/README.md`](https://github.com/Canner/WrenAI/blob/main/core/wren-core/README.md), this executes the full test suite and confirms that the query planner and MDL manifest loader work correctly on your machine.

### Start the Interactive view Example

The fastest way to see the engine in action is the `view` example shipped in the `wren-example` crate:

```bash
cargo run --example view

```

This command builds and runs [`core/wren-core/wren-example/examples/view.rs`](https://github.com/Canner/WrenAI/blob/main/core/wren-core/wren-example/examples/view.rs), which instantiates a DataFusion `SessionContext`, registers a sample Wren MDL model, parses a SQL string through the `Planner`, and prints the resulting logical plan. You should see output similar to:

```

=== Wren Model ===
[Model definitions …]

=== Logical Plan ===
Projection: …

```

Other example binaries, such as [`plan-sql.rs`](https://github.com/Canner/WrenAI/blob/main/plan-sql.rs), are available in the same directory and follow the same pattern.

## Launch the Full wren Engine Binary

For a production-like local run, build and execute the `wren` binary located at [`core/wren-core/benchmarks/src/bin/wren.rs`](https://github.com/Canner/WrenAI/blob/main/core/wren-core/benchmarks/src/bin/wren.rs):

```bash
cargo run --release --bin wren -- \
    --manifest ./path/to/manifest.json \
    --sql "SELECT revenue FROM revenue_by_region WHERE region='EMEA'"

```

This command exposes the same API surface as the production server, including SQL planning and dry-run capabilities, without requiring the full Python or Node.js server stack.

## Embed wren-core in Your Own Rust Project

You can also import the library into an external crate and drive the engine programmatically.

Add a path dependency in your [`Cargo.toml`](https://github.com/Canner/WrenAI/blob/main/Cargo.toml):

```toml
[dependencies]
wren-core = { path = "../WrenAI/core/wren-core" }

```

Then load a manifest and create a `Planner` instance:

```rust
use wren_core::planner::Planner;
use wren_core::mdl::manifest::Manifest;

fn main() -> anyhow::Result<()> {
    let manifest = Manifest::load(
        "../WrenAI/core/wren-core/wren-example/examples/datafusion-apply/manifest.json"
    )?;
    let planner = Planner::new(manifest);
    let plan = planner.plan("SELECT * FROM sales LIMIT 10")?;
    println!("{:#?}", plan);
    Ok(())
}

```

Run your program with:

```bash
cargo run

```

The `Planner` struct defined in [`core/wren-core/core/src/lib.rs`](https://github.com/Canner/WrenAI/blob/main/core/wren-core/core/src/lib.rs) is the primary public entry point. It consumes a `Manifest`—typically generated by the Python bindings—and returns a DataFusion logical plan that you can inspect or execute.

## Key Source Files in the wren-core Crate

Understanding the layout of `core/wren-core` helps when you need to debug or extend the engine:

- **[`core/wren-core/Cargo.toml`](https://github.com/Canner/WrenAI/blob/main/core/wren-core/Cargo.toml)** — Workspace manifest that declares crate dependencies and feature flags.
- **[`core/wren-core/core/src/lib.rs`](https://github.com/Canner/WrenAI/blob/main/core/wren-core/core/src/lib.rs)** — Public library entry point where `Planner` and `SessionContext` wrappers are exported.
- **[`core/wren-core/core/src/mdl/manifest.rs`](https://github.com/Canner/WrenAI/blob/main/core/wren-core/core/src/mdl/manifest.rs)** — Contains the `Manifest` loader used to read MDL definitions into the planner.
- **[`core/wren-core/wren-example/examples/view.rs`](https://github.com/Canner/WrenAI/blob/main/core/wren-core/wren-example/examples/view.rs)** — Minimal runnable demo that prints a logical plan from a sample model.
- **[`core/wren-core/benchmarks/src/bin/wren.rs`](https://github.com/Canner/WrenAI/blob/main/core/wren-core/benchmarks/src/bin/wren.rs)** — The full-featured `wren` CLI binary used for benchmarking and end-to-end testing.
- **[`core/wren-core/README.md`](https://github.com/Canner/WrenAI/blob/main/core/wren-core/README.md)** — High-level build, test, and formatting instructions for contributors.

## Summary

- The wren-core engine lives in `core/wren-core` and is built on Apache DataFusion.
- Install Rust, clone `Canner/WrenAI`, and run `cargo build --workspace` to compile.
- Execute `cargo test` to verify the engine and `cargo run --example view` for an instant hands-on demo.
- Launch the full CLI with `cargo run --release --bin wren -- <args>` to exercise SQL planning against your own MDL manifest.
- Embed the crate in your own Rust project by depending on `wren-core` and using the `Planner` and `Manifest` APIs exposed in [`core/wren-core/core/src/lib.rs`](https://github.com/Canner/WrenAI/blob/main/core/wren-core/core/src/lib.rs).

## Frequently Asked Questions

### Do I need Docker to run wren-core locally?

No. The wren-core crate is a pure Rust library and does not require Docker or any additional services. You only need the Rust toolchain installed via `rustup`.

### What is the fastest way to see the engine working?

Run the built-in example with `cargo run --example view`. This loads a sample MDL manifest, parses a SQL query, and prints the logical plan without any extra configuration.

### How do I connect wren-core to my own MDL manifest?

Pass the path to your manifest JSON or YAML file when constructing the `Manifest` object in Rust, or supply the `--manifest` flag when running the `wren` binary. The manifest format is consumed by the loader in [`core/wren-core/core/src/mdl/manifest.rs`](https://github.com/Canner/WrenAI/blob/main/core/wren-core/core/src/mdl/manifest.rs).

### Can I run wren-core without the rest of the WrenAI server stack?

Yes. The `wren-example` binaries and the `wren` CLI binary are self-contained Rust programs. They do not depend on the Python bindings, Node.js services, or external containers, making them ideal for isolated engine development.