Running the Mesh

Start a node 

sonny mesh serve \
  --grpc 127.0.0.1:50052 \
  --synapse-listen 127.0.0.1:50053 \
  --control-db /var/lib/sonny/control.db

The node listens for gRPC client connections, advertises on the Synapse QUIC peer plane, sends heartbeats to announce availability, and accepts sessions pushed from other nodes.

A two-node mesh over mTLS

Both planes take the same certificate material. --advertise-addr is what makes the pair reachable: each node publishes the address the other can route to.

# host-a
sonny mesh serve \
  --name worker-a \
  --grpc 0.0.0.0:50052 --advertise-addr host-a:50052 \
  --synapse-listen 0.0.0.0:50053 \
  --cert /etc/sonny/host-a.pem --key /etc/sonny/host-a-key.pem \
  --ca /etc/sonny/mesh-ca.pem \
  --trust-domain mesh.local \
  --region eu --zone eu-1 \
  --providers anthropic,openai --models gpt-5-mini \
  --max-sessions 8

# host-b
sonny mesh serve \
  --name worker-b \
  --grpc 0.0.0.0:50052 --advertise-addr host-b:50052 \
  --synapse-listen 0.0.0.0:50053 \
  --mesh-peer quic://host-a:50053 \
  --cert /etc/sonny/host-b.pem --key /etc/sonny/host-b-key.pem \
  --ca /etc/sonny/mesh-ca.pem \
  --trust-domain mesh.local \
  --region eu --zone eu-2

--mesh-peer prefers quic://. ws:// is a development URL and wss:// is the mTLS compatibility URL; both exist for rolling upgrades, not for new deployments.

Managed deployments

Production builds expect an explicit deployment contract rather than ambient trust:

FlagPurpose
--managed-manifestprivate managed-worker deployment manifest (required in production builds)
--control-dbpath to the SQLite control-plane DB (default <data>/control.db)
--authz-policyauthorization policy file
--node-idstable node ID (default: generated UUID)
--namedisplay name (default: $(whoami)@$(hostname))
--coordinatoraddress of a node in an existing mesh to join

Point a chat at the mesh

Three options, weakest to strongest coupling:

# 1. Just show a peer in the TUI's Connect dialog
sonny run --mesh-peer host-a:50052 --mesh-peer host-b:50052

# 2. Observe a specific node from the mesh panel
sonny run --mesh-addr host-a:50052

# 3. Embed a node in this chat so others can attach to it
sonny run --mesh-self --mesh-self-grpc :50052 --mesh-self-synapse :50053

--mesh-peer is repeatable, and both --mesh-addr and --mesh-peer also read from the mesh: block of your config or from SONNY_MESH_ADDR, so you can set peers once in .sonny.yaml instead of retyping them.

Note
--mesh-self registers the current session with the embedded node. Without it, your session is local-only and nothing can attach to it.

Checking the mesh 

sonny mesh nodes          # what is up
sonny mesh sessions       # what is running
sonny mesh sessions -a    # include completed sessions

Flag-level detail lives in the mesh CLI reference .