A2M (Agent to Machine) is a local-first MCP bridge built with Rust and Go microservices and a native macOS desktop application. It lets supported AI clients interact with authorized terminal processes, files and developer workflows.
- Latest Release: A2M v1.3.2 Release Notes & Architecture Guide
- New to A2M? Follow the visual setup and ChatGPT connection guide — compact clickable screenshots walk through tunnel setup, device connection, and a successful A2M response.
+---------------------------------------+
| AI Client (Claude / Cursor / etc.) |
+-------------------+-------------------+
| JSON-RPC 2.0 (stdio)
v
+---------------------------------------+
| a2m-gateway / dc-gateway (Go) |
| - MCP JSON-RPC 2.0 Protocol Engine |
| - Self-Healing Sidecar Lifecycle |
| - Process & PTY Lifecycle Supervisor |
| - Memory-Safe Ring Buffer Pagination |
| - POSIX/Win32 Process Group Control |
+--------+---------------------+--------+
| |
Unix Domain Socket| (JSON-RPC IPC) | Local Process Invocation
v v
+---------------------------------------+ +---------------------------------------+
| a2m-fs / dc-fs-engine (Rust) | | a2m-docs / dc-doc-service (Go) |
| - High-Speed Filesystem Operations | | - Native Excel Reader & Range Editor |
| - Multi-threaded Regex Search Engine | | (qax-os/excelize v2.11) |
| - Surgical edit_block with | | - Native PDF Text & Metadata Parser |
| Levenshtein Fuzzy Match Fallback | | (zero Chromium/Puppeteer dependency|
| - Atomic Write & CRLF/LF Normalizer | +---------------------------------------+
| - Multi-Language AST Symbol Indexer |
| - Embedded SQLite Knowledge Graph |
| - Impact & Blast Radius Evaluator |
| - Persistent ADR Governance Engine |
+---------------------------------------+
Tested on macOS Apple Silicon arm64 (see docs/benchmarks/native-vs-original.md):
| Metric | Reference Node.js/Electron tool | A2M Native (Rust & Go) |
|---|---|---|
| Cold Startup Latency | 1,200 ms – 2,500 ms | 55 ms |
| Command Roundtrip Latency | 2,050 ms | 6 ms |
| Idle Memory Consumption | 85 MB – 140 MB | 10.11 MB |
| Desktop App Binary Size | > 150 MB (Electron runtime) | 111 KB (Native Cocoa Mach-O) |
| Standalone DMG Installer | > 200 MB | 11 MB (Self-contained) |
| Process Tree Termination | Flaky Node signals; zombie leaks | Native OS Process Groups (killpg) |
| Max Output Buffering | Crashes with V8 RangeError (>50MB string) |
Circular ring buffer with zero-copy eviction |
| External Telemetry / Quotas | Cloud relay, 10,000 call limit, Paywall | 100% Offline-First. Zero telemetry. Unlimited |
The native desktop application (A2M.app) provides a complete graphical interface:
- One-Click Connect / Disconnect: Connects the local machine to the AI assistant using OpenAI's official
tunnel-clientor private SSE transport. - Live Terminal Monitor: Displays real-time streaming output (
stdout/stderr) of everything the AI runs with search, auto-scroll, ANSI colors, and output export. - Interactive Control: Allows sending input (
stdin) to prompts or triggering immediate emergency process termination (Kill Process). - System Tray (Menu Bar): Quick-status indicator and controls in the macOS menu bar.
Install via DMG:
open dist/A2M-macos-arm64.dmgOr launch directly:
open apps/desktop/macos/A2M.app# Build all microservices
make build
# Run unit tests across Rust and Go test suites
make test
# Run full end-to-end integration test over stdio
make e2e{
"mcpServers": {
"a2m": {
"command": "/absolute/path/to/clever-hypatia/bin/a2m"
}
}
}{
"mcpServers": {
"a2m": {
"command": "/absolute/path/to/clever-hypatia/bin/a2m"
}
}
}A2M uses a2m and a2m-2 as the default tunnel-client profile names. If you already have a tunnel-client profile with another name, set A2M_TUNNEL_PROFILE_1 or A2M_TUNNEL_PROFILE_2 in your local, untracked environment file; do not rename or delete an active tunnel profile automatically. New local configuration and authorization data use the ~/.a2m/ directory. Verify your existing settings after upgrading.
| Tool | Service | Description |
|---|---|---|
start_process |
dc-gateway |
Execute command or launch long-running process with output streaming |
read_process_output |
dc-gateway |
Read process output buffer with offset, length, and tail pagination |
interact_with_process |
dc-gateway |
Write to process stdin and wait for prompt response |
kill_process |
dc-gateway |
Graceful SIGTERM process termination |
force_terminate |
dc-gateway |
Forceful SIGKILL process tree termination |
list_sessions |
dc-gateway |
List active and historical process execution sessions |
list_processes |
dc-gateway |
Host system process snapshot |
read_file |
dc-fs-engine |
Line-bounded paginated file reader |
read_multiple_files |
dc-fs-engine |
Batch file reader |
write_file |
dc-fs-engine |
Atomic file writer with rewrite and append modes |
edit_block |
dc-fs-engine |
Surgical string replacement with Levenshtein fuzzy match fallback |
create_directory |
dc-fs-engine |
Recursive directory creation |
list_directory |
dc-fs-engine |
Bounded directory traversal with metadata |
move_file |
dc-fs-engine |
Safe file move and rename |
get_file_info |
dc-fs-engine |
File metadata, permissions, and MIME type |
start_search |
dc-fs-engine |
Concurrent ripgrep-grade regex search for files or content |
get_more_search_results |
dc-fs-engine |
Cursor-based search session pagination |
stop_search |
dc-fs-engine |
Early cancellation of active search session |
list_searches |
dc-fs-engine |
Registry of active search sessions |
get_config |
dc-gateway |
Retrieve server configuration |
set_config_value |
dc-gateway |
Persist server configuration updates |
get_usage_stats |
dc-gateway |
Operational uptime and tool execution metrics |
get_recent_tool_calls |
dc-gateway |
Recent tool execution audit ring buffer |
excel_read_sheet |
dc-doc-service |
Read cell matrix or range from .xlsx workbook |
excel_list_sheets |
dc-doc-service |
List worksheet names in .xlsx workbook |
excel_edit_range |
dc-doc-service |
Modify cells or ranges in .xlsx worksheets |
docx_read |
a2m-docs |
Extract body text, headers, and footers from .docx files |
docx_edit |
a2m-docs |
Surgical find-and-replace in .docx body, headers, or footers |
pdf_extract_text |
a2m-docs |
Native text and metadata extraction from PDF files |
auth_status |
a2m-gateway |
Inspect active MCP authorization status, role, and capabilities |
auth_login |
a2m-gateway |
Authenticate session using security token (DC_AUTH_TOKEN) |
capabilities_list |
a2m-gateway |
Live inventory of installed agent skills, CLI bridges, and external MCP tools |
skills_find |
a2m-gateway |
Search and discover installed local Agent Skills |
skills_read |
a2m-gateway |
Read bounded, root-scoped instructions for an agent skill |
mcp_servers_list |
a2m-gateway |
List configured external Model Context Protocol providers |
index_codebase |
a2m-fs |
Index workspace or directory into the persistent AST knowledge graph |
get_architecture |
a2m-fs |
High-level project architecture, language breakdown, entrypoints, and core symbols |
query_symbols |
a2m-fs |
Search code symbols (functions, structs, classes, interfaces, enums) with sub-millisecond precision |
trace_call_path |
a2m-fs |
Trace call chains and execution paths between source and target symbols |
assess_impact |
a2m-fs |
Evaluate blast radius, callers, and regression risk before modifying code |
manage_adr |
a2m-fs |
Manage Architecture Decision Records (ADRs) to preserve design decisions and governance |
correlate_error |
a2m-gateway |
Correlate compiler errors or test failure stack traces with AST nodes and dependent callers |
A2M includes a 100% offline-first security gateway with constant-time token verification (crypto/subtle) and role-based capability gating:
- Environment Configuration:
DC_AUTH_TOKEN: Sets the expected pre-shared security token.DC_REQUIRE_AUTH=true: Enforces mandatory authentication for all MCP tool calls (whenfalse, machine access is granted automatically).A2M_ALLOWED_DIRECTORIES: Colon-separated list of allowed directories for filesystem and CLI boundaries.A2M_FS_BINARY: Explicit operator path override fora2m-fs/dc-fs-engine.A2M_DOC_BINARY: Explicit operator path override fora2m-docs/dc-doc-service.DC_AUTH_ROLE: Sets the access role:admin(default): Unrestricted access to all tools.workspace: Permits all filesystem operations and standard developer commands; blocks destructive administrative tools (force_terminate,set_config_value).read_only: Prohibits all mutating operations (write_file,edit_block,start_process,kill_process); permits only read and search tools.
A2M natively bridges the AI client and the human operator through zero-overhead local IPC sockets and Server-Sent Events (SSE). While an AI assistant is running tasks, the human developer can observe and interact with live processes from any terminal or browser window:
# List active and recent processes launched by the AI agent
a2m ps
# Stream real-time colored stdout and stderr from all AI processes
a2m watch
# Attach directly to a running AI process; watch output and send stdin from your keyboard
a2m attach <PID>Launch A2M as a standing background daemon providing both MCP SSE transport and an interactive browser dashboard:
a2m server --port 8765- Live Web Dashboard: Open
http://127.0.0.1:8765in your browser to inspect running processes, view real-time log streams, inject terminal input, and terminate tasks. - SSE MCP Transport: Connect remote or local AI clients via HTTP Server-Sent Events at
http://127.0.0.1:8765/sse(messages posted to/message?sessionId=...). - REST Management API: Programmatic endpoints for external dashboards and scripts:
GET /api/sessions: Returns active process sessions.GET /api/stream: Real-time SSE event stream for stdout/stderr/exits.POST /api/stdin: Send interactive text into a process stdin ({"pid": 1234, "input": "y\n"}).POST /api/kill: Send SIGTERM to a running process ({"pid": 1234}).