Skip to main content
The Agent Client Protocol (ACP) is an open JSON-RPC protocol between a client, such as an editor, and a coding agent. The agent runs as a subprocess and exchanges messages with the client over stdin and stdout. Run the agent in a Superserve sandbox and keep your client outside it: the agent’s file edits and shell commands stay in the sandbox, and your client receives the same stream of messages, tool calls, and permission requests. This page uses these ACP adapters:

Set up the sandbox

Create a sandbox from the superserve/node-22 template and install the adapter in it. The Python code is complete in the next section.
TypeScript
The adapter reads ANTHROPIC_API_KEY as usual, but its value is a stand-in token — the real key is attached only on requests to Anthropic, never exposed to the agent.

Connect an ACP client

Start the adapter with sandbox.commands.spawn(). Then connect its stdin and stdout to an ACP client from the ACP SDK. ACP sends one JSON message per line, so the bridge only has to move bytes in each direction.
The agent writes hello.js and runs it in the sandbox:
Some points about this client:
  • Files stay in the sandbox. The client sends empty clientCapabilities, so the agent reads and writes files and runs commands with its own tools in the sandbox. If you advertise the fs or terminal capabilities, the agent sends those operations to your client instead.
  • Permissions come to your client. Before a tool call, the agent can send a session/request_permission request. The handler above approves each call once. A real client shows the request to the user.
  • The session stays open until you close it. To continue the conversation, send another session/prompt with the same sessionId before the finally block closes the process.
  • The client notices when the adapter stops. The bridge watches wait(). If the adapter exits or the connection drops, the stream ends and pending requests fail instead of waiting forever.
agent-client-protocol 1.0.0 for Python logs Method not found for the auth/status_update notification that the Claude Code adapter sends. The error does not stop the session.

Use Codex

The Codex adapter needs three changes. Bind your OpenAI key and install the adapter:
TypeScript
Spawn codex-acp instead of claude-agent-acp. NO_BROWSER=1 hides the ChatGPT sign-in option, which needs a browser:
TypeScript
After initialize, call authenticate with the api-key method:
TypeScript
To choose the model, set CODEX_CONFIG in env, for example CODEX_CONFIG: JSON.stringify({ model: "gpt-5.5" }).

Delete when finished

The examples delete the sandbox with sandbox.kill() in a finally block, so a failed run does not leave it running. Deleting a sandbox also deletes its files and saved state. To keep the sandbox for more sessions, remove that call and delete the sandbox later. To delete it from another process, pass its ID to Sandbox.killById() (TypeScript) or Sandbox.kill_by_id() (Python). To delete paused sandboxes automatically, see Auto-delete.