How to Opt Out of the Automatic Agent Start During OpenLogi Development Runs

Set OPENLOGI_DEV_AGENT=0 before running cargo run -p openlogi-desktop to skip the automatic agent build, embed, and launch.

OpenLogi's development workflow is designed for convenience: each time you run the desktop GUI, a custom runner automatically builds and starts the background agent along with its overlay helper. However, there are situations where you want to run the GUI against a manually started agent, a mock implementation, or simply avoid the overhead of agent rebuilds. This guide explains how to opt out of the automatic agent start using the OPENLOGI_DEV_AGENT environment flag, as implemented in the AprilNEA/OpenLogi repository.

How the Automatic Agent Start Works

The automatic behavior is controlled by the custom runner script .cargo/run-macos.sh, which invokes the xtask macos dev-bundle command. Inside this command, the code explicitly checks the OPENLOGI_DEV_AGENT environment variable before deciding whether to build and embed the agent.

In xtask/src/commands/macos/dev_bundle.rs, the logic is straightforward:

if std::env::var("OPENLOGI_DEV_AGENT").as_deref() != Ok("0") {
    // …build and embed the agent and overlay
}

When the variable is unset or set to any value other than "0", the runner:

• Builds the agent binary from source
• Embeds it into the development bundle
• Stops any previously running dev agent
• Launches a fresh agent process

This guarantees the GUI always connects to a fresh IPC socket with a compatible agent version.

Using OPENLOGI_DEV_AGENT=0 to Skip Automatic Startup

Setting OPENLOGI_DEV_AGENT=0 flips the conditional to false, causing the runner to skip the entire agent build and launch sequence:

OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

With this flag:

• No dev-agent process starts automatically
• The desktop app attempts to connect to an existing agent
• If no agent is running, the GUI fails gracefully rather than crashing
• You have full control over which agent process the GUI uses

This is particularly useful when:

• You want to run multiple GUI instances against a single long-running agent
• You're developing agent features and need to restart the GUI without agent rebuilds
• You're testing with the mock agent or a custom agent implementation

Practical Example: Running with a Mock Agent

The repository includes a mock agent specifically for this workflow. Run it in one terminal, then launch the GUI in another:

Terminal 1 — start the mock agent:

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

Terminal 2 — run the GUI without automatic agent start:

OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

The mock agent source file at crates/openlogi-agent/src/bin/mock_agent.rs even includes this reminder in its documentation comments:

//! OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop   # in a second terminal

Where This Behavior Is Documented

The OPENLOGI_DEV_AGENT flag appears in multiple locations across the codebase:

File	Purpose
docs/DEVELOPMENT.md	Primary documentation for the development workflow and agent opt-out
xtask/src/commands/macos/dev_bundle.rs	Implementation of the conditional check
crates/openlogi-agent/src/bin/mock_agent.rs	Mock agent with usage comment
AGENTS.md	Project-wide summary of agent behavior and configuration

Summary

• Default behavior: cargo run -p openlogi-desktop automatically builds, embeds, and starts the agent
• Opt-out command: OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop
• Key implementation: xtask/src/commands/macos/dev_bundle.rs checks std::env::var("OPENLOGI_DEV_AGENT").as_deref() != Ok("0")
• Use case: Manual agent control, mock testing, faster GUI iteration cycles

Frequently Asked Questions

What happens if I run the GUI with OPENLOGI_DEV_AGENT=0 but no agent is running?

The desktop app attempts to connect to an existing agent socket and fails gracefully if none is found. You'll see connection errors in the logs, but the GUI won't crash. Start a manual agent (or the mock) and restart the GUI to establish connectivity.

Can I use OPENLOGI_DEV_AGENT=0 on platforms other than macOS?

The .cargo/run-macos.sh runner is macOS-specific, but the OPENLOGI_DEV_AGENT flag is implemented in the cross-platform xtask command structure. Check your platform's runner script or xtask implementation for equivalent behavior on Linux or Windows builds.

Why does the runner stop previously running dev agents automatically?

This prevents socket conflicts and version mismatches. When the automatic agent start is enabled, the runner ensures a clean state by terminating stale dev agents before launching fresh ones. With OPENLOGI_DEV_AGENT=0, this cleanup is skipped—you're responsible for agent lifecycle management.

Is there a way to make OPENLOGI_DEV_AGENT=0 the default for my environment?

Add export OPENLOGI_DEV_AGENT=0 to your shell profile, or create a shell alias: alias openlogi-dev='OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop'. Remove or override when you need the automatic behavior.

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