ClaudeCode.Adapter.Node (ClaudeCode v0.29.0)

View Source

Distributed adapter that runs Adapter.Port on a remote BEAM node.

Connects to a remote node via Erlang distribution, creates a workspace directory, and starts Adapter.Port there. After startup, Session talks directly to the remote adapter — GenServer.call/2 and send/2 work transparently across connected BEAM nodes.

Usage

{:ok, session} = ClaudeCode.Session.start_link(
  cwd: "/workspaces/tenant-123",
  model: "claude-sonnet-4-20250514",
  adapter: {ClaudeCode.Adapter.Node, [
    node: :"claude@gpu-server"
  ]}
)

Session-level options (:model, :cwd, :system_prompt, etc.) are passed to start_link/1 as usual. They are merged into the adapter config automatically. The adapter tuple only needs Node-specific options (:node, :cookie, :connect_timeout, :callback_timeout) which are consumed by this module and not forwarded to the remote Adapter.Port.

In-Process MCP Tools and Hooks

MCP tools (defined with ClaudeCode.MCP.Server) always execute on the local node — they are routed through a CallbackProxy GenServer that lives on your app server.

Hooks support a :where option on matcher configs:

  • :local (default) — runs on your app server via the proxy
  • :remote — runs on the sandbox server in the remote Adapter.Port

The can_use_tool callback always runs locally.

Failure Handling

The distributed link between Session and the remote adapter fires on nodedown. Session receives {:EXIT, pid, :noconnection} and handles it like any adapter crash. No automatic reconnection — create a new Session to reconnect.