ACP server

Run fx as an Agent Client Protocol (ACP) server to use the fx 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 && fx acp

Configure the client to launch the absolute binary path when possible:

{
  "command": "/absolute/path/to/fx",
  "args": ["acp"]
}

The client process working directory becomes the primary workspace. Launch a separate server process for each primary workspace.

fx 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 fx settings

ACP uses the existing fx authentication and configuration. Complete Authentication before the client starts the server. Initialization fails when no usable AI Gateway credential is available.

The server uses the same settings, project instructions, skills, sessions, permissions, sandbox, and tools as interactive fx.

Supported ACP methods

The client must call initialize first. fx 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.

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, fx 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 and embedded resource blocks. ACP does not accept image or audio blocks; use interactive fx or fx ask --image for visual input.

Clients receive streamed user and agent messages, tool status updates, and permission requests.

ACP sessions use only the mcpServers supplied by the client. They do not inherit servers from ~/.fx/mcp.json; omitting mcpServers starts the session without MCP servers. 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-file or FX_TRACE_LOG instead.