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

> Learn how to opt out of the automatic agent start in OpenLogi development runs by setting OPENLOGI_DEV_AGENT=0. Skip agent build, embed, and launch easily.

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

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/macos/dev_bundle.rs), the logic is straightforward:

```rust
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**:

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

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

```

**Terminal 2** — run the GUI without automatic agent start:

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

```

The mock agent source file at [`crates/openlogi-agent/src/bin/mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/bin/mock_agent.rs) even includes this reminder in its documentation comments:

```rust
//! 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`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) | Primary documentation for the development workflow and agent opt-out |
| [`xtask/src/commands/macos/dev_bundle.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/macos/dev_bundle.rs) | Implementation of the conditional check |
| [`crates/openlogi-agent/src/bin/mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/bin/mock_agent.rs) | Mock agent with usage comment |
| [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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.