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

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 (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 (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) 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), 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 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).

Implementation Examples

Creating a Local JIT Manager

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

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

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

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 – Defines the AcnInstanceManager interface and the runAcnEnsure stream consumer
• 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 – HTTP proxy implementation for remote instance management (lines 30-70)
• 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 – Command-line resolution and binary path validation
• 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 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.

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