GhostWire
Documentation

Installation

GhostWire can be installed on Linux, via Docker, or built from source. Choose the method that works best for your environment.

Linux (Recommended)

# Clone the repository
git clone https://github.com/Phantomojo/GhostWire-secure-mesh-communication.git
cd GhostWire-secure-mesh-communication

# Run the installation script
./scripts/install.sh

# Start GhostWire
./scripts/ghostwire.sh start

# Open the dashboard
http://localhost:8080

Docker

# Clone and run
git clone https://github.com/Phantomojo/GhostWire-secure-mesh-communication.git
cd GhostWire-secure-mesh-communication
docker-compose up -d

# Check health
curl http://localhost:9000/api/v2/health
{"status":"healthy","version":"0.1.0"}

From Source

# Prerequisites: Rust 1.75+, Node 18+
git clone https://github.com/Phantomojo/GhostWire-secure-mesh-communication.git
cd GhostWire-secure-mesh-communication/ghostwire

# Build the backend
cargo build --release

# Build the frontend
cd ../webui-src && npm install && npm run build

# Run
cargo run --release

For detailed installation instructions, see docs/INSTALL.md on GitHub.

Architecture

GhostWire is a decentralized mesh communication platform built in Rust with a React web dashboard. The system is designed for resilience, security, and adaptability.

Core Modules

• crypto_machine: AES-256-GCM encryption, Ed25519 signatures, X25519 key exchange. The cryptographic heart of GhostWire.
• libp2p networking: Kademlia DHT for peer discovery, Gossipsub for pub/sub messaging, QUIC and TCP transports.
• AI integration: LightGBM anomaly detection (ONNX Runtime) and GNN routing model for intelligent mesh management.
• Axum HTTP API: RESTful endpoints for dashboard, health checks, peer management, and mesh statistics.
• TrustStore: Distributed reputation system for Sybil resistance and node behavior tracking.
• DTN (Delay-Tolerant Networking): Message queuing and store-and-forward for offline-capable communication.

Data Flow

Messages are encrypted locally with AES-256-GCM, routed through the libp2p mesh via Kademlia DHT, monitored by the LightGBM anomaly detector, and delivered to the destination node. If the destination is offline, messages are queued in the DTN layer for later delivery.

Technology Stack

• Backend: Rust, libp2p, Axum, Tokio, ONNX Runtime
• Frontend: React, TypeScript, Canvas API for mesh visualization
• AI/ML: LightGBM, PyTorch GNN, GuifiSants dataset
• Transports: WiFi Direct, Bluetooth LE, LoRa, WebRTC, TCP/IP, Reticulum, Briar

API Reference

GhostWire exposes a RESTful HTTP API via Axum. The API is used by the web dashboard and can be accessed programmatically.

Base URL

http://localhost:9000/api/v2

Endpoints

• GET /health — Health check. Returns status and version.
• GET /peers — List all connected peers with status, latency, and reputation.
• GET /mesh/stats — Mesh network statistics: node count, message rate, queue depth.
• GET /mesh/topology — Current mesh topology as a graph structure.
• POST /message/send — Send a message to a peer (JSON body with recipient and content).
• GET /messages/inbox — Retrieve received messages.
• GET /identity/profiles — List all identity profiles on this node.
• POST /identity/create — Create a new identity profile.
• GET /anomaly/status — Current anomaly detection status and recent alerts.

For the complete API reference with request/response examples, see docs/API_QUICK_REFERENCE.md.

Contributing

GhostWire is open-source (AGPLv3) and actively seeking contributors. All skill levels welcome — from Rust experts to first-time open-source contributors.

Areas We Need Help

• Rust development: Core networking, cryptography, DTN layer, API endpoints.
• AI/ML: GNN model improvement, LightGBM retraining, new anomaly detection features.
• Frontend: React dashboard, mesh visualization, mobile responsiveness.
• Documentation: User guides, API docs, tutorials, translations.
• Security research: Code review, threat modeling, penetration testing.
• Testing: Unit tests, integration tests, mesh simulation testing.

How to Get Started

# 1. Fork the repository on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/GhostWire-secure-mesh-communication.git
cd GhostWire-secure-mesh-communication

# 3. Create a branch
git checkout -b feature/my-contribution

# 4. Make your changes and test
# 5. Commit and push
git commit -m "feat: add my contribution"
git push origin feature/my-contribution

# 6. Open a Pull Request on GitHub

Read the full contributing guide at docs/CONTRIBUTING.md.

Changelog

v0.1.0 — Current (April 2026)

• Initial release of GhostWire mesh communication platform.
• Rust core with libp2p networking, Kademlia DHT, Gossipsub pub/sub.
• AES-256-GCM encryption, Ed25519 signatures, X25519 key exchange.
• LightGBM anomaly detection (ONNX, 76.7μs inference).
• GNN routing model trained on GuifiSants dataset (7,931 samples).
• Axum HTTP API with health, peers, mesh stats endpoints.
• React web dashboard with real-time mesh visualization.
• Multi-profile identity support with QR code pairing.
• TrustStore reputation system for Sybil resistance.
• Delay-tolerant networking with message queuing.
• Docker support with docker-compose.

Planned

• ML-KEM-768 post-quantum key encapsulation integration.
• Windows, macOS, and Android builds.
• Tor integration for anonymity routing.
• Independent third-party security audit.
• Bug bounty program.

Full changelog at docs/CHANGELOG.md.

Code of Conduct

GhostWire is committed to providing a welcoming, safe, and harassment-free environment for all contributors regardless of background. Our full Code of Conduct is based on the Contributor Covenant.

Our Pledge

We pledge to make participation in our project and community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Expected Behavior

• Using welcoming and inclusive language.
• Being respectful of differing viewpoints and experiences.
• Gracefully accepting constructive criticism.
• Focusing on what is best for the community.
• Showing empathy towards other community members.

Unacceptable Behavior

• The use of sexualized language or imagery and unwelcome sexual attention or advances.
• Trolling, insulting/derogatory comments, and personal or political attacks.
• Public or private harassment.
• Publishing others' private information without explicit permission.

Reporting

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the team at mirungu015@proton.me. All complaints will be reviewed and investigated promptly and fairly.

Read the full Code of Conduct at docs/CODE_OF_CONDUCT.md.