https://github.com/omniedgeio/omniedge
Bringing intranet on the internet with Zero-Config Mesh VPNs.
https://github.com/omniedgeio/omniedge
industrial-iot mesh-networks omninervous wireguard
Last synced: 4 months ago
JSON representation
Bringing intranet on the internet with Zero-Config Mesh VPNs.
- Host: GitHub
- URL: https://github.com/omniedgeio/omniedge
- Owner: omniedgeio
- License: apache-2.0
- Created: 2022-06-26T03:23:32.000Z (almost 4 years ago)
- Default Branch: dev
- Last Pushed: 2026-02-11T04:32:27.000Z (4 months ago)
- Last Synced: 2026-02-11T06:54:41.043Z (4 months ago)
- Topics: industrial-iot, mesh-networks, omninervous, wireguard
- Language: Rust
- Homepage: https://connect.omniedge.io
- Size: 49.8 MB
- Stars: 882
- Watchers: 16
- Forks: 54
- Open Issues: 33
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- my-awesome - omniedgeio/omniedge - iot,mesh-networks,omninervous,wireguard pushed_at:2026-02 star:0.9k fork:0.1k Bringing intranet on the internet with Zero-Config Mesh VPNs. (Rust)
README
# OmniEdge
> Zero-Config P2P Mesh VPN for AI, Robotics, and Edge Computing
[](https://github.com/omniedgeio/omniedge/releases)
[](https://github.com/omniedgeio/omniedge/actions/workflows/release.yml)
[](https://github.com/omniedgeio/omniedge/actions/workflows/desktop-release.yml)
[](https://github.com/omniedgeio/omniedge/actions/workflows/e2e.yml)
[](LICENSE)
[](https://www.rust-lang.org/)
[](https://tauri.app/)
[](https://github.com/omniedgeio/OmniNervous)
[](#supported-platforms)
[](https://discord.gg/d4faRPYj)
## The Problem
Building distributed AI systems is hard. Connecting robots, edge devices, and cloud infrastructure across networks is even harder:
- Your robot fleet can't communicate behind NAT
- Federated learning nodes need secure, low-latency links
- Remote debugging AI devices requires complex VPN setup
- Multi-agent systems need peer discovery without central servers
- Humanoid robot teleoperation demands deterministic, jitter-free networking
**OmniEdge solves this with a single binary.**
## Why Researchers & Developers Choose OmniEdge
| Challenge | OmniEdge Solution |
| ----------------------------- | ------------------------------------------------------ |
| NAT traversal | Automatic hole punching + relay fallback, 99%+ success |
| Symmetric NAT | Zero-knowledge relay for hardest NAT types |
| Latency-critical AI inference | WireGuard encryption, ~0.3ms overhead |
| Deterministic networking | 6-Sigma stability (Cpk 2.92) for teleoperation |
| Secure model transfer | End-to-end encrypted mesh |
| Heterogeneous devices | Single binary for x86, ARM64, RISC-V |
| Air-gapped labs | Self-hosted nucleus mode (no cloud dependency) |
## Performance: Industrial-Grade Stability
Validated through [50-run longitudinal testing](https://github.com/omniedgeio/OmniNervous/blob/main/Capability_test/cloud_test_50_run_paper.md) using Process Capability Analysis (Cpk):
| Metric | OmniEdge Tunnel | Raw Internet | Improvement |
| --------------------------- | ------------------ | ------------ | -------------------- |
| **Latency** | 54.69ms | 54.36ms | +0.3ms overhead |
| **Latency Stability (Cpk)** | **2.92 (6-Sigma)** | 6.47 | Near-deterministic |
| **Throughput** | **484.7 Mbps** | 344.1 Mbps | **+140.8%** |
| **Jitter (StdDev)** | 0.057ms | 0.026ms | Bounded, predictable |
> **What this means**: Cpk > 2.0 indicates industrial-grade process capability. OmniEdge provides deterministic, jitter-controlled networking suitable for real-time robot control and latency-sensitive AI inference.
## Perfect For
### Robotics
- **Humanoid Teleoperation**: Deterministic latency for real-time control loops
- **Robot Swarms**: Mesh networking for multi-robot coordination
- **ROS 2 Integration**: Seamless DDS discovery across networks
- **Remote Debugging**: SSH into any robot without port forwarding
### AI & Machine Learning
- **Federated Learning**: Secure gradient exchange between edge nodes
- **Distributed Inference**: Split models across Jetson/Pi clusters
- **MLOps Pipelines**: Deploy models to edge devices seamlessly
- **GPU Cluster Access**: Connect to remote training infrastructure
### Research
- **Multi-Agent Systems**: P2P communication for agent coordination
- **Edge Computing**: Connect fog nodes to cloud transparently
- **IoT Testbeds**: Instant mesh for sensor networks
- **Reproducible Experiments**: Consistent networking across trials
## Quick Start (60 seconds)
```bash
# Install on any Linux device (Jetson, Pi, server)
curl -fsSL https://raw.githubusercontent.com/omniedgeio/omniedge/main/scripts/omniedge-install.sh | bash
# Start and connect (interactive login on first run)
sudo omniedge start
# That's it. Your devices can now reach each other by virtual IP.
```
## Nucleus Mode Custom Server
When running `omniedge start --mode nucleus` or `--mode dual`, the CLI can auto-register a custom user server using the public IP and chosen port. This requires an auth token; if auth is missing or public IP lookup fails, it skips registration and continues.
### OpenWrt Installation
```bash
# Download the package for your architecture (example: aarch64, OpenWrt 24.10)
wget https://github.com/omniedgeio/omniedge/releases/download/v2.6.0/omniedge_2.6.0_aarch64_generic.ipk
# Install the package
opkg install omniedge_2.6.0_aarch64_generic.ipk
# Configure via UCI
uci set omniedge.main.enabled='1'
uci set omniedge.main.network_id='your-network-id'
uci commit omniedge
# Start the service
/etc/init.d/omniedge start
/etc/init.d/omniedge enable # Start on boot
```
## Supported Hardware
| Device | Architecture | Status |
| -------------------------------- | ------------- | ------------ |
| NVIDIA Jetson (Nano/Xavier/Orin) | ARM64 | Tested |
| Raspberry Pi 4/5 | ARM64 | Tested |
| Intel NUC / x86 Servers | x86_64 | Tested |
| Apple Silicon (M1/M2/M3) | ARM64 | Tested |
| RISC-V Boards | riscv64 | Experimental |
| OpenWrt Routers | x86_64, ARM64 | Tested |
## Supported Platforms
### CLI (`omniedge-cli`)
| Platform | Architecture | Package Formats |
| ----------- | ------------------------------------- | -------------------------------------- |
| **Linux** | x86_64, ARM64, RISC-V | `.tar.gz`, `.deb`, `.rpm`, `.AppImage` |
| **macOS** | x86_64 (Intel), ARM64 (Apple Silicon) | `.tar.gz` |
| **Windows** | x86_64 | `.zip` |
### Desktop (`omniedge-desktop`)
| Platform | Architecture | Package Formats |
| ----------- | ------------- | ------------------- |
| **Windows** | x86_64 | `.msi`, `.exe` |
| **macOS** | x86_64, ARM64 | `.dmg` |
| **Linux** | x86_64 | `.deb`, `.AppImage` |
### OpenWrt (`omniedge-openwrt`)
| OpenWrt Version | Architecture | Package Format | Status |
| ------------------- | ------------ | -------------- | ------ |
| **24.10.x** | x86_64 | `.ipk` | Tested |
| **24.10.x** | aarch64 | `.ipk` | Tested |
| **25.x (snapshot)** | x86_64 | `.apk` | Tested |
| **25.x (snapshot)** | aarch64 | `.apk` | Tested |
> **Note**: MIPS architecture is not supported due to Rust toolchain limitations.
## Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ Your AI Network │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Jetson Orin │ │ Robot Fleet │ │ Cloud │ │
│ │ 10.147.1.1 │◄──►│ 10.147.1.x │◄──►│ 10.147.1.x │ │
│ │ ( Edges ) │ │ (Edges) │ │ (Edges) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └───────────────────┼───────────────────┘ │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ OmniEdge Mesh │ │
│ │ (WireGuard) │ │
│ │ │ │
│ │ - E2E Encrypted │ │
│ │ - NAT Traversal │ │
│ │ - Relay Fallback │ │
│ │ - 6σ Stability │ │
│ └───────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## Plugin System (v2.2.0)
OmniEdge now supports a **WASM-based plugin system** that allows extending functionality without modifying the core application.
### Features
| Feature | Description |
| ----------------------------- | -------------------------------------------------------- |
| **WASM Sandboxing** | Plugins run in secure WebAssembly sandboxes |
| **Event Hooks** | React to VPN state changes, peer events, network changes |
| **Capability-Based Security** | Fine-grained permissions per plugin |
| **Hot Reload** | Install, enable, disable plugins without restart |
| **Cross-Platform** | Single plugin binary works on all platforms |
### Plugin Capabilities
| Capability | Description |
| ----------------- | --------------------------- |
| `network-status` | Read VPN connection state |
| `peer-info` | Access peer list and status |
| `event-hooks` | Subscribe to VPN events |
| `http-client` | Make outbound HTTP requests |
| `key-value-store` | Persist plugin data |
| `notifications` | Show system notifications |
| `logging` | Write to application logs |
### Installing Plugins
```bash
# Via CLI (v2.2.0)
omniedge plugin list # List installed plugins
omniedge plugin install ./plugin.zip # Install from ZIP file
omniedge plugin uninstall # Remove a plugin
omniedge plugin enable # Enable a plugin
omniedge plugin disable # Disable a plugin
omniedge plugin info # Show plugin details
omniedge plugin reload # Reload a plugin
omniedge plugin discover # Discover plugins in directory
# Via Desktop UI
# Settings > Plugins > Install Plugin > Select .zip file
# Plugin directory
# Windows: %APPDATA%\OmniEdge\plugins\
# macOS: ~/Library/Application Support/OmniEdge/plugins/
# Linux: ~/.local/share/omniedge/plugins/
```
### Creating Plugins
See [examples/plugins/hello-world](examples/plugins/hello-world) for a complete example.
```rust
// Minimal plugin structure
wit_bindgen::generate!({
world: "omniedge-plugin",
exports: {
world: MyPlugin,
},
});
struct MyPlugin;
impl Guest for MyPlugin {
fn on_load() -> Result<(), String> {
Ok(())
}
}
```
## NAT Traversal (v2.1.0)
OmniEdge automatically handles complex network environments with multi-layer NAT traversal:
### How It Works
```
┌─────────────────────────────────────────────────────────────────┐
│ NAT Traversal Stack │
├─────────────────────────────────────────────────────────────────┤
│ 1. STUN Detection → Identify NAT type (Open/Cone/Symmetric) │
│ 2. UDP Hole Punching → Direct P2P for compatible NAT types │
│ 3. Port Mapping → UPnP/NAT-PMP to open router ports │
│ 4. Relay Fallback → Zero-knowledge relay for symmetric NAT │
└─────────────────────────────────────────────────────────────────┘
```
### NAT Type Compatibility
| Your NAT | Peer NAT | Connection Method |
| --------------- | -------------------- | --------------------- |
| Open/Full Cone | Any | Direct P2P |
| Restricted Cone | Open/Full/Restricted | Direct P2P |
| Port-Restricted | Open/Full Cone | Direct P2P |
| Symmetric | Open/Full Cone | Direct P2P (usually) |
| Symmetric | Symmetric | **Relay** (automatic) |
### Features
| Feature | Description |
| ----------------------- | -------------------------------------- |
| **Auto NAT Detection** | STUN-based detection on connection |
| **Relay Fallback** | Zero-knowledge relay for symmetric NAT |
| **Port Mapping** | UPnP/NAT-PMP/PCP support |
| **Encrypted Signaling** | X25519 + XSalsa20-Poly1305 |
| **IPv6 Dual-Stack** | Happy Eyeballs (RFC 8305) |
### Configuration
```bash
# Check your NAT type and settings
omniedge status
# Configure NAT traversal
omniedge config show # View current settings
omniedge config relay on # Enable relay fallback
omniedge config portmap on # Enable UPnP/NAT-PMP
omniedge config ipv6 prefer # Prefer IPv6 when faster
omniedge config encrypt on # Enable encrypted signaling
```
## Operating Modes
| Mode | Description | Use Case |
| ------------------ | --------------------- | ------------------------------ |
| **edge** (default) | VPN client | Connect devices to mesh |
| **nucleus** | Signaling server only | Self-hosted relay, no cloud |
| **dual** | VPN + signaling | Central hub + mesh participant |
```bash
# Edge mode - Join an existing network
sudo omniedge start -n
# Nucleus mode - Run your own signaling server (air-gapped labs)
sudo omniedge start --mode nucleus --port 51821 --secret "YourLabSecret123"
# Dual mode - Hub node that also participates in mesh
sudo omniedge start -n --mode dual --secret "YourSecret123456"
```
## Transport Modes (v2.5.0)
OmniEdge supports two transport modes for different networking requirements:
| Mode | Layer | Interface | Platforms | Use Case |
| ---------------- | ------------------ | --------- | ---------- | -------------------------- |
| **L3** (default) | IP (Layer 3) | TUN | All | Standard VPN, IP routing |
| **L2** | Ethernet (Layer 2) | TAP | Linux only | Bridging, non-IP protocols |
### L3 Mode (Default)
Layer 3 mode operates at the IP level, routing IP packets between peers. This is the default and works on all platforms.
```bash
# L3 mode (default - no flag needed)
sudo omniedge start -n
# Explicit L3 mode
sudo omniedge start -n --transport-mode l3
```
### L2 Mode (Linux Only)
Layer 2 mode operates at the Ethernet level, bridging Ethernet frames between peers. This enables:
- **Non-IP Protocols**: ARP, DHCP relay, NetBIOS, STP
- **MAC Address Visibility**: See actual MAC addresses across the mesh
- **VLAN Bridging**: Extend VLANs across sites
- **Legacy Protocol Support**: Protocols that don't use IP
```bash
# L2 mode (Linux only, requires l2-vpn feature)
sudo omniedge start -n --transport-mode l2
```
**Requirements**:
- Linux operating system (TAP devices require Linux kernel)
- Build with `--features l2-vpn` flag
**Note**: L2 mode is currently in preview. Full OmniNervous L2 module integration is in progress.
## SSH Integration (v2.7.0)
OmniEdge now includes a **built-in SSH server and client**, enabling secure remote access to any device in your mesh network without exposing ports to the internet.
### Features
| Feature | Description |
|---------|-------------|
| **Mesh SSH Client** | SSH to any peer by name or virtual IP |
| **Built-in SSH Server** | Accept SSH connections over the mesh |
| **SFTP Support** | Secure file transfer to/from peers |
| **SCP Support** | Copy files with familiar scp syntax |
| **Session Recording** | Record SSH sessions for audit/compliance |
| **Fleet Operations** | Execute commands across multiple nodes |
| **Emergency Access** | Break-glass mechanism for incident response |
| **Standalone Mode** | Run SSH server without OmniEdge backend |
### SSH Commands
```bash
# Connect to a peer (by name or virtual IP)
omniedge ssh user@my-robot # By peer name
omniedge ssh user@10.147.1.5 # By virtual IP
omniedge ssh -p 2222 user@peer # Custom port
# Execute remote commands
omniedge ssh user@peer "uptime"
omniedge ssh user@peer "systemctl status myservice"
# Interactive SFTP
omniedge sftp peer # Start SFTP session
# Copy files (SCP)
omniedge scp local.txt peer:/remote/path
omniedge scp peer:/remote/file.txt ./local/
omniedge scp -r ./folder peer:/path # Recursive copy
```
### Standalone SSH Server
Run an SSH server without the full OmniEdge backend - useful for testing, development, or lightweight deployments:
```bash
# Default: Private networks only (10.x, 172.16.x, 192.168.x)
omniedge ssh-server
# Accept from any IP (development/testing)
omniedge ssh-server --permissive
# Localhost only (127.0.0.0/8)
omniedge ssh-server --localhost-only
# Custom network allowlist
omniedge ssh-server --allow-network 192.168.1.0/24
# User mapping (map SSH user to local user)
omniedge ssh-server --user-map git:admin --default-user guest
# Custom port and host key
omniedge ssh-server -p 22 --host-key-path /etc/omniedge/host_key
```
### Use Cases
- **Remote Robot Debugging**: SSH into any robot in your fleet without port forwarding
- **Secure File Deployment**: Transfer ML models to edge devices via SFTP
- **Fleet Management**: Execute commands across all nodes simultaneously
- **Incident Response**: Emergency access with audit logging
- **Air-Gapped Operations**: Standalone SSH server for isolated networks
## Self-Hosted Mode (Air-Gapped Labs)
Run completely offline with no cloud dependency:
```bash
# On your central server (e.g., lab gateway)
sudo omniedge start --mode nucleus --port 51821 --secret "LabSecret2026!"
# On edge devices - they discover each other through your nucleus
# Configure network settings via the dashboard or API
```
**Use cases:**
- Secure research environments
- Industrial robotics with network isolation
- Defense and government applications
- Privacy-critical deployments
## CLI Reference
```bash
# Basic operations
omniedge start # Connect to first available network
omniedge start -n # Connect to specific network
omniedge status # Check connection status
omniedge stop # Disconnect
# Authentication
omniedge start -s # Non-interactive login (CI/CD)
# Exit node (route traffic through a peer)
omniedge start -x # Run as exit node
omniedge start -e # Use specific exit node
omniedge start --no-exit-node # Disable exit node
# NAT traversal configuration (v2.1.0)
omniedge config show # Show current network settings
omniedge config relay on|off # Enable/disable relay fallback
omniedge config relay server # Set custom relay server
omniedge config portmap on|off # Enable/disable UPnP/NAT-PMP
omniedge config ipv6 on|off|prefer # IPv6 settings
omniedge config encrypt on|off # Encrypted signaling
omniedge config reset # Reset to defaults
# Plugin management (v2.2.0)
omniedge plugin list # List installed plugins
omniedge plugin install # Install plugin from ZIP
omniedge plugin uninstall # Remove a plugin
omniedge plugin enable # Enable a plugin
omniedge plugin disable # Disable a plugin
omniedge plugin info # Show plugin details
omniedge plugin reload # Reload a plugin
omniedge plugin discover # Discover plugins in directory
# Version check and upgrade (v2.6.0)
omniedge version # Display version with commit hash
omniedge version --check # Check GitHub for updates
omniedge version --releases # Show recent release history
omniedge upgrade # Self-update to latest version
omniedge upgrade --check # Check only, don't install
omniedge upgrade --yes # Skip confirmation prompt
# SSH integration (v2.7.0)
omniedge ssh user@peer # SSH to peer by name or IP
omniedge ssh user@peer command # Execute remote command
omniedge sftp peer # Interactive SFTP session
omniedge scp file.txt peer:/path # Copy files to/from peers
omniedge ssh-server # Start standalone SSH server
omniedge ssh-server --permissive # Accept from any IP
# Advanced modes
omniedge start --mode nucleus --port 51821 --secret "..." # Signaling server
omniedge start --mode dual --secret "..." # Hub + client
```
## V2 Migration Notice
OmniEdge V2 is a complete rewrite in Rust, replacing the legacy Go/n2n implementation:
| Aspect | V1 (Legacy) | V2 (Current) |
| ---------- | ---------------------------------------------------------------- | ----------------------------- |
| Language | Go | Rust |
| Protocol | n2n | OmniNervous (WireGuard-based) |
| License | GPL-3.0 | Apache-2.0 / MIT |
| Repository | [omniedge-legacy](https://github.com/omniedgeio/omniedge-legacy) | This repository |
## Research & Citations
Using OmniEdge in your research? We'd love to hear about it.
```bibtex
@software{omniedge2026,
title = {OmniEdge: Zero-Config P2P Mesh VPN for Edge Computing},
author = {OmniEdge Team},
year = {2026},
url = {https://github.com/omniedgeio/omniedge},
note = {Industrial-grade stability (Cpk 2.92) validated through 50-run longitudinal testing}
}
```
### Related Publications
- [OmniNervous Protocol Stability Analysis](https://github.com/omniedgeio/OmniNervous/blob/main/Capability_test/cloud_test_50_run_paper.md) - 50-run Cpk validation study
## Built With
- **[Rust](https://www.rust-lang.org/)** - Memory safety, zero-cost abstractions
- **[WireGuard](https://www.wireguard.com/)** - Modern, audited cryptography
- **[OmniNervous](https://github.com/omniedgeio/OmniNervous)** - High-performance P2P daemon with NAT traversal
- STUN-based NAT detection
- Relay fallback for symmetric NAT
- UPnP/NAT-PMP/PCP port mapping
- Happy Eyeballs (RFC 8305) for IPv6
- **[Tauri](https://tauri.app/)** - Lightweight desktop apps
## Community
- [Discord](https://discord.gg/d4faRPYj) - Ask questions, share projects
- [GitHub Issues](https://github.com/omniedgeio/omniedge/issues) - Bug reports and feature requests
- [Twitter](https://twitter.com/omniedgeio) - Updates and announcements
## License
Dual-licensed under [Apache License 2.0](LICENSE-APACHE) and [MIT License](LICENSE-MIT).
Use freely in academic and commercial projects. See [LICENSING.md](LICENSING.md) for details.
---
**Built for the machines that build the future.**
[Website](https://connect.omniedge.io) | [Docs](https://connect.omniedge.io/docs) | [Discord](https://discord.gg/d4faRPYj) | [Twitter](https://twitter.com/omniedgeio)