# How the JIT ACN Spawning Model Works with the AcnInstanceManager in Magnitude

> Learn how the JIT ACN spawning model in Magnitude leverages AcnInstanceManager to lazily initialize ACN daemons on-demand for efficient process management. Understand the ensure() invocation for ready instances.

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

---

**The JIT ACN spawning model lazily initializes ACN daemon instances on-demand through the `AcnInstanceManager`, which orchestrates local process spawning or remote proxying to return a ready instance only when `ensure()` is invoked.**

The Magnitude SDK implements a sophisticated just-in-time provisioning system for AI Compute Nodes (ACN) that eliminates resource waste by deferring daemon creation until explicitly requested. This article examines how the **JIT ACN spawning model** leverages the `AcnInstanceManager` service interface to handle lifecycle orchestration, readiness monitoring, and graceful shutdown according to the source implementation in `magnitudedev/magnitude`.

## Core Architecture Components

### The AcnInstanceManager Interface

At the heart of the system lies the `AcnInstanceManager` service interface defined in [`packages/sdk/src/acn-jit/acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/acn-instance-manager.ts) (lines 30-38). This contract exposes two critical operations:

- **`ensure(request)`** – Returns a `Stream<AcnEnsureEvent, AcnEnsuranceError>` that lazily initializes an ACN instance
- **`stop`** – Gracefully terminates the managed daemon through the `AcnDaemonShutdownSupervisor`

The interface abstracts away whether the instance runs locally or remotely, allowing consumers to interact with both deployment models identically.

### Just-In-Time Spawning Mechanics

Unlike traditional long-running services, the **JIT spawning** approach defers daemon creation until the exact moment a client requires compute resources. When `ensure()` is called in [`packages/sdk/src/acn-jit/local-acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/local-acn-instance-manager.ts) (lines 91-101), the manager creates an asynchronous stream that triggers the **AcnEnsuranceCoordinator** only after subscription occurs.

This lazy evaluation pattern ensures that ACN processes never consume system resources during idle periods, making the architecture ideal for development environments and episodic workloads.

### Lifecycle Orchestration

The `AcnEnsuranceCoordinator` (implemented in [`acn-ensurance-coordinator.ts`](https://github.com/magnitudedev/magnitude/blob/main/acn-ensurance-coordinator.ts)) manages the complete instance lifecycle through three phases:

1. **Owner Observation** – Checks `makeAcnOwnerObserver` for existing registered instances to prevent duplicate spawning
2. **Daemon Launch** – Uses `makeAcnCandidateLaunchSupervisor` and `makeAcnDaemonLaunchCommandResolver` to spawn the binary via `ChildProcessSpawner`
3. **Readiness Monitoring** – Watches the daemon's stdout for `AcnReadyInstanceSchema` validation before emitting the ready state

## Execution Flow: From Request to Ready Instance

### Step 1: Consumer Request Initiation

A client component—whether CLI, web application, or desktop app—invokes `AcnInstanceManager.ensure({ target })` with an encoded target specification (typically including model parameters like `{ model: "gpt-4" }`).

### Step 2: Stream Construction and Coordination

The local manager constructs an `ensureEffect` that instantiates the `AcnEnsuranceCoordinator` with the target configuration, an `emit` callback for progress events, and supervisory helpers. This effect runs inside the coordinator's `run` method (lines 73-89 in [`local-acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/local-acn-instance-manager.ts)), returning a cold stream that remains inactive until consumed.

### Step 3: Conditional Launch or Reuse

Upon stream subscription, the coordinator first queries existing owners through the observer pattern. If an active ACN instance exists for the target, the coordinator immediately forwards the ready instance. Otherwise, it proceeds to binary resolution and process spawning.

### Step 4: Process Spawning and Validation

The `makeAcnCandidateLaunchSupervisor` resolves the executable path (customizable via `binaryPath` options) and spawns the ACN daemon. The launched process streams lifecycle observations until emitting a structured `Ready` event conforming to `AcnReadyInstanceSchema`.

### Step 5: Instance Delivery

Once validation succeeds, the stream emits a single `{ _tag: "Ready", instance }` event containing the URL and metadata, then terminates. Consumers typically use `runAcnEnsure()` from [`acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/acn-instance-manager.ts) to convert this stream into a concrete `ReadyInstance` promise.

### Remote Proxy Variant

When initializing `makeRemoteAcnInstanceManager` with a proxy URL, the flow diverges at step 3. Instead of local spawning, the manager sends an HTTP POST to `/acn/ensure` with the serialized request. The response parses through `RemoteAcnEnsureMessageSchema`, returning a proxied instance with adjusted routing URLs (lines 58-64 in [`packages/sdk/src/acn-jit/remote-acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/remote-acn-instance-manager.ts)).

## Implementation Examples

### Creating a Local JIT Manager

```typescript
import { makeLocalAcnInstanceManager } from "@magnitudedev/sdk";
import { Effect } from "effect";

const managerEffect = makeLocalAcnInstanceManager({
  binaryPath: "/usr/local/bin/acn",
  dataDir: "/tmp/acn-data",
});

const manager = await Effect.runPromise(managerEffect);

```

This creates a lazily-initialized manager that will spawn the ACN binary only upon the first `ensure()` call.

### Ensuring an Instance Availability

```typescript
import { AcnTargetSchema } from "@magnitudedev/acn-protocol";
import { runAcnEnsure } from "@magnitudedev/sdk";
import { Effect } from "effect";

const request = {
  target: AcnTargetSchema.encode({ model: "gpt-4" })
};

const ensureStream = manager.ensure(request);
const readyInstance = await Effect.runPromise(runAcnEnsure(ensureStream));

console.log("ACN ready at", readyInstance.url);

```

The `runAcnEnsure` helper consumes the event stream, resolving only when the coordinator confirms daemon readiness or rejecting with `AcnEnsuranceError` on failure.

### Configuring Remote Proxy Access

```typescript
import { makeRemoteAcnInstanceManager } from "@magnitudedev/sdk";
import { Effect } from "effect";

const remoteManager = await Effect.runPromise(
  makeRemoteAcnInstanceManager("https://acn-proxy.example.com")
);

const readyInstance = await Effect.runPromise(
  runAcnEnsure(remoteManager.ensure(request))
);

```

Remote managers bypass local spawning entirely, delegating instance lifecycle management to the HTTP proxy while maintaining the identical `AcnInstanceManager` interface.

### Graceful Shutdown

```typescript
await Effect.runPromise(manager.stop);

```

Invoking `stop` triggers the `AcnDaemonShutdownSupervisor`, ensuring clean termination of the underlying process and resource cleanup.

## Key Source Files

- **[`packages/sdk/src/acn-jit/acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/acn-instance-manager.ts)** – Defines the `AcnInstanceManager` interface and the `runAcnEnsure` stream consumer
- **[`packages/sdk/src/acn-jit/local-acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/local-acn-instance-manager.ts)** – Implements JIT local spawning, coordination logic, and shutdown sequences (lines 73-101)
- **[`packages/sdk/src/acn-jit/remote-acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/remote-acn-instance-manager.ts)** – HTTP proxy implementation for remote instance management (lines 30-70)
- **[`packages/sdk/src/acn-jit/acn-ensurance-coordinator.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/acn-ensurance-coordinator.ts)** – Core orchestration logic for owner observation, launching, and readiness monitoring
- **[`packages/sdk/src/acn-jit/acn-daemon-launch-command-resolver.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/acn-daemon-launch-command-resolver.ts)** – Command-line resolution and binary path validation
- **[`packages/sdk/src/acn-jit/acn-daemon-shutdown-supervisor.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/acn-daemon-shutdown-supervisor.ts)** – Graceful termination logic for running daemons

## Summary

- The **JIT ACN spawning model** defers daemon initialization until `AcnInstanceManager.ensure()` is explicitly called, preventing resource waste
- The `AcnEnsuranceCoordinator` handles the complete lifecycle: checking existing owners, launching binaries via `ChildProcessSpawner`, and validating readiness through `AcnReadyInstanceSchema`
- Both local and remote deployment models implement the same `AcnInstanceManager` interface, allowing seamless switching between `makeLocalAcnInstanceManager` and `makeRemoteAcnInstanceManager`
- Streams of `AcnEnsureEvent` provide granular observability into the spawning process, consumed via `runAcnEnsure` for promise-based workflows
- Shutdown operations traverse the `AcnDaemonShutdownSupervisor` to ensure clean process termination

## Frequently Asked Questions

### How does the JIT model prevent multiple ACN instances for the same target?

The `AcnEnsuranceCoordinator` consults `makeAcnOwnerObserver` before launching, checking for existing registered instances. If an active owner exists for the requested target, the coordinator reuses that instance rather than spawning a duplicate daemon, ensuring singleton-per-target semantics.

### What happens if the ACN daemon fails to reach ready state?

The stream returned by `ensure()` emits `AcnEnsuranceError` events describing the failure mode (binary not found, port conflict, or timeout). The `runAcnEnsure` helper propagates these as rejected promises, allowing callers to implement retry logic or fallback to remote managers.

### Can I customize the ACN binary location for local spawning?

Yes. Pass the `binaryPath` option to `makeLocalAcnInstanceManager` to specify an alternative executable location. The `makeAcnDaemonLaunchCommandResolver` uses this path when constructing the spawn arguments, defaulting to system PATH resolution when unspecified.

### Is the remote manager suitable for production workloads?

The remote implementation in [`remote-acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/remote-acn-instance-manager.ts) forwards requests to an HTTP proxy that manages pooled instances. While it maintains the same interface as local managers, production suitability depends on the proxy's scaling characteristics and the network latency between client and proxy endpoints.