meshd Wire Protocol — Reference Specification

**Status:** Informational **Version:** 1.0 **Source:** `https://github.com/mohameddiomande/meshd` 1. [Overview](#1-overview) 2. [Authentication](#2-authentication) 3. [Slot API](#3-slot-api) 4. [Mesh API](#4-mesh-api) 5. [Slot Lifecycle](#5-slot-lifecycle) 6. [Configuration](#6-configuration) 7. [Topology](#7-topology) 8. [Building a Client](#8-building-a-client) 9. [Error Reference](#9-error-reference) 10. [Future Work](#10-future-work) meshd is a Rust daemon that manages a static registry of agent slots — named PTY processes (Claude, Codex, OpenCode, Gemini, or any CLI agent) — and exposes them over an HTTP/1.1 REST API. Each machine in a Tailscale mesh runs its own independent meshd instance. Machines discover each other via a hard-coded static node table and coordinate through peer-to-peer HTTP calls. - **Direct PTY ownership.** Each slot is a real forked process with a master PTY. Injection writes bytes directly to the PTY master fd. No shell wrapper, no exec layer. - **Zero inter-node dependencies at boot.** Every node runs standalone. Mesh coordination is best-effort; a node failure does not affect the others. - **Stateless HTTP.** All slot state is in-process. No shared database is required for operation (Supabase is used for fleet visibility only, not for control-plane decisions). - **ANSI-clean output.** The PTY reader strips ANSI escape sequences before writing to the ring buffer, so consumers get plain text lines. | Property | Value | |---|---| | Protocol | HTTP/1.1 | | Default port | 9451 | | Alternate mesh-api compat port | Configurable via `mesh_port` | | Bind address | `[ip]` (all interfaces) | | Content type | `application/json` (all endpoints except `/stream`) | | Streaming | `text/event-stream` (SSE, `/stream/:slot` only) |