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

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

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

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

cargo test

As documented in 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:

cargo run --example view

This command builds and runs 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, 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:

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:

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

Then load a manifest and create a Planner instance:

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:

cargo run

The Planner struct defined in 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 — Workspace manifest that declares crate dependencies and feature flags.
• 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 — Contains the Manifest loader used to read MDL definitions into the planner.
• 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 — The full-featured wren CLI binary used for benchmarking and end-to-end testing.
• 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.

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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}