The Sonny Mesh
Sonny sessions are not pinned to the terminal that started them. The mesh turns a set of machines into a session fabric: any node can host a session, any authorized operator can watch or drive that session from anywhere else in the mesh, and a running session can be transferred between nodes without losing context.
This is the mechanism behind long-running work that outlives one laptop session — a refactor that keeps going while you move from your desk machine to your workstation, or a supervised fleet of workers pinned to a beefy build host.
What the mesh gives you
| Capability | Command |
|---|---|
| Start a node that hosts sessions | sonny mesh serve |
| See which nodes are up | sonny mesh nodes |
| List sessions across the mesh | sonny mesh sessions |
| Push a local session to a node | sonny mesh push |
| Watch or drive a remote session | sonny mesh attach <session-id> |
| Leave a session running remotely | sonny mesh detach |
| Move a session to another node | sonny mesh transfer <session-id> <target-node> |
| Stop sessions | sonny mesh terminate |
Two planes carry the traffic:
- Client plane — gRPC, on
Config.GRPCAddress(default:50052). This is whatsonny mesh attach, the CLI, and the desktop app connect to. - Peer plane — Synapse QUIC with a WebSocket fallback for rolling upgrades, on
Config.SynapseListen(default:50053). This is node-to-node.
Two ways to be in the mesh
You do not have to run a dedicated node to participate.
- Ad hoc. Run
sonny --mesh-self. Your chat embeds an in-process mesh node and registers the session with it, so another machine can attach to it. - Managed node. Run
sonny mesh serveas a long-lived service. Sessions are created on it (or pushed to it) and it is the thing you point at with--mesh-addr.
Where to go next
- Mesh architecture — the two planes, isolation reporting, and the control-plane database.
- Running the mesh — flags, mTLS, peer SVIDs, authorization policy, and a two-node example.
- Working with sessions — attach, detach, transfer, terminate, and the session filters that matter on a busy mesh.
For the per-command flag tables see the mesh CLI reference .