How It Works
The full technical design: watcher, peers, protocol, safety.
Understanding the moving parts helps you trust the system and debug it. Here is how MUE Sync works under the hood.
High-level flow
Artist A saves a file -> watcher detects change -> agent reads + hashes the file -> sends it over an existing P2P socket to every connected peer -> Artist B writes it atomically and verifies the SHA-256 hash before swapping it in.
Components
1. The watcher
The agent uses Node's recursive fs.watch on the project root. Changes are debounced for
1.5 seconds, so rapid saves collapse into one send. Anything in the ignore list is filtered out before
a send is even scheduled, and files the agent itself just received are suppressed to prevent an echo
loop.
2. The peer registry
Agents keep a live map of peers (peer ID to socket). Peers are added when the relay hands out an
introducer list or announce frame. A second machine that comes online is announced to all,
and everyone opens a direct connection to it.
3. Sending files
Each transfer is two parts over a single socket: a one-line JSON header with metadata, then the raw body bytes, then a newline terminator. Writes on each socket are serialized onto a promise chain so frame bytes never interleave and corrupt the protocol, which is essential because TCP is a byte stream. Large files are streamed in chunks over the socket and hash-verified at both ends.
4. Receiving and atomic write
On receive, the file is written to a temp location inside Content/.mue-sync-incoming,
its SHA-256 hash is compared with the metadata, and only on a match is it renamed into place. This means
a peer never sees a half-written asset. For real asset files (.uasset, .umap,
.fbx, etc.) a marker is appended so a local UE hot-reload plugin can act.
5. Offline catch-up
When a socket opens, the receiving side requests recent files. The sender walks the tree and resends anything modified within the last 10 minutes (capped at 2000 files), so rejoining a session does not miss recent work.
6. The relay / introducer
This is a small TCP service on port 6668. It keeps a registry of peers and their Tailscale IPs and P2P ports. It does not relay file data. It only answers "who is on the network and how do I reach them". Agent connect/disconnect is retried every 5 seconds.
Safety guarantees
- Integrity: SHA-256 verified on every file before it is committed locally.
- Atomicity: temp file + rename means no partial/corrupt assets.
- No echo loops: recently-received files are suppressed and re-broadcasts are deduped.
- Privacy: everything rides on your Tailscale VPN; the relay never stores data.
- No dependencies: pure Node.js built-ins, so no
npm installneeded.
Ports summary
| Port | Service | Who listens |
|---|---|---|
| 6670 | P2P file transfer | Every agent |
| 6668 | Peer introducer | Relay box |
| 6667 | Status HTTP | Relay box |
| 6666 | UE discovery (UDP) | Relay box |
| 4200 | Docs + landing site | Edge gateway |