ACP server
Run nod as an Agent Client Protocol (ACP) server to use the nod agent from compatible editors and clients.
Configure an ACP client
Start the server from the project that should be the primary workspace:
cd /absolute/path/to/project && nod acp
Configure the client to launch the absolute binary path when possible:
{
"command": "/absolute/path/to/nod",
"args": ["acp"]
}
The client process working directory becomes the primary workspace. Launch a separate server process for each primary workspace.
nod acp accepts two options:
| Option | Behavior |
|---|---|
--model <id> |
Override the model for the server process, including loaded sessions. |
--log-file <path> |
Write ACP diagnostics to an absolute file path. |
Global workspace flags such as --add-dir, --no-additional-dirs, and --context-limit must appear before acp.
Authentication and nod settings
ACP uses the selected nod provider and saved credentials. Complete Authentication before the client starts the server.
The server uses the same settings, project instructions, skills, sessions, permissions, and tools as interactive nod.
Supported ACP methods
The client must call initialize first. nod responds with ACP protocol version 1 and supports these methods:
| Method | Behavior |
|---|---|
initialize |
Negotiate protocol capabilities and initialize the connection. |
session/new |
Create and activate a saved session. |
session/load |
Load an exact session ID and replay its history. |
session/resume |
Reconnect to a saved session without replaying its history. |
session/close |
Close the active session. |
session/list |
List sessions for the primary workspace. |
session/prompt |
Run one turn in the active session. |
session/cancel |
Cancel the active prompt. |
session/set_config_option |
Change the active model or mode. |
session/set_mode |
Change the active mode. |
Each connection has one active session and one active prompt. A second session/prompt while one is running is rejected.
Sessions, models, and permissions
New and loaded sessions expose model and mode selectors. Model changes are saved to the active session, while a process-level --model override takes precedence over the model stored in a loaded session.
| Mode | Permission behavior |
|---|---|
ask |
Request approval for unresolved sensitive tool calls. |
code |
Automatically review unresolved sensitive tool calls. |
Both modes expose the available runtime tools. Before the client selects a mode, nod uses the permission mode from the active configuration.
An Allow for this session approval remains active only for the current session. It is not written to settings or restored when the session is loaded again.
Prompt and MCP support
session/prompt accepts text, embedded resources, and inline image blocks. Images are sent to the session model; see Vision. Audio blocks are not supported.
Clients receive streamed user and agent messages, tool status updates, and permission requests. Tool calls arrive as a tool_call followed by tool_call_update messages, and shell commands include a command_result.
ACP sessions combine client-supplied mcpServers with approved servers from the workspace .mcp.json. A client entry wins a same-name project entry. Pending or rejected project servers remain unavailable, and ACP never inherits servers from ~/.nod/mcp.json. Clients can provide stdio, HTTP, or SSE servers.
Protocol limits
ACP uses newline-delimited JSON-RPC 2.0 over stdin and stdout. Each input message is limited to 8 MiB.
Protect the protocol stream
Stdout is reserved for ACP messages. Write diagnostics to
--log-fileinstead.