Home

Welcome to the Ghostlink Wiki

Welcome to the official developer and user documentation for Ghostlink. Ghostlink is a high-performance LAN fabric designed to turn spare local GPUs and CPU hosts into a unified, low-latency execution surface for large-model inference.

Use the navigation below or the sidebar to explore technical guides, deployment strategies, and architecture deep-dives.

---

📖 Documentation Directory

🚀 Getting Started

• Quickstart Guide: The fastest path to spin up your first cluster and launch Ghostlink Studio.
• Installation & Requirements: Hardware prerequisites (CPU, GPU, NPU) and environment variables setup.
• CLI Reference: Quick breakdown of core commands like serve, join, listen, and doctor.

🏗 Architecture & Core Primitives

• Architecture Overview: Deep dive into our zero-copy SPSC (Single-Producer Single-Consumer) ring buffers and backpressure handling.
• Network & Discovery Layer: How HMAC-SHA256 authenticated UDP discovery frames securely bind cluster nodes together.
• Layer Placement & Execution Planning: Understanding the greedy layer allocation engine across heterogeneous hardware.

🌐 Deployment & Operations

• Multi-Node Deployment Guide: Production staging, network autotuning, and routing across complex LAN fabrics.
• Security Model: Hardening your transport layer, rotating shared secrets, and configuring firewall policies.
• Troubleshooting & Diagnostics: Using cargo run -p ghost-link -- doctor to debug network connectivity and runtime drift.

---

📊 Expected Performance Baselines

When properly configured, Ghostlink achieves ultra-low overhead by choosing the optimal transport mode between nodes:

Transport Mode	Avg Throughput (tokens/s)	Avg P95 Latency (ms)	Target Context
In-Memory (Zero-Copy)	118,840.29	1.83 ms	Co-located processes / Same host
TCP Loopback (Optimized)	67,794.12	3.65 ms	Local containers & IPC bridges
LAN Fabric (10GbE / RDMA)	Varies	Varies	Distributed multi-node setups

⚠️ Note: Benchmarks are tracked continuously via scripts/flow_perf_snapshot.py. Ensure your runtime environment matches the baseline expectations before scaling out production gates.

---

🛠 CLI Command Cheatsheet

The ghost-link binary provides a unified command set for managing both localized nodes and cluster-wide environments:

# Launch the dark-themed desktop management GUI
cargo run -p ghost-link -- gui

# Start the OpenAI-compatible API server (/v1/chat/completions)
cargo run -p ghost-link -- serve

# Run unified environment & network troubleshooting checks
cargo run -p ghost-link -- doctor --network-probe --network-target 127.0.0.1:8003

# Profile local compute capability and recommend worker topologies
cargo run -p ghost-link -- probe