Protocol overview

Protocol overview covers how the snowpea daemon and clients communicate over WebSocket JSON-RPC, how versioning works, and how to read the reference.

On this page

• Understand how it is generated
• Check the connection
• Start a connection
• Check version rules
• Choose where to begin
• Inspect live data

Understand how it is generated

The protocol is defined in core/snowpea_core/server/protocol.py. That file contains PROTOCOL_VERSION, every method's parameter and result schema, and every event payload.

The generated artifacts are the reference document and the TypeScript bindings (sdk/src/protocol.ts). Neither artifact is hand-edited, and CI fails the build if they drift.

uv run python scripts/gen_protocol.py --check

Item	Location or value
Protocol definition	core/snowpea_core/server/protocol.py
Version constant	PROTOCOL_VERSION
TypeScript bindings	sdk/src/protocol.ts
Generation check command	uv run python scripts/gen_protocol.py --check
Reference	protocol reference

The current version is 1.5.0.

Check the connection

At start-up the daemon binds a loopback-only port. The daemon records the port and authentication data in $SNOWPEA_HOME/daemon.json as {port, pid, token, startedAt, protocolVersion}.

A client reads $SNOWPEA_HOME/daemon.json before connecting.

Surface	Endpoint	Purpose
WebSocket	ws://127.0.0.1:<port>/ws	JSON-RPC 2.0, bidirectional
HTTP GET	/health	liveness probe
HTTP GET	/protocol.json	this schema, as JSON
HTTP GET	/version	server and protocol versions

The daemon is not exposed to the network. Code on another host is handled by selecting a backend (docker, ssh), not by opening a port.

Start a connection

Immediately after connecting, a client calls system.hello. The parameters are the token from $SNOWPEA_HOME/token, the client version, and the protocol version the client was built against.

{"jsonrpc":"2.0","id":1,"method":"system.hello",
 "params":{"token":"…","clientVersion":"0.1.0","protocolVersion":"1.5.0"}}

1. Connect to the WebSocket endpoint ws://127.0.0.1:<port>/ws. When the connection opens, JSON-RPC 2.0 messages can be sent.
2. Call system.hello with the JSON-RPC request above. On success, the result contains protocolVersion, serverVersion, and a capabilities list.
3. Call any other method before system.hello. The request fails with unauthorized.
4. Call system.hello with a protocol version whose major version does not match. The request is rejected with protocol_incompatible.

After the version freeze, feature negotiation happens through capabilities.

Check version rules

PROTOCOL_VERSION is semver.

Change type	Rule
Freeze criteria	version 1.0.0, no change to the reference or the generated schema across three consecutive release tags, and the SDK contract tests passing on all three
Additive changes	minor bump and capabilities negotiation in system.hello
Major changes	changes that require releasing every client at the same time

Choose where to begin

Read the reference in this order.

1. Check Transport and handshake. This section describes transport and the system.hello procedure.
2. Check Methods. It provides parameter and result schemas for session.*, turn.*, approval.*, agent.*, gateway.*, schedule.*, memory.*, audio.*, settings.*, system.*.
3. Check Events. It defines the daemon-pushed events message.delta, message.done, tool.call, tool.result, diff, subagent.*, team.task.update, mode.changed, usage, error, turn.done.
4. Check Versioning. This section describes the freeze gate and version-change rules.

When implementing a client, also read the core manual's Protocol page for background. The generated reference provides the exact schema.

Inspect live data

The headless CLI uses this protocol. With --json, it emits events as JSON Lines.

snowpea -c "summarise README.md" --json

The daemon can return the schema directly.

curl "http://127.0.0.1:<port>/protocol.json"

<port> is in $SNOWPEA_HOME/daemon.json.

---

Next steps

Read the full schemaOpen the generated reference.→Understand the architectureSee how the daemon and clients fit.→