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

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 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 and handles session-specific errors through session-errors.ts
• Debugging support – Provides the session inspector (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, 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. 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
Agent	Start/stop agents, query capabilities	boundary/acn.ts
Connection	Manage client connection lifecycle	server.ts
Display	Stream UI updates from agent to client	display-view-stream.ts
Shell	Provide REPL-like interactive shell	Shell service handlers
Onboarding	Initialize new agents and projects	onboarding/service.ts
ProjectFiles/Files/Changes	Read/write files, track modifications	file-system-manager.ts
Models	Expose model catalog, handle ranking	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.

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 abstracts the underlying file system, exposing safe read/write APIs to agents with proper sandboxing. Meanwhile, project-manager.ts tracks project metadata, resolves project roots, and coordinates ownership monitoring through ownership-monitor.ts.

Display and UI Streaming

Real-time UI updates flow through display-view-stream.ts and 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 routes model requests to local or remote providers. It coordinates:

• Hardware selection via local-inference-hardware.ts
• Ranking policies through local-model-ranking-policy.ts
• Provider credential management in provider-credentials.ts

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

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 and exposes them through the HTTP/gRPC server initialized in packages/acn/src/server.ts.

Making RPC Calls from the SDK

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

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:

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 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 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 service. Local inference uses hardware selection logic in local-inference-hardware.ts and ranking policies in local-model-ranking-policy.ts. Remote inference routes to configured providers with credentials stored in provider-credentials.ts.

How does the ACN handle file system security for agents?

File access is mediated through 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 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. This TypeScript file declares the MagnitudeRpcs interface grouping all available methods. The concrete implementation is wired in packages/acn/src/boundary/acn.ts and served through packages/acn/src/server.ts.

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