# How to Run OpenLogi in Development Mode with `cargo run`

> Easily run OpenLogi in development mode with cargo run. Launch the desktop UI in debug mode and control mock agents with environment variables for efficient local testing.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-08-31

---

**Run OpenLogi locally using `cargo run -p openlogi-desktop` to build and launch the desktop UI in debug mode, with optional environment variables to control mock agent behavior and enable diagnostic tools.**

OpenLogi is a Rust-based logistics platform with a desktop UI and modular agent architecture. During development, you can iterate rapidly using Cargo's built-in runner without building full release bundles. This guide covers the exact commands, environment variables, and source locations you need to run OpenLogi in development mode.

---

## Pre-flight Check: Verify the Build

Before launching, confirm the desktop crate compiles cleanly:

```bash
cargo check -p openlogi-desktop

```

This validates dependencies and catches compile errors without producing a full binary. Skipping this step is fine for quick iteration, but `cargo check` saves time when refactoring across crates.

---

## Basic Development Run

The simplest way to start OpenLogi in development mode:

```bash
cargo run -p openlogi-desktop

```

This command, documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) at line 34, builds `openlogi-desktop` in debug mode and immediately executes it. By default, the application automatically spawns a temporary **mock agent** that provides scripted inventory data over IPC.

The entry point reading this behavior is located in [`crates/openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs), where the runtime checks environment variables before initializing the agent subsystem.

---

## Environment Variables for Development Control

OpenLogi's development mode responds to two primary environment variables. Set these before the `cargo run` command to modify runtime behavior.

### Disable Automatic Mock Agent: `OPENLOGI_DEV_AGENT`

When you need manual control over the agent lifecycle—such as running a custom agent implementation or debugging agent-desktop communication—disable auto-spawn:

```bash
OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

```

With `OPENLOGI_DEV_AGENT=0`, the desktop UI starts without any agent connection. You must provide your own agent in a separate terminal (see the next section).

This variable is evaluated at [`crates/openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs) line 65 according to the source.

### Enable Component Gallery: `OPENLOGI_COMPONENT_GALLERY`

For UI development and debugging, launch with the component gallery enabled:

```bash
OPENLOGI_COMPONENT_GALLERY=1 cargo run -p openlogi-desktop

```

The **Component Gallery** exposes isolated UI components for visual regression testing and rapid iteration. This feature is available only in debug builds and is documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) at line 135.

---

## Running a Standalone Mock Agent

For scenarios requiring full control—such as testing specific agent states or running modified agent code—start the mock agent separately:

```bash
cargo run -p openlogi-agent --bin openlogi-agent-mock

```

This executes the binary defined in [`crates/openlogi-agent/src/bin/mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/bin/mock_agent.rs). The mock agent implements the full agent protocol and serves scripted inventory over the IPC socket used by the desktop UI.

**Typical two-terminal workflow:**

```bash

# Terminal 1: Start standalone mock agent

cargo run -p openlogi-agent --bin openlogi-agent-mock

# Terminal 2: Launch desktop with external agent

OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

```

This pattern appears in the *Dev-run* entry of [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) at line 218, which describes the architecture for development runs.

---

## Release Builds for Performance Testing

When validating performance or preparing for distribution testing, build with release optimizations:

```bash
cargo run -p openlogi-desktop --release

```

Note that **release builds ignore the component gallery flag**—the `OPENLOGI_COMPONENT_GALLERY` check is compiled out in release mode as implemented in [`crates/openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs).

---

## Key Source Files and Architecture

Understanding these locations helps when tracing behavior or extending the development workflow:

| File | Purpose |
|------|---------|
| [`crates/openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs) | Desktop entry point; reads `OPENLOGI_DEV_AGENT` and `OPENLOGI_COMPONENT_GALLERY` environment variables |
| [`crates/openlogi-agent/src/bin/mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/bin/mock_agent.rs) | Standalone mock agent binary for development IPC testing |
| [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) | Consolidated development instructions and environment variable reference |
| [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) | High-level architecture with the "Dev-run" workflow specification |
| [`xtask/README.md`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/README.md) | Helper tasks for bundling (not required for basic development runs) |

The automatic mock agent spawn logic and component gallery gating are both implemented in the desktop crate's main function, making [`crates/openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs) the authoritative source for runtime behavior.

---

## Summary

- **`cargo run -p openlogi-desktop`** — Run OpenLogi in development mode with automatic mock agent
- **`OPENLOGI_DEV_AGENT=0`** — Disable auto-spawn for manual agent control
- **`OPENLOGI_COMPONENT_GALLERY=1`** — Enable UI debugging gallery (debug builds only)
- **`cargo run -p openlogi-agent --bin openlogi-agent-mock`** — Run standalone agent in separate terminal
- **`--release`** flag — Build optimized binary for performance validation

These commands, defined across [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) and [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md), provide a complete local development workflow for the OpenLogi platform.

---

## Frequently Asked Questions

### How do I run OpenLogi without the mock agent?

Set `OPENLOGI_DEV_AGENT=0` before your cargo command: `OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop`. The desktop UI will start without any agent connection, allowing you to connect a custom agent implementation or test disconnected behavior.

### Can I enable the component gallery in release builds?

No. The component gallery is explicitly gated to debug builds only in [`crates/openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs). The environment variable check is compiled out when building with `--release`, ensuring no diagnostic overhead in production binaries.

### What's the difference between `cargo check` and `cargo run` for OpenLogi?

`cargo check -p openlogi-desktop` validates compilation without producing a binary—useful for rapid feedback during refactoring. `cargo run -p openlogi-desktop` performs a full debug build and immediately executes the resulting binary, including automatic mock agent initialization.

### Where is the mock agent implementation located?

The mock agent source resides at [`crates/openlogi-agent/src/bin/mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/bin/mock_agent.rs). This binary implements the agent protocol with scripted inventory responses, designed specifically for development and integration testing without requiring production logistics infrastructure.