MUE SyncFeaturesHow It WorksSetupDocsFAQDownload

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

Ports summary

PortServiceWho listens
6670P2P file transferEvery agent
6668Peer introducerRelay box
6667Status HTTPRelay box
6666UE discovery (UDP)Relay box
4200Docs + landing siteEdge gateway