acpremote

# 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](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py) for exposure-path questions 3. open the [remote client module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/client.py) and the [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py) for mirror-path questions 4. open the [command transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/command.py) 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](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py), [transport config module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/config.py) | | expose a stdio ACP command over WebSocket | Yes | [command transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/command.py), [server transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py) | | mirror a remote ACP endpoint locally | Yes | [remote client module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/client.py), [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py) | | bearer auth or metadata routes | Yes | [auth helpers](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/auth.py), [metadata module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/metadata.py), [server transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py) | | remote host ownership or `remote_cwd` | Yes | [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py), [remote client module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/client.py), [metadata module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/metadata.py) | | line buffering / frame relay issues | Yes | [stream bridge module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/stream.py) | | 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 - explicit ACP unstable-protocol opt-in for elicitation routes 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](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpremote/SKILL.md) - [Raw transport docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/acpremote.md) - [Raw remote-host docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/examples/remote-hosting.md) - [Rendered docs](https://vcoderun.github.io/acpkit/acpremote/) - [Source tree](https://github.com/vcoderun/acpkit/tree/main/packages/transports/acpremote) Cross-skill references: - [Root package skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpkit-sdk/SKILL.md) - [Pydantic adapter skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/pydantic-acp/SKILL.md) - [LangChain adapter skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/langchain-acp/SKILL.md) ## 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](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/__init__.py) ## Module Guide | Subsystem | Key files | Use them for | | --- | --- | --- | | server and routing | [server transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py), [auth helpers](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/auth.py), [metadata module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/metadata.py), [transport config module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/config.py), [limit definitions](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/limits.py) | server startup, mount paths, metadata, health, auth, limits | | remote client and proxy behavior | [remote client module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/client.py), [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py) | remote connection setup, metadata fetch, local mirroring, host ownership | | command-backed transport | [command transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/command.py) | stdio ACP commands that need WebSocket exposure | | stream plumbing | [stream bridge module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/stream.py) | 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 For ACP 0.11 unstable client requests, pass `--unstable-protocol` to `acpremote mirror` or set `TransportOptions(use_unstable_protocol=True)` on `connect_acp(...)`. The option belongs to the receiving upstream client connection. It remains disabled by default and does not imply capability support. ## 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](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py) 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](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/serve_command.py) - [Remote mirror recipe](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/mirror_remote.py) - [Skill-local example notes](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/README.md) 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](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpkit-sdk/examples/README.md) - [Public Pydantic example](https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/finance_agent.py) - [Public LangChain example](https://github.com/vcoderun/acpkit/blob/main/examples/langchain/workspace_graph.py) ## 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. - Do not require an agent-side unstable flag merely to send elicitation. The client connection receiving `elicitation/create` registers that route; capability negotiation is separate. - 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.