acpremote

name	acpremote
description	Use for `acpremote` tasks: exposing ACP agents or stdio ACP commands over WebSocket, mirroring remote ACP endpoints locally, host ownership semantics, metadata/auth routes, and remote transport examples.

acpremote Skill

Use this skill when the task is about the acpremote transport package.

This package is the repo's ACP transport/helper layer. It assumes the runtime already speaks ACP and focuses on moving that ACP boundary across WebSocket transport or back into a local ACP proxy.

It is not an adapter.

That distinction matters:

• adapters turn framework runtimes into ACP
• acpremote transports or mirrors an ACP boundary that already exists

Start Here

If you only need the shortest high-signal path:

1. read Quick Routing
2. open the server transport module for exposure-path questions
3. open the remote client module and the proxy agent module for mirror-path questions
4. open the command transport module only when the upstream runtime is ACP-over-stdio

Quick Routing

If the task is about...	Use this skill?	Open first
expose an existing ACP agent over WebSocket	Yes	server transport module, transport config module
expose a stdio ACP command over WebSocket	Yes	command transport module, server transport module
mirror a remote ACP endpoint locally	Yes	remote client module, proxy agent module
bearer auth or metadata routes	Yes	auth helpers, metadata module, server transport module
remote host ownership or remote_cwd	Yes	proxy agent module, remote client module, metadata module
line buffering / frame relay issues	Yes	stream bridge module
adapting a Pydantic or LangChain runtime to ACP	No, pair with adapter skill	adapter packages

Package Boundary

acpremote owns:

• WebSocket transport
• stdio-to-WebSocket ACP relaying
• remote mirror proxy behavior
• /acp metadata
• /healthz
• bearer-token protection
• transport latency metadata/projection
• host-ownership policy for mirrored clients

It does not own:

• adapting pydantic_ai.Agent
• adapting LangGraph/LangChain graphs
• root CLI target loading
• Codex auth parsing

Do Not Confuse With

• acpremote vs acpkit-sdk acpremote is transport; acpkit is the root CLI/runtime package
• acpremote vs pydantic-acp acpremote exposes or mirrors ACP; pydantic-acp creates ACP from a Pydantic runtime
• acpremote vs langchain-acp acpremote transports ACP; langchain-acp adapts graph runtimes into ACP

Primary References

Package references:

• Raw skill
• Raw transport docs
• Raw remote-host docs
• Rendered docs
• Source tree

Cross-skill references:

• Root package skill
• Pydantic adapter skill
• LangChain adapter skill

Public Surface

Server-side seams:

• serve_acp(...)
• serve_command(...)
• serve_stdio_command(...)

Client-side seam:

• connect_acp(...)

Support types:

• TransportOptions
• CommandOptions
• ServerOptions

Package entrypoint:

• Package entrypoint

Module Guide

Subsystem	Key files	Use them for
server and routing	server transport module, auth helpers, metadata module, transport config module, limit definitions	server startup, mount paths, metadata, health, auth, limits
remote client and proxy behavior	remote client module, proxy agent module	remote connection setup, metadata fetch, local mirroring, host ownership
command-backed transport	command transport module	stdio ACP commands that need WebSocket exposure
stream plumbing	stream bridge module	line buffering, text/binary frame handling, sender/receiver lifecycle

Core Transport Shapes

Shape 1: Existing ACP agent object

Use:

• serve_acp(...)

Meaning:

1. some runtime already produced an acp.interfaces.Agent
2. acpremote exposes that ACP boundary over WebSocket

Shape 2: Existing stdio ACP command

Use:

• serve_command(...)
• serve_stdio_command(...)

Meaning:

1. the upstream runtime only exposes ACP on stdin/stdout
2. acpremote spawns that command
3. stdin/stdout ACP frames are bridged onto WebSocket

Shape 3: Remote ACP mirrored locally

Use:

• connect_acp(...)

Meaning:

1. there is an existing remote ACP WebSocket endpoint
2. acpremote opens a remote connection
3. the local machine gets a proxy ACP agent that mirrors the remote endpoint

Remote Host Ownership

This is one of the most important rules in the package.

The default should keep the remote host authoritative for:

• cwd
• host-backed filesystem ownership
• host-backed terminal ownership

That is why the proxy layer:

• prefers remote metadata like remote_cwd
• strips local host-backed capabilities before forwarding initialize(...)

Use client passthrough only when the product explicitly wants the local machine to become host owner.

If a user reports:

• remote command executed in local cwd
• local filesystem used instead of remote filesystem
• remote agent owning the wrong host

inspect the proxy agent module and metadata flow first.

Metadata and Health Surface

The transport package also owns the lightweight HTTP surface around the WebSocket endpoint:

• /acp
• /healthz

Typical uses:

• health checks
• transport metadata inspection
• remote cwd discovery
• debugging auth and route configuration

This is transport-level behavior. Do not push it into adapter code.

Latency and Transport Visibility

acpremote can emit transport-observed latency through:

• metadata fields
• optional visible latency projection

Keep the distinction explicit:

• this is proxy-observed timing
• it is not a claim of clock-synchronized one-way network truth

Skill-Bundled Examples

Skill-local examples:

• Remote command exposure recipe
• Remote mirror recipe
• Skill-local example notes

These demonstrate:

• exposing a stdio ACP command remotely
• mirroring a remote ACP endpoint locally
• using TransportOptions intentionally

Handoff Rules

Pair or switch to:

• acpkit-sdk when the remote host is reached through acpkit serve ... or the local mirror is acpkit run --addr ...
• pydantic-acp when a Pydantic agent is adapted first, then exposed remotely
• langchain-acp when a LangGraph or DeepAgents graph is adapted first, then exposed remotely

Common end-to-end references:

• Root recipe index
• Public Pydantic example
• Public LangChain example

Guardrails

• Do not call acpremote an adapter.
• Do not claim it can adapt a framework runtime by itself.
• Do not blur ACP adaptation with ACP transport.
• If the task is really about acpkit run ... or acpkit serve ..., pair this skill with acpkit-sdk.

Production Baseline

• Bind to loopback unless an authenticated reverse proxy owns public TLS termination.
• Require bearer authentication or an equivalent trusted edge for non-loopback exposure.
• Bound metadata requests, WebSocket frames, stream buffers, command runtime, and command output.
• Every connection setup failure, reconnect, cancellation, and shutdown path must close the ACP connection, stream bridge, WebSocket, and child process it owns.
• Use configured native acp_agent exports when exposing adapter-backed examples; serving a raw framework target can discard custom adapter state.