# How the Magnitude Desktop Application Locates Its Bundled Daemon Binaries in Production vs. Development

> Discover how the Magnitude desktop app finds its daemon binaries. Learn about production vs development binary location logic using resolveBinaryCommand and environment detection.

- Repository: [Magnitude/magnitude](https://github.com/magnitudedev/magnitude)
- Tags: internals
- Published: 2026-09-06

---

**The Magnitude desktop app resolves daemon binary locations through the `resolveBinaryCommand` function, which uses environment detection to choose between cached release binaries in `~/.magnitude/bin` for production or locally-built binaries via the `MAGNITUDE_CLI_BINARY` environment variable for development.**

The Magnitude desktop client relies on a native **ACN daemon** to run its AI agent runtime. Finding the correct executable requires different strategies in production (installed bundles) versus development (local builds). This article examines the binary resolution logic as implemented in the `magnitudedev/magnitude` repository, tracing how the application determines which daemon binary to launch.

## The Binary Resolution Architecture

Magnitude's binary location system centers on the `@magnitudedev/daemon-management` package. The `resolveBinaryCommand` function implements a **three-step decision tree** that prioritizes explicit configuration, then falls back to environment-appropriate defaults.

The resolver distinguishes contexts through two primary signals:

- **Production**: No explicit `binaryPath` and no `MAGNITUDE_CLI_BINARY` environment variable
- **Development**: `MAGNITUDE_CLI_BINARY` set by [`scripts/dev-server.ts`](https://github.com/magnitudedev/magnitude/blob/main/scripts/dev-server.ts) or explicit `binaryPath` provided

## Step-by-Step Resolution Logic

### Step 1: Explicit binaryPath Override

If the caller supplies `options.binaryPath`, the resolver uses this path **as-is** without downloading or cache checks.

```ts
// Any environment - explicit path takes precedence
const resolved = await Effect.runPromise(
  resolveBinaryCommand({ binaryPath: '/custom/path/to/acn' })
);
// resolved.command => ['/custom/path/to/acn', 'serve']

```

Developers leverage this in local workflows by setting the `MAGNITUDE_CLI_BINARY` environment variable, which the **pinned resolver layer** (`cliBinaryResolverPinnedLayer`) converts into an explicit `binaryPath`.

### Step 2: No Version Requested (Default Path Resolution)

When `options.version` is `undefined`, the resolver falls back to `defaultBinaryPath`.

| Environment | Behavior |
|-------------|----------|
| **Production** | Checks `~/.magnitude/bin/<executable>` (e.g., `~/.magnitude/bin/magnitude-acn`). If present, uses it; otherwise throws `BinaryNotFound` error. |
| **Development** | `MAGNITUDE_CLI_BINARY` environment variable triggers `cliBinaryResolverPinnedLayer`, which supplies the explicit path from local build output ([`packages/acn/src/binary.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/binary.ts)). |

The `defaultBinaryPath` is constructed in [`packages/daemon-management/src/binary.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/daemon-management/src/binary.ts):

```ts
// From packages/daemon-management/src/binary.ts
export const defaultBinaryPath = path.join(
  defaultDataDir,  // ~/.magnitude
  'bin',
  executableName   // magnitude-acn
);

```

### Step 3: Specific Version Requested

When `options.version` is provided, the resolver calls `ensureAcn`, which implements **cached release management**:

1. Checks `~/.magnitude/releases/acn/<version>/<host>/...` for existing binary
2. Validates version and revision match
3. If missing or mismatched, **downloads** from the official release server
4. Stores downloaded binary in the cache hierarchy

```ts
// Production with version pinning - may trigger download
const resolved = await Effect.runPromise(
  resolveBinaryCommand({ version: '1.2.3' })
);
// Checks cache at ~/.magnitude/releases/acn/1.2.3/...
// Downloads if not found or revision mismatch

```

Development workflows rarely exercise this path since `MAGNITUDE_CLI_BINARY` bypasses version-based resolution.

## Desktop Application Integration

The **Electron main process** ([`desktop/src/main.ts`](https://github.com/magnitudedev/magnitude/blob/main/desktop/src/main.ts)) orchestrates daemon startup:

```ts
// From desktop/src/main.ts
const resolved = yield* resolveBinaryCommand({
  // Production: no binaryPath set → uses defaultBinaryPath
  // Development: MAGNITUDE_CLI_BINARY env var → pinned layer supplies binaryPath
});
const command = resolved.command; // [binaryPath, "serve"]

```

The **development server** ([`desktop/scripts/dev-server.ts`](https://github.com/magnitudedev/magnitude/blob/main/desktop/scripts/dev-server.ts)) ensures local binaries are used:

```ts
// From desktop/scripts/dev-server.ts
process.env.MAGNITUDE_CLI_BINARY = path.resolve(
  __dirname,
  '../../packages/acn/src/binary.ts'
  // Or compiled output path
);

```

This injection triggers the pinned resolver layer, short-circuiting production search paths.

## Complete Environment Comparison

| Factor | Production | Development |
|--------|------------|-------------|
| **Primary source** | `~/.magnitude/bin/magnitude-acn` or cached release | Local build via `MAGNITUDE_CLI_BINARY` |
| **Binary provider** | `cliBinaryResolverLayer` (default) | `cliBinaryResolverPinnedLayer` (env-driven) |
| **Download behavior** | Downloads missing versions automatically | Never downloads; uses local build exclusively |
| **Cache location** | `~/.magnitude/releases/acn/<version>/` | N/A (bypassed) |
| **Configuration** | None required; bundled with installer | `MAGNITUDE_CLI_BINARY` env var required |

## Working Code Examples

### Production Binary Resolution

```ts
// Production - clean environment, no overrides
// Resolves to ~/.magnitude/bin/magnitude-acn
import { resolveBinaryCommand } from '@magnitudedev/daemon-management';
import { Effect } from 'effect';

const prodCmd = await Effect.runPromise(resolveBinaryCommand());
console.log(prodCmd.command);
// Output: ['/home/user/.magnitude/bin/magnitude-acn', 'serve']

```

### Development with Pinned Binary

```ts
// Development - use locally built daemon
import { resolveBinaryCommand } from '@magnitudedev/daemon-management';
import { cliBinaryResolverPinnedLayer } from '@magnitudedev/launcher';
import { Effect } from 'effect';

// Set or inherit from dev-server.ts
process.env.MAGNITUDE_CLI_BINARY = '/path/to/magnitude/packages/acn/dist/acn';

const devResolver = cliBinaryResolverPinnedLayer(process.env.MAGNITUDE_CLI_BINARY);
const devCmd = await Effect.runPromise(
  resolveBinaryCommand().pipe(Effect.provideLayer(devResolver))
);
console.log(devCmd.command);
// Output: ['/path/to/magnitude/packages/acn/dist/acn', 'serve']

```

## Key Source Files

| File | Responsibility |
|------|--------------|
| [`packages/daemon-management/src/binary.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/daemon-management/src/binary.ts) | Core resolution logic, `defaultBinaryPath`, `resolveBinaryCommand` implementation |
| [`packages/launcher/src/cli-binary-resolver.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/launcher/src/cli-binary-resolver.ts) | Layered resolver architecture; `cliBinaryResolverLayer` and `cliBinaryResolverPinnedLayer` |
| [`desktop/src/main.ts`](https://github.com/magnitudedev/magnitude/blob/main/desktop/src/main.ts) | Electron entry point; orchestrates daemon process creation |
| [`desktop/scripts/dev-server.ts`](https://github.com/magnitudedev/magnitude/blob/main/desktop/scripts/dev-server.ts) | Development environment setup; configures `MAGNITUDE_CLI_BINARY` |
| [`packages/release/scripts/build/acn.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/release/scripts/build/acn.ts) | Release build script; generates production binaries placed in expected cache locations |

## Summary

- **`resolveBinaryCommand`** in `@magnitudedev/daemon-management` provides unified binary location logic with environment-aware fallbacks.
- **Production** uses `~/.magnitude/bin/` or versioned release cache (`~/.magnitude/releases/acn/`), downloading missing binaries automatically.
- **Development** bypasses cache and download logic via `MAGNITUDE_CLI_BINARY`, pointing directly to locally-built executables.
- The **pinned resolver layer** (`cliBinaryResolverPinnedLayer`) enables instant developer iteration without interfering with production resolution paths.
- Layered Effect-TS architecture allows clean composition of resolution strategies through `Effect.provideLayer`.

## Frequently Asked Questions

### How does Magnitude prevent downloading binaries in development?

The [`desktop/scripts/dev-server.ts`](https://github.com/magnitudedev/magnitude/blob/main/desktop/scripts/dev-server.ts) sets `MAGNITUDE_CLI_BINARY` before launching the Electron app. The `cliBinaryResolverPinnedLayer` detects this environment variable and returns the specified local path directly, bypassing all cache checks and download logic in `resolveBinaryCommand`.

### What happens if the production daemon binary is deleted after installation?

If `~/.magnitude/bin/magnitude-acn` is missing and no explicit `binaryPath` or `version` is specified, `resolveBinaryCommand` throws a `BinaryNotFound` error. To recover, users must reinstall the application or trigger a version-specific resolution that downloads the binary via `ensureAcn`.

### Can I use a custom daemon binary in production?

Yes. Pass `binaryPath` explicitly to `resolveBinaryCommand`, or set an environment variable that your launcher code converts to the `binaryPath` option. The resolver treats explicit paths identically in all environments—it uses them without modification or validation against release caches.

### Where does Magnitude cache downloaded daemon versions?

Version-specific binaries are stored at `~/.magnitude/releases/acn/<version>/<host-platform>/<arch>/<revision>/magnitude-acn`. The `ensureAcn` function manages this hierarchy, validating both version strings and revision hashes before returning cached paths.