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

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

// 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).

The defaultBinaryPath is constructed in packages/daemon-management/src/binary.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

// 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) orchestrates daemon startup:

// 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) ensures local binaries are used:

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

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

// 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	Core resolution logic, defaultBinaryPath, resolveBinaryCommand implementation
packages/launcher/src/cli-binary-resolver.ts	Layered resolver architecture; cliBinaryResolverLayer and cliBinaryResolverPinnedLayer
desktop/src/main.ts	Electron entry point; orchestrates daemon process creation
desktop/scripts/dev-server.ts	Development environment setup; configures MAGNITUDE_CLI_BINARY
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 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.

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