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

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:

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:

cargo run -p openlogi-desktop

This command, documented in 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, 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:

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 line 65 according to the source.

Enable Component Gallery: OPENLOGI_COMPONENT_GALLERY

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

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

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

This executes the binary defined in 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:

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

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.

---

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	Desktop entry point; reads OPENLOGI_DEV_AGENT and OPENLOGI_COMPONENT_GALLERY environment variables
crates/openlogi-agent/src/bin/mock_agent.rs	Standalone mock agent binary for development IPC testing
docs/DEVELOPMENT.md	Consolidated development instructions and environment variable reference
AGENTS.md	High-level architecture with the "Dev-run" workflow specification
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 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 and 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. 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. This binary implements the agent protocol with scripted inventory responses, designed specifically for development and integration testing without requiring production logistics infrastructure.

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