# What Does the ACN (Agent Communication Node) Do in Magnitude? Core Responsibilities Explained

> Understand the core responsibilities of the ACN Agent Communication Node in Magnitude. Learn how it hosts agent runtimes, handles RPCs, and provides essential system services for efficient operation.

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

---

**TL;DR:** The **ACN (Agent Communication Node)** is the core daemon in Magnitude that hosts agent runtimes, implements the ACN protocol RPCs for client-side SDKs, and provides system services including file operations, model inference routing, and real-time UI streaming.

The **Agent Communication Node (ACN)** is the backbone of the Magnitude platform. According to the [magnitudedev/magnitude](https://github.com/magnitudedev/magnitude) source code, this daemon isolates complex, stateful backend work from the lightweight client SDK. Understanding ACN responsibilities helps developers debug agent behavior, extend platform capabilities, and architect integrations.

## Runtime Hosting: The Agent Lifecycle Engine

The ACN's primary responsibility is **starting and supervising agent processes**. It maintains the complete lifecycle of sessions, ensuring agents have a stable environment to execute code, run tools, and perform inference.

Key runtime functions include:

- **Process ownership** – The ACN daemon owns all agent processes, preventing orphaned child processes when clients disconnect
- **Session state management** – Tracks runtime state via [`session-runtime-state.ts`](https://github.com/magnitudedev/magnitude/blob/main/session-runtime-state.ts) and handles session-specific errors through [`session-errors.ts`](https://github.com/magnitudedev/magnitude/blob/main/session-errors.ts)
- **Debugging support** – Provides the **session inspector** ([`session-inspector.ts`](https://github.com/magnitudedev/magnitude/blob/main/session-inspector.ts)) for examining live sessions and diagnosing runtime issues

The entry point for this functionality is found in [`packages/acn/src/boundary/acn.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/boundary/acn.ts), where the daemon initializes and begins listening for connections.

## Protocol Implementation: The RPC Boundary

The ACN implements the **ACN protocol RPCs** defined in [`packages/acn-protocol/src/boundary/acn.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn-protocol/src/boundary/acn.ts). This RPC boundary is the single integration point between client SDKs and the platform backend.

The RPC group `MagnitudeRpcs` covers these functional areas:

| RPC Group | Purpose | Handler Location |
|-----------|---------|------------------|
| **Projects** | Create, delete, list projects | [`project-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/project-manager.ts) |
| **Agent** | Start/stop agents, query capabilities | [`boundary/acn.ts`](https://github.com/magnitudedev/magnitude/blob/main/boundary/acn.ts) |
| **Connection** | Manage client connection lifecycle | [`server.ts`](https://github.com/magnitudedev/magnitude/blob/main/server.ts) |
| **Display** | Stream UI updates from agent to client | [`display-view-stream.ts`](https://github.com/magnitudedev/magnitude/blob/main/display-view-stream.ts) |
| **Shell** | Provide REPL-like interactive shell | Shell service handlers |
| **Onboarding** | Initialize new agents and projects | [`onboarding/service.ts`](https://github.com/magnitudedev/magnitude/blob/main/onboarding/service.ts) |
| **ProjectFiles/Files/Changes** | Read/write files, track modifications | [`file-system-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/file-system-manager.ts) |
| **Models** | Expose model catalog, handle ranking | [`model-catalog.ts`](https://github.com/magnitudedev/magnitude/blob/main/model-catalog.ts) |
| **Git** | Inspect repository state for agents | Git inspection handlers |
| **Sessions** | Pause, resume, cancel sessions | Session management layer |
| **Configuration** | Read/write platform configuration | Configuration store |

All SDK calls route through this boundary. For example, when calling `sdk.projects.list()`, the SDK serializes the request, transmits it via the ACN protocol, and the ACN executes the corresponding handler in [`packages/acn/src/project-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/project-manager.ts).

## System Services: Concrete Capabilities

Beyond protocol translation, the ACN provides **concrete service implementations** that agents depend on.

### File Operations and Project Management

The [`file-system-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/file-system-manager.ts) abstracts the underlying file system, exposing **safe read/write APIs** to agents with proper sandboxing. Meanwhile, [`project-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/project-manager.ts) tracks project metadata, resolves project roots, and coordinates ownership monitoring through [`ownership-monitor.ts`](https://github.com/magnitudedev/magnitude/blob/main/ownership-monitor.ts).

### Display and UI Streaming

Real-time UI updates flow through [`display-view-stream.ts`](https://github.com/magnitudedev/magnitude/blob/main/display-view-stream.ts) and [`display-view-streams.ts`](https://github.com/magnitudedev/magnitude/blob/main/display-view-streams.ts). These implement **display view streams** that push tool outputs, logs, and interactive widgets from the daemon to connected clients. This enables live agent observation without polling.

### Inference Gateway and Model Catalog

The [`inference-gateway.ts`](https://github.com/magnitudedev/magnitude/blob/main/inference-gateway.ts) routes model requests to **local or remote providers**. It coordinates:

- Hardware selection via [`local-inference-hardware.ts`](https://github.com/magnitudedev/magnitude/blob/main/local-inference-hardware.ts)
- Ranking policies through [`local-model-ranking-policy.ts`](https://github.com/magnitudedev/magnitude/blob/main/local-model-ranking-policy.ts)
- Provider credential management in [`provider-credentials.ts`](https://github.com/magnitudedev/magnitude/blob/main/provider-credentials.ts)

The [`model-catalog.ts`](https://github.com/magnitudedev/magnitude/blob/main/model-catalog.ts) enumerates available models and presents a unified view to SDK consumers, abstracting whether inference runs on-device or via API.

### Onboarding and Environment Setup

Fresh agent environments are prepared by [`onboarding/service.ts`](https://github.com/magnitudedev/magnitude/blob/main/onboarding/service.ts). This installs required providers, configures model sources, and ensures the target directory structure exists before an agent begins execution.

### Observability and Tracing

The ACN integrates with **Motel**, Magnitude's built-in OpenTelemetry collector. All RPC calls and internal operations emit traces and logs, accessible via `/api/traces` and `/api/logs` endpoints for deep debugging.

## Starting the ACN Daemon

Typically invoked through the Magnitude CLI, the daemon can also be started programmatically:

```typescript
import { startAcnDaemon } from '@magnitudedev/acn';

await startAcnDaemon({
  projectRoot: '/home/user/my-project',
  logLevel: 'info',
});

```

Once started, the daemon reads RPC definitions from [`packages/acn-protocol/src/boundary/acn.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn-protocol/src/boundary/acn.ts) and exposes them through the HTTP/gRPC server initialized in [`packages/acn/src/server.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/server.ts).

## Making RPC Calls from the SDK

Client code consumes ACN services through the SDK's typed interface:

```typescript
import { sdk } from '@magnitudedev/sdk';

const projects = await sdk.projects.list();
console.log('Available projects:', projects);

```

## Subscribing to Display Streams

For real-time agent observation:

```typescript
import { sdk } from '@magnitudedev/sdk';

const view = await sdk.display.subscribe({ viewId: 'my-view' });

view.on('update', (payload) => {
  console.log('Display update:', payload);
});

```

Updates originate from [`display-view-stream.ts`](https://github.com/magnitudedev/magnitude/blob/main/display-view-stream.ts) inside the ACN and propagate to all connected subscribers.

## Summary

- **Runtime hosting** – The ACN daemon supervises agent processes and manages session lifecycles with full state tracking and debugging support
- **Protocol implementation** – A comprehensive RPC boundary (`MagnitudeRpcs`) exposes projects, files, models, Git state, sessions, configuration, and more to SDK clients
- **System services** – Concrete implementations for file operations, display streaming, inference routing, project management, and onboarding
- **Observability** – Built-in OpenTelemetry integration via Motel for tracing and logging all operations

## Frequently Asked Questions

### What is the relationship between the ACN and the Magnitude SDK?

The ACN is the **server-side daemon** that implements all backend functionality. The SDK is the **client-side library** that consumes ACN services through typed RPC calls. The ACN protocol defined in [`packages/acn-protocol/src/boundary/acn.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn-protocol/src/boundary/acn.ts) contractually separates these layers, allowing SDK updates without daemon changes and vice versa.

### Can the ACN run inference locally or only via remote APIs?

The ACN supports **both local and remote inference** through the [`inference-gateway.ts`](https://github.com/magnitudedev/magnitude/blob/main/inference-gateway.ts) service. Local inference uses hardware selection logic in [`local-inference-hardware.ts`](https://github.com/magnitudedev/magnitude/blob/main/local-inference-hardware.ts) and ranking policies in [`local-model-ranking-policy.ts`](https://github.com/magnitudedev/magnitude/blob/main/local-model-ranking-policy.ts). Remote inference routes to configured providers with credentials stored in [`provider-credentials.ts`](https://github.com/magnitudedev/magnitude/blob/main/provider-credentials.ts).

### How does the ACN handle file system security for agents?

File access is mediated through [`file-system-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/file-system-manager.ts), which provides **sandboxed APIs** rather than direct file system access. This abstraction layer enforces path restrictions, prevents directory traversal, and logs all operations for audit purposes. Project roots are validated via [`project-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/project-manager.ts) and monitored for ownership changes.

### Where can I find the complete list of ACN RPC methods?

The authoritative RPC definition lives in [`packages/acn-protocol/src/boundary/acn.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn-protocol/src/boundary/acn.ts). This TypeScript file declares the `MagnitudeRpcs` interface grouping all available methods. The concrete implementation is wired in [`packages/acn/src/boundary/acn.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/boundary/acn.ts) and served through [`packages/acn/src/server.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/server.ts).