Skip to content
Wayland Docs

ACP Server and Client

The acp subcommand exposes Wayland Core over the Agent Client Protocol (ACP) on an HTTP/SSE transport. acp serve binds a port and serves sessions; acp request is a one-shot client for talking to a running server. The Wayland desktop app uses this same ACP backend to host the engine.

Serve

Section titled “Serve”

Bind the transport to a TCP port:

Terminal window
wayland-core acp serve --bind 127.0.0.1:8080

--bind defaults to 127.0.0.1:8080. On first run the server generates an API key, stores it, and prints it once to stderr. Pass it as an X-API-Key header on every request to the server.

Request

Section titled “Request”

acp request exercises the server’s endpoints from the command line. It is mostly a smoke test for a running serve, but the operations map directly to the protocol.

Point it at a base URL (no trailing slash), then choose an operation:

Terminal window
# Create a session, print the new session_id
wayland-core acp request --base-url http://127.0.0.1:8080 create-session


# Create with a specific model
wayland-core acp request create-session --model claude-sonnet-4-6


# List, get, and delete sessions
wayland-core acp request list-sessions
wayland-core acp request get-session <SESSION_ID>
wayland-core acp request delete-session <SESSION_ID>

--base-url defaults to http://127.0.0.1:8080.

Send a message

Section titled “Send a message”

send posts text to a session and streams the response events to stdout, one JSON object per line, exiting when the stream ends:

Terminal window
wayland-core acp request send <SESSION_ID> "Summarize the README"

How the desktop uses it

Section titled “How the desktop uses it”

The Wayland desktop app drives the engine through this ACP backend rather than spawning a raw process per turn. The CLI surface here is the same protocol the app speaks, so you can stand up a server and connect any ACP-aware client to it.

Next

Section titled “Next”