Set up the sandbox
superserve/node-22 template and install the adapter in it. The Python code is complete in the next section.
TypeScript
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 withsandbox.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.
hello.js and runs it in the sandbox:
- 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 thefsorterminalcapabilities, 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_permissionrequest. 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/promptwith the samesessionIdbefore thefinallyblock 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
codex-acp instead of claude-agent-acp. NO_BROWSER=1 hides the ChatGPT sign-in option, which needs a browser:
TypeScript
initialize, call authenticate with the api-key method:
TypeScript
CODEX_CONFIG in env, for example CODEX_CONFIG: JSON.stringify({ model: "gpt-5.5" }).
Delete when finished
The examples delete the sandbox withsandbox.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.