GhostMesh Documentation

Quick Start

Option A: Instant execution via npx (Zero install)

You can run GhostMesh directly in any terminal using Node.js without needing to install Rust or Cargo:

# On Machine A (Host)
npx ghostmesh-cli invite

# On Machine B (Guest)
npx ghostmesh-cli join <ticket>

Option B: Building from Source

Clone the repository and build the workspace with Cargo:

git clone https://github.com/NeyorDEV/ghostmesh.git
cd ghostmesh
cargo build --release

# Run CLI
cargo run -p ghost-cli -- invite

# Run GUI
cargo run -p ghostmesh-gui

Downloads

Pre-compiled standalone binaries for 64-bit Windows are available from the GitHub Releases:

npm / npx Package

The official npm package ghostmesh-cli provides an instant cross-platform wrapper to execute GhostMesh commands anywhere Node.js is installed:

# Check version
npx ghostmesh-cli --version

# Display help
npx ghostmesh-cli --help

# Generate a fresh cryptographic identity
npx ghostmesh-cli keygen

# Discover your public STUN endpoint
npx ghostmesh-cli discover

Architecture Overview

1. Binary Wire Format

Every UDP packet in GhostMesh follows a compact binary layout with a fixed 43-byte header:

[0..2]   Magic Bytes (0x47, 0x4D -> "GM")
[2]      Packet Type (0x01: STUN_PROBE, 0x02: HANDSHAKE_INIT, 0x03: HANDSHAKE_RESP, 0x04: DATA, 0x05: KEEP_ALIVE)
[3..19]  Destination Node ID (16 bytes)
[19..35] Source Node ID (16 bytes)
[35..43] Sequence Number / Nonce (8 bytes Big-Endian)
[43..]   Encrypted Payload + Poly1305 Authentication Tag (16 bytes)

2. Noise Protocol Cryptography

Security is enforced via mutual authentication using the Noise_XX_25519_ChaChaPoly_BLAKE2s pattern:

• Key Exchange: Ephemeral & static Curve25519 keypairs.
• Cipher: ChaCha20-Poly1305 authenticated symmetric encryption (AEAD).
• Hash: BLAKE2s for transcript authentication and key derivation.

3. STUN & Automated UPnP Traversal

To bypass domestic routers and Carrier-Grade NAT (CGNAT):

1. Both nodes query public STUN servers (stun.l.google.com:19302) to discover reflexive IP:Port mappings.
2. Automated UPnP: GhostMesh automatically negotiates port 4242 UDP mapping on domestic Internet boxes via IGD, eliminating manual router port forwarding.
3. When pairing, nodes exchange synchronized UDP hole-punching probes to maintain open firewall state tables.
4. Background keep-alives every 10 seconds keep NAT port mappings open indefinitely.

4. Multi-Hop Mesh Routing

GhostMesh nodes act as autonomous transit routers. If Node A cannot directly reach Node C due to an asymmetric firewall, but both A and C have an active link with Node B, Node B seamlessly and securely forwards end-to-end encrypted packets between A and C without being able to decrypt the payload.

5. HTTPS / TCP Fallback Relay

When operating inside enterprise or university networks that strictly filter all outbound UDP traffic, GhostMesh automatically activates its fallback relay tunnel over standard HTTPS port 443, ensuring 100% connectivity even through the most restrictive firewalls.

6. Virtual Network Adapter (Wintun)

GhostMesh instantiates a virtual Layer 3 network interface (ghost0) powered by Wintun on Windows. It assigns an IP address in the private mesh subnet (10.42.0.0/16), allowing system tools like ping, SSH, and file transfers to traverse the P2P mesh as if connected over a local LAN.

Desktop Dashboard (GUI)

The desktop application provides a modern dark glassmorphism dashboard built with Tauri v2 and native Rust bindings:

• Live Status Indicators: Real-time display of local virtual IP (10.42.X.Y/16), public STUN endpoint, and cryptographic Node ID.
• One-Click Invite Generator: Create encrypted base64 gm1_... invitation tickets containing your Curve25519 public key and reflexive UDP endpoint.
• Active Mesh Links Table: View active peer endpoints, real-time RTT round-trip latency, and connection states (Connected / Disconnected).
• System Tray Minimization: Closes cleanly to the Windows system tray and runs silently in the background without terminal prompts.

Known Devices & Consent-Based Pairing

GhostMesh v0.2.1 introduces persistent device memory coupled with an explicit mutual consent authorization protocol. You no longer need to regenerate and exchange invitation codes for devices you frequently connect with:

How Consent Pairing Works

1. Automatic Memory: Whenever a peer connects via an invitation ticket, their Curve25519 public key, Node ID, and last known endpoint are securely saved to your local encrypted config (AppData/Roaming/GhostMesh/config.json).
2. Request Connection: In the Known Devices panel, clicking Connect sends a signed PairRequest packet over the mesh.
3. Incoming Consent Banner: An alert banner appears instantly on the target peer's screen displaying your Node ID with two options:
   • Accept: Instantly establishes the bi-directional encrypted tunnel and updates routing tables.
   • Decline: Rejects the pairing attempt; no session is created.
4. Forget Device: Clicking Forget immediately deletes the peer from your trusted devices list and revokes future reconnection shortcuts.

Mesh Firewall & Granular Peer Permissions

GhostMesh includes a native peer-level access firewall. You can selectively enable or block capabilities for each saved machine:

• RDP Toggle: Enable or forbid Remote Desktop incoming sessions from this node.
• Drop Toggle: Permit or reject high-speed GhostDrop file streams.
• Temporary Session: Marks the peer as an ephemeral guest; the device authorization is automatically revoked when the connection terminates.

Presse-Papier Partagé (Clipboard Sync)

Seamlessly share copied text, code snippets, tokens, and URLs across machines without email or third-party web chats:

• 1-Click Send: In the active peers table, clicking Clip immediately pushes the contents of your local Windows clipboard to that peer.
• Auto-Sync Mode: Under System Preferences, toggling Clipboard Sync will automatically write incoming clipboard packets directly into the target machine's Windows clipboard with a discreet confirmation toast.
• Noise Encrypted: All clipboard data travels through packet type 0x0A, authenticated and encrypted end-to-end.

Passerelle Internet (Exit Node Gateway)

Route all non-mesh IPv4 Internet traffic through a designated remote GhostMesh node (similar to Tailscale Exit Nodes):

How it Works

• Enable on Host: On the machine you want to use as an exit gateway, check Exit Node Gateway: Allow remote mesh peers to route their Internet connection through this PC in System Preferences.
• Activate on Client: In the Active Peers table, click Exit Node. GhostMesh injects two high-priority /1 routes (0.0.0.0/1 and 128.0.0.0/1) into the Windows routing table, routing all outgoing web traffic through the encrypted virtual mesh IP (10.42.X.Y).
• 1-Click Deactivation: Clicking the active Exit: ON button immediately tears down the override routes and restores direct Internet connectivity.

GhostChat - End-to-End Encrypted P2P Messaging

GhostChat is a lightweight, zero-footprint instant messaging engine built right into GhostMesh:

• Noise Protocol Authenticated: Every message packet (0x09) is encrypted point-to-point with ChaCha20-Poly1305.
• Zero Disk Storage: Messages exist strictly in RAM during the active session. No central servers or databases log your exchanges.
• Quick 1-Click Launch: Click the Chat button on any active link to immediately share notes, URLs, or credentials.

Windows Remote Desktop (RDP) Integration

Take full remote control of your distant computers at up to 60 FPS without installing third-party proprietary software (such as TeamViewer, AnyDesk, or RustDesk). GhostMesh leverages native Windows Remote Desktop (mstsc.exe) operating directly over the encrypted mesh overlay:

1-Click Launch from Dashboard

In the Active Peers table of the GhostMesh GUI, each connected peer displays a Remote Desktop button. Clicking this button automatically spawns Windows mstsc.exe /v:10.42.X.Y targeting the remote machine's virtual mesh IP.

Prerequisites on the Remote Host

To accept incoming Remote Desktop connections on the remote computer:

1. Open Windows Settings > System > Remote Desktop.
2. Toggle Enable Remote Desktop to On.
3. Ensure the Windows account on the remote host has a password set. When mstsc prompts for credentials, simply enter that computer's Windows username and password.

QR Code Instant Pairing

GhostMesh includes native vector SVG QR Code generation. When inviting a peer, simply display the QR Code directly from the Invitation modal. Any companion device or smartphone can scan the code to instantly extract the pairing ticket without copying long text strings.

GhostDrop - Built-in P2P File Transfer with Resume & Folders

GhostDrop is GhostMesh's native all-in-one file transfer engine. Unlike cloud storage or local-only utilities like AirDrop, GhostDrop transfers files directly peer-to-peer across the internet at the maximum physical speed of your connection:

Key Capabilities

• Interrupted Transfer Resumption (Resume): If a network blip occurs during a large transfer (e.g. 50 GB), GhostDrop automatically negotiates byte offsets and continues right where it was paused without re-sending completed chunks.
• On-the-Fly Folder Zipping: Selecting an entire directory automatically compresses it on the fly into an archive, streams it to the remote peer, and cleans up temporary buffers.
• High-Speed Async Streaming: Utilizes 128 KB chunk buffers over TCP port 4243 with live MB/s telemetry and progress bars.

How it Works

1. Select a Connected Peer: Choose from the active peers listed in your mesh network.
2. Pick Any File or Folder: Drag and drop or browse for any file or folder. There is no file size limit.
3. Stream with GhostDrop: High-throughput asynchronous streaming sends encrypted 128 KB chunks directly to the recipient over port 4243.
4. Auto-Save to Transfers: The receiving peer automatically saves files to Downloads/GhostMesh-Transfers/ and displays real-time MB/s throughput.

Windows Autostart & Silent Systray Mode

Ensure your machine remains accessible for Remote Desktop or continuous folder synchronization without requiring manual application launch after every reboot:

• One-Click Startup Toggle: Located under the System Preferences section of the dashboard, checking the autostart option configures the native Windows Run registry key.
• Silent Background Launch: Windows launches GhostMesh with the --silent flag, suppressing window popups and keeping the engine running discreetly in the Windows notification area (system tray).

GhostSync - Continuous Folder Synchronization

GhostSync provides real-time folder synchronization similar to Syncthing, embedded directly into your GhostMesh daemon:

• Zero Configuration: Select a local folder to watch.
• Automated Change Detection: GhostSync periodically tracks filesystem changes and diffs file manifests.
• Peer Sync: Modifications are automatically synchronized in the background to connected mesh peers without user intervention.

CLI Reference

ghostmesh keygen                    # Generate a fresh cryptographic identity keypair
ghostmesh discover                  # Query STUN to resolve local NAT endpoint
ghostmesh invite [--port 4242] [--ip 10.42.0.1] # Generate ticket and wait for peer
ghostmesh join <ticket> [--ip 10.42.0.2]       # Join peer and negotiate UDP hole-punching
ghostmesh send <target> <file>      # Send file via GhostDrop P2P high-speed streaming
ghostmesh receive [--dir <path>]    # Receive files via GhostDrop listener daemon
ghostmesh up [--port 4242] [--ip 10.42.0.1]    # Run standalone background node

Firewalls & Troubleshooting

P2P direct connections rely on UDP traversal. If your nodes fail to connect, review the typical scenarios below:

1. Connecting Home to Work

• Work / University Firewalls: Most enterprise firewalls strictly drop unsolicited or arbitrary outbound UDP packets. To test from work, switch your machine to a mobile 4G/5G Wi-Fi hotspot where UDP and STUN are unrestricted.
• Residential Router Port Forwarding: At home, routers (Freebox, Livebox, SFR, Bouygues) drop unexpected inbound UDP. You can forward UDP port 4242 directly to your home PC's local IP in your box admin panel (192.168.1.1).

2. NAT Types & Symmetric NAT

UDP hole-punching succeeds with Cone NATs (Full Cone, Restricted Cone, Port-Restricted Cone). When a network uses Symmetric NAT (common in enterprise networks), external ports change randomly for each destination. For symmetric networks, a relay fallback (DERP / TURN) or port forwarding is required.