Node Connection
The WebSocket a node opens to the control plane to receive actors. Advanced; use rivetkit-core instead of implementing it.
A node is a process that runs your actor code. It registers with the control plane by opening one long-lived WebSocket and then receives commands over it: start this actor, stop that one, deliver this message. Every RivetKit runtime opens this connection for you.
This protocol is internal and changes between releases. Do not implement it by hand. If you are bringing RivetKit to a new language, bind to rivetkit-core, the Rust library that already speaks it and that the TypeScript runtime is built on.
GET wss://rivet.example.com/envoys/connect
| Query parameter | Description |
|---|---|
protocol_version | Protocol version the node speaks. The control plane rejects versions it has not agreed to. |
namespace | Namespace the node serves. |
pool_name | Node pool the node joins. Actors created with rvt-pool or pool matching this name run on it. |
envoy_key | Identifier for this node process, unique within the pool. |
version | Integer build version of the node. When a pool has drain_on_version_upgrade set, connecting a newer version drains nodes on older versions. |
The token travels as a rivet_token.{token} subprotocol, the same as other WebSocket endpoints. See Authentication. It must be your Rivet token or a scoped token granting create on the node resource.
Messages are binary BARE frames. The schema, versioned message types, and a reference client live in the repository:
- Protocol schemas, one
.barefile per protocol version - Rust protocol types generated from the schemas
- Rust client, the transport rivetkit-core uses to hold this connection
To see which nodes are connected, use List Nodes.