The mesh command group provides tools for managing distributed LLM sessions across multiple nodes. Sessions can be pushed to remote nodes, transferred between nodes, and continue running even when disconnected from the local terminal.
Use mesh serve to start a mesh node, mesh push to send sessions to remote
nodes, and mesh attach to connect to running sessions.
Usage:
sonny mesh [command]
Persistent flags
These apply to every mesh subcommand except serve, which has its own
listener-side flags.
| Flag | Type | Description |
|---|---|---|
--client-ca | string | CA bundle file used to verify the server cert |
--client-cert | string | client TLS certificate file (PEM) for mTLS-protected mesh endpoints |
--client-key | string | client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512) |
--client-key-pin | string | PIN file for PKCS#11 client key (optional) |
--dev-insecure-transport | — | DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production) |
--endpoint | string | mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052) |
-h, --help | — | help for mesh |
--server-name | string | SNI / cert-SAN match target (required when --client-cert is set) |
Mesh subcommands also accept the global flags .
Subcommands
| Subcommand | Purpose |
|---|---|
adopt | Adopt a running session using a pinned, single-use offer |
attach | Attach to a running session |
detach | Detach from a session |
exec | Run a shell command on a remote mesh node via its A2A endpoint |
host | Bootstrap and manage SSH-reachable mesh hosts |
human-key | Manage the keys that let a device attach to mesh sessions as their human |
identity | Provision and inspect mesh node identity material |
list | List nodes and sessions (alias ls) |
nodes | List mesh nodes |
peers | Print this daemon’s mesh participation snapshot as JSON |
push | Push a session to a remote node |
relate | Grant, revoke and list peer relationships between root sessions on two nodes |
serve | Start a mesh node |
sessions | List mesh sessions |
terminate | Terminate one or many mesh sessions (aliases kill, stop) |
transfer | Transfer a session to another node |
sonny mesh service install|uninstall|run exists only on Windows builds
(manages the mesh node as a Windows service); it is absent from this command
tree entirely on Linux/macOS builds, where systemd/launchd own that job instead.
mesh serve
Start a mesh node that can host and transfer sessions. The node listens for gRPC client connections for session streaming and compatibility, advertises on the Synapse QUIC peer plane using protobuf framing by default, retains WebSocket and JSON negotiation for rolling-upgrade compatibility, accepts sessions from other nodes, and sends heartbeats to announce availability.
Usage:
sonny mesh serve [flags]
| Flag | Type | Description |
|---|---|---|
--advertise-addr | string | address peers should use to reach this node’s gRPC surface, e.g. a reachable tailscale DNS name like “lothiriel:9052” (default: --grpc); required on a multi-host mesh because the bind address is not routable from a peer |
--authz-policy | string | path to the RBAC policy YAML (default /etc/sonny/mesh/authz.yaml) |
--ca | string | TLS CA certificate file |
--cert | string | TLS certificate file |
--control-db | string | path to the SQLite mesh control-plane DB (default <data>/control.db) |
--coordinator | string | mesh coordinator address (if joining existing mesh) |
--grpc | string | gRPC listen address (default “:50052”) |
-h, --help | — | help for serve |
--key | string | TLS key file |
--label | strings | node labels (key=value) |
--managed-manifest | string | private managed-worker deployment manifest (required in production builds) |
--max-sessions | int | maximum concurrent sessions (default 10) |
--mesh-peer | strings | quic:// peer URL (preferred), or ws:// development / wss:// mTLS compatibility URL (repeatable) |
--models | strings | supported models |
--name | string | node name (default: $(whoami)@$(hostname)) |
--node-id | string | node ID (default: auto-generated UUID) |
--providers | strings | supported LLM providers |
--recipes | strings | available recipes |
--region | string | node region (for routing) |
--synapse-listen | string | address Synapse listens on for QUIC/UDP (default) and WebSocket/TCP compatibility (default “:50053”) |
--trust-domain | string | SPIFFE trust domain for peer SVIDs (default mesh.local) |
--zone | string | node zone (for routing) |
mesh push
Usage:
sonny mesh push [flags]
| Flag | Type | Description |
|---|---|---|
-f, --file | string | local recipe file whose recipe ID is sent (or use --pack) |
--follow | — | follow session output after push |
-h, --help | — | help for push |
--node | string | target node ID (default: best available) |
--persist | — | persist session on detach (default true) |
--recipe | string | ID of the recipe the target node runs (or use --file) |
--session-dir | string | absolute working directory for the session on the target node (default: the current directory) |
mesh attach and mesh detach
sonny mesh attach <session-id> connects to a running session.
| Flag | Type | Description |
|---|---|---|
-h, --help | — | help for attach |
--read-only | — | attach in read-only mode |
sonny mesh detach leaves the session:
| Flag | Type | Description |
|---|---|---|
-h, --help | — | help for detach |
--keep-running | — | keep session running in background (default true) |
--stop | — | pause session instead of backgrounding |
mesh transfer
Usage:
sonny mesh transfer [flags]
| Flag | Type | Description |
|---|---|---|
--force | — | force transfer even if session is active |
-h, --help | — | help for transfer |
mesh terminate
sonny mesh terminate [session-id] (aliases kill, stop).
| Flag | Type | Description |
|---|---|---|
--all | — | terminate every matching session (requires --node or --all-nodes) |
--all-nodes | — | with --all, terminate sessions on every node |
--force | — | force terminate without graceful shutdown |
-h, --help | — | help for terminate |
--node | string | node ID for --all (terminates all sessions on this node) |
--reason | string | reason for termination |
--yes | — | skip the interactive confirm for --all or --all-nodes |
Inspecting nodes and sessions
sonny mesh list (alias ls) lists nodes and sessions; it takes no flags
beyond -h/--help.
sonny mesh nodes:
| Flag | Type | Description |
|---|---|---|
-h, --help | — | help for nodes |
--region | string | filter by region |
--zone | string | filter by zone |
sonny mesh sessions:
| Flag | Type | Description |
|---|---|---|
-a, --all | — | show all sessions including completed |
-h, --help | — | help for sessions |
--isolation-assurance | string | filter by achieved assurance |
--isolation-backend | string | filter by achieved backend |
--isolation-state | string | filter by isolation verification state |
--search | string | filter by session, recipe, model, provider, or node text |
--sort | string | sort by updated, assurance, backend, or isolation-state (default “updated”) |
Attaching one session without a node
To expose a single interactive session so a remote client can attach to it
without running a full node, use --mesh-self on
sonny run
.