# How Magnitude Manages the ACN Lifecycle: Launch, Health Checks, and Shutdown Timings Explained

> Discover how Magnitude manages the ACN lifecycle: explore launch, health checks, and shutdown timings. Learn about coordinated phases and configurable timeouts for efficient agent orchestration.

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

---

**Magnitude orchestrates the Agent Compute Node (ACN) through four coordinated phases—launch, readiness verification, active running, and graceful shutdown—each governed by configurable timeouts and dedicated supervisor components.**

The **ACN lifecycle** is central to Magnitude's architecture for just-in-time daemon management. Rather than running a persistent background service, Magnitude spawns short-lived ACN processes on demand, ensures they reach a healthy state before use, monitors their activity, and reclaims them when idle. This article examines the exact mechanisms, source file implementations, and timing parameters that control this orchestration.

## The Four Phases of ACN Lifecycle Management

According to the `magnitudedev/magnitude` source code, the ACN lifecycle flows through distinct phases managed by specialized components in `packages/daemon-management/src/acn-jit/`.

### Launch Phase: Deciding When to Spawn

The **AcquisitionEnsuranceCoordinator** ([`acn-ensurance-coordinator.ts`](https://github.com/magnitudedev/magnitude/blob/main/acn-ensurance-coordinator.ts)) determines when a new ACN instance is required. It evaluates criteria such as:

- No existing ACN currently registered
- Previous instance has terminated or become unreachable
- A pending user request requires compute resources

When conditions are met, the coordinator delegates to the **AcquisitionCandidateLaunchSupervisor** to begin the actual process spawn.

### Readiness Phase: Health Check and Registration

The **AcquisitionCandidateLaunchSupervisor** ([`acn-candidate-launch-supervisor.ts`](https://github.com/magnitudedev/magnitude/blob/main/acn-candidate-launch-supervisor.ts)) executes the launch sequence:

1. Resolves the binary path and arguments via `AcnDaemonLaunchCommandResolver`
2. Spawns the process using Node's `child_process`
3. Polls the HTTP `/health` endpoint until it returns **healthy**
4. Registers the `x-magnitude-acn-id` in shared state for SDK routing

| Timing Parameter | Default | Purpose |
|------------------|---------|---------|
| `ACN_LAUNCH_TIMEOUT_MS` | `5000` | Maximum wait for health endpoint response |
| `ACN_MAX_RETRIES` | `3` | Launch attempts before abandonment |

If health checks fail within the timeout window, the supervisor retries up to the configured maximum. All retries exhausted results in a rejected promise propagated to the caller.

### Running Phase: Activity Monitoring

Once healthy, the **AcquisitionOwnerObserver** ([`acn-owner-observer.ts`](https://github.com/magnitudedev/magnitude/blob/main/acn-owner-observer.ts)) assumes responsibility:

- Maintains periodic heartbeat checks via `/ping` endpoint
- Tracks active session usage count
- Detects shutdown signals (OS `SIGTERM`, manual stop requests)
- Emits idle-timeout events when no sessions remain

| Timing Parameter | Default | Purpose |
|------------------|---------|---------|
| `ACN_IDLE_TIMEOUT_MS` | `30000` | Duration of inactivity before shutdown trigger |

The observer implements a reference-counting mechanism: each active RPC session increments the count, and when all sessions close, the idle timer begins.

### Shutdown Phase: Graceful Termination

The **AcquisitionDaemonShutdownSupervisor** ([`acn-daemon-shutdown-supervisor.ts`](https://github.com/magnitudedev/magnitude/blob/main/acn-daemon-shutdown-supervisor.ts)) handles termination:

1. Sends `SIGTERM` to the ACN process
2. Waits for graceful exit or timeout
3. Escalates to `SIGKILL` if necessary
4. Clears instance ID from shared state

| Timing Parameter | Default | Purpose |
|------------------|---------|---------|
| `ACN_SHUTDOWN_GRACE_MS` | `10000` | Grace period after `SIGTERM` |
| `ACN_SHUTDOWN_FORCE_MS` | `2000` | Additional wait before `SIGKILL` |

## Central Orchestration: AcquisitionInstanceManager

The **AcquisitionInstanceManager** ([`acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/acn-instance-manager.ts)) binds these phases into a unified interface. Its public API exposes two primary methods:

- `acquire()`: Returns a promise that resolves when the ACN is healthy and ready for RPC calls
- `release()`: Signals that the ACN can be shut down, either immediately or after idle timeout

The manager internally coordinates:
- Launch requests to the **AcquisitionEnsuranceCoordinator**
- Readiness promise resolution from **AcquisitionCandidateLaunchSupervisor**
- Lifetime observation via **AcquisitionOwnerObserver**
- Shutdown delegation to **AcquisitionDaemonShutdownSupervisor**

## Practical Usage Examples

### Starting and Using an ACN Instance

```typescript
// packages/sdk-common/src/connection/acn-bootstrap.ts
import { makeAcnInstanceManager } from "@magnitudedev/daemon-management";

const acnManager = makeAcnInstanceManager({
  launchTimeoutMs: 5_000,
  idleTimeoutMs: 30_000,
});

async function initializeWork() {
  // Triggers launch if needed, waits for health check
  const acnId = await acnManager.acquire();
  console.log(`ACN ready with ID: ${acnId}`);
  
  // SDK automatically routes RPC calls to this instance
  const projects = await rpc.projectManager.list({});
  return projects;
}

```

### Configuring Environment Variables

```bash

# .env or process environment

ACN_LAUNCH_TIMEOUT_MS=10000      # Slower machines need more time

ACN_IDLE_TIMEOUT_MS=60000        # Keep alive longer for burst workloads

ACN_SHUTDOWN_GRACE_MS=15000      # Allow more cleanup time

ACN_SHUTDOWN_FORCE_MS=5000       # Delay before forced kill

```

### Manual Shutdown Trigger

```typescript
// Explicit release, bypassing idle timeout
await acnManager.release({ immediate: true });

// Or let idle timeout handle it naturally
await acnManager.release();  // Returns immediately, shutdown follows idle period

```

## Key Source Files and Responsibilities

| File Path | Component | Lifecycle Responsibility |
|-----------|-----------|--------------------------|
| [`packages/daemon-management/src/acn-jit/acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/daemon-management/src/acn-jit/acn-instance-manager.ts) | `AcquisitionInstanceManager` | Central API coordinating all phases |
| [`packages/daemon-management/src/acn-jit/acn-ensurance-coordinator.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/daemon-management/src/acn-jit/acn-ensurance-coordinator.ts) | `AcquisitionEnsuranceCoordinator` | Launch decision logic |
| [`packages/daemon-management/src/acn-jit/acn-candidate-launch-supervisor.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/daemon-management/src/acn-jit/acn-candidate-launch-supervisor.ts) | `AcquisitionCandidateLaunchSupervisor` | Process spawn and health verification |
| [`packages/daemon-management/src/acn-jit/acn-owner-observer.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/daemon-management/src/acn-jit/acn-owner-observer.ts) | `AcquisitionOwnerObserver` | Runtime monitoring and idle detection |
| [`packages/daemon-management/src/acn-jit/acn-daemon-shutdown-supervisor.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/daemon-management/src/acn-jit/acn-daemon-shutdown-supervisor.ts) | `AcquisitionDaemonShutdownSupervisor` | Graceful and forced termination |
| [`packages/daemon-management/src/acn-jit/acn-daemon-launch-command-resolver.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/daemon-management/src/acn-jit/acn-daemon-launch-command-resolver.ts) | `AcnDaemonLaunchCommandResolver` | Binary path and argument resolution |
| [`packages/acn-protocol/src/boundary/acn.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn-protocol/src/boundary/acn.ts) | RPC boundary definitions | Contract between SDK and running ACN |

## Summary

- **Four phases** govern the ACN lifecycle: launch decision, readiness verification, active operation, and shutdown reclamation
- **Five configurable timings** control behavior: `ACN_LAUNCH_TIMEOUT_MS`, `ACN_MAX_RETRIES`, `ACN_IDLE_TIMEOUT_MS`, `ACN_SHUTDOWN_GRACE_MS`, and `ACN_SHUTDOWN_FORCE_MS`
- **AcquisitionInstanceManager** in [`acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/acn-instance-manager.ts) serves as the primary interface for SDK consumers
- **Graceful degradation** is built in: retries on launch failure, escalating signals on shutdown, and automatic cleanup of orphaned state

## Frequently Asked Questions

### What triggers the ACN to launch?

The **AcquisitionEnsuranceCoordinator** evaluates need based on request demand and existing instance state. No persistent daemon runs; each compute session begins with an explicit `acquire()` call that may trigger fresh process spawn.

### How does Magnitude ensure an ACN is ready before use?

The **AcquisitionCandidateLaunchSupervisor** polls the `/health` endpoint until success or timeout. Only after this verification does `acquire()` resolve, guaranteeing that subsequent RPC calls reach a functional service.

### Can I adjust how long the ACN stays running?

Yes. Set `ACN_IDLE_TIMEOUT_MS` to control inactivity duration before automatic shutdown. For persistent workloads, increase this value; for resource-constrained environments, decrease it to reclaim memory faster.

### What happens if the ACN process hangs during shutdown?

The **AcquisitionDaemonShutdownSupervisor** implements a two-stage termination: `SIGTERM` followed by `ACN_SHUTDOWN_GRACE_MS` wait, then `SIGKILL` if still running. This prevents zombie processes while allowing cleanup routines to execute.