Skip to content

omniedgeio/OmniNervous

BranchesTags

Repository files navigation

OmniNervous: High-Performance P2P VPN for AI & Robotics

Important

OmniNervous is an open-source, high-performance P2P VPN daemon built in Rust. It provides secure mesh networking with sub-millisecond latency using a signaling protocol and WireGuard data plane.

Architecture

OmniNervous uses a dual-plane design: control plane for signaling and peer management, data plane using WireGuard for encrypted tunnels. Linux builds can enable an L2 data plane for TAP-based bridging and L2 VPNs.

Performance Results (Feb 8, 2026)

Validated on AWS Lightsail $5 Instances (3-node cluster, cross-region: us-east-1 and us-east-2):

Metric Result Notes
Throughput (IPv4) 662.38 Mbps 147.6% of baseline
Throughput (IPv6) 632.25 Mbps Dual-stack VPN support
Latency 46.63 ms Cross-region (ping)
Baseline 448.59 Mbps Raw iperf3 performance
Efficiency 147.6% Protocol acceleration & zero-copy

Key Achievement: Feb 8 tests demonstrated record-breaking efficiency. v0.8.3 achieves 147.6% efficiency through zero-copy packet transmission and optimized UDP pipelines, outperforming raw baseline throughput.

Scalability & Capacity (Theoretically)

OmniNervous is optimized for extreme efficiency, allowing for a lightweight signaling footprint and high-speed data plane.

🔌 Nucleus (Signaling Server)

Validated on a $5 AWS Lightsail (1 vCPU, 1 GB RAM):

  • Peer Capacity: 10,000+ total registered nodes.
  • Cluster Capacity: Optimized for 2,000 nodes per cluster.
  • Efficiency: Delta-update protocol ensures each heartbeat uses < 1KB of bandwidth.
  • Throughput: Zero data plane overhead (Signaling-only).

🛰️ Edge Node (P2P Client)

  • Userspace Mode: Recommended for up to 500 concurrent peers.
  • Kernel Mode: Recommended for 1,000+ high-performance peers.
  • Lookup Type: $O(1)$ routing table for encrypted packet dispatch.

Quick Start

Prerequisites

  • Rust: Stable 1.74+
  • Linux Kernel: 5.6+ (for Kernel Mode) OR TUN/TAP support (for Userspace Mode)
  • WireGuard Tools: wg and wg-quick (Optional for Userspace Mode)

Build

# Native build
cargo build --release

# Enable L2 VPN (Linux only)
cargo build --release --features l2-vpn

# Docker-based build (Linux AMD64)
# This handles local dependencies (e.g. patched boringtun)
./scripts/build_local_docker.ps1  # Windows
./scripts/build_local_docker.sh   # Linux/macOS

The build script will produce a binary at: scripts/omninervous-linux-amd64

Usage

Initialize Identity:

./target/release/omninervous --init

Run Nucleus (Signaling Server):

sudo ./target/release/omninervous --mode nucleus --port 51820

Run Edge Node:

sudo ./target/release/omninervous \
  --nucleus <nucleus-host>:51820 \
  --cluster <cluster-name> \
  --vip 10.200.0.1 \
  --userspace  # Recommended for non-root/non-kernel setups

Run Edge Node (L2, Linux only):

sudo ./target/release/omninervous \
  --nucleus <nucleus-host>:51820 \
  --cluster <cluster-name> \
  --vip 10.200.0.1 \
  --transport-mode l2

Advanced Options:

  • STUN servers: --stun stun.l.google.com:19302
  • Multiple STUN: --stun "server1 server2" or --stun '["server1", "server2"]'
  • Cluster secret: --secret <16-char-min>
  • Config file: --config config.toml
  • Transport mode: --transport-mode l2 (Linux only, requires l2-vpn feature)
Flag Description Default
--mode nucleus Run as signaling server Edge mode
--nucleus Nucleus address (host:port) Required
--cluster Cluster name Required
--vip Virtual IP (e.g., 10.200.0.1) Required
--vip6 IPv6 Virtual IP (e.g., fd00::1) Optional
--port UDP port 51820
--userspace Use BoringTun userspace implementation Disabled (Kernel)
--stun STUN server(s) Built-in fallback
--secret Cluster PSK Optional
--init Generate identity -
--config Path to config file -
--transport-mode Transport mode: "l3" (default) or "l2" (Linux-only, requires l2-vpn feature) l3
--l2-mtu Override L2 TAP MTU (Linux only, l2-vpn) 1400

L2 VPN (Linux, l2-vpn feature)

  • Mode: --transport-mode l2 uses a TAP device for Layer 2 bridging.
  • Encapsulation: L2 frames are encrypted and sent over the existing UDP/WireGuard path.
  • Fragmentation: Large frames are fragmented and reassembled (default MTU 1400).
  • Observability: L2 metrics are exposed via Prometheus /metrics.

Security Features

Feature Implementation
Identity X25519 keys stored with 0o600 permissions
Signaling Auth HMAC-SHA256 with cluster PSK
Encryption ChaCha20-Poly1305
Forward Secrecy Ephemeral key rotation per session
Peer Auth Cluster-based PSK validation

Current Status

  • Version: v0.8.3 (High-Efficiency Zero-Copy Release)
  • Performance: 662.38 Mbps throughput, 147.6% baseline efficiency
  • Features: Dual-stack IPv4/IPv6 P2P, Zero-copy transmission, Relay fallback, L2 transport mode (Linux), Prometheus metrics
  • Security: Input validation, DoS protection, CBOR size limits, XML injection prevention

Deployment Options

Docker Deployment

1. Build the image:

docker build -t omninervous:latest .

2. Deploy the nucleus (signaling server):

docker-compose up -d

This starts the signaling server on port 51820.

Testing with docker-compose: For a full test cluster (nucleus + 2 edges + tester), use docker-compose.test.yml:

docker-compose -f docker-compose.test.yml up -d

View logs:

docker-compose logs -f

Linux Binary Deployment

Build linux-amd64 binary:

./scripts/build_local_docker.sh

Output: scripts/omninervous-linux-amd64

Deploy to cloud instance:

./scripts/deploy_to_cloud.sh user@host

Manual deployment:

# Copy binary to server
scp scripts/omninervous-linux-amd64 user@server:/usr/local/bin/

# Run on server
sudo /usr/local/bin/omninervous --mode nucleus --port 51820

Configuration File

Create config.toml:

[daemon]
port = 51820
interface = "eth0"
log_level = "info"

[network]
nucleus = "nucleus.example.com:51820"
cluster = "my-network"
stun_servers = ["stun.l.google.com:19302"]
use_builtin_stun = true
# IPv6 dual-stack settings (v0.4.0+)
prefer_ipv6 = true
happy_eyeballs_delay_ms = 250

[security]
max_sessions_per_ip = 10
handshake_timeout_secs = 5
encrypt_signaling = true

[[peers]]
public_key = "abc123..."
endpoint = "192.168.1.100:51820"

Load with: omninervous --config config.toml

Cloud Testing

3-node test orchestration:

./scripts/cloud_test.sh \
  --nucleus 104.x.x.x \
  --node-a 54.x.x.x \
  --node-b 35.x.x.x \
  --ssh-key ~/.ssh/cloud.pem \
  --secret "my-secure-secret-16"

This deploys binaries, runs baseline iperf3 tests, establishes WireGuard tunnel, and reports throughput/latency metrics.

Directory Structure

OmniNervous/
├── Cargo.toml                   # Workspace configuration
├── Dockerfile                   # Multi-stage Docker build
├── docker-compose.yml           # Nucleus deployment
├── docker-compose.test.yml     # 3-node test cluster
├── config.example.toml          # Configuration template
├── LICENSING.md                 # License information
├── README.md                    # Project documentation
├── RELEASE_NOTES.md             # Version changelog
├── crates/
│   └── daemon/
│       ├── Cargo.toml           # Package dependencies
│       └── src/
│           ├── config.rs        # TOML configuration
│           ├── handler.rs       # Message processing
│           ├── http.rs          # HTTP endpoints (/metrics, /health)
│           ├── identity.rs      # X25519 identity management
│           ├── main.rs          # Application entry point
│           ├── metrics.rs       # Prometheus metrics
│           ├── peers.rs         # Peer routing table
│           ├── signaling.rs     # Nucleus protocol implementation
│           ├── stun.rs          # STUN server fallback list
│           └── wg.rs            # WireGuard CLI integration
├── scripts/
│   ├── build_local_docker.sh    # Docker-based build tool
│   ├── build_local_docker.ps1   # PowerShell Docker build script
│   └── cloud_test.sh            # Cloud testing orchestrator
└── .github/
    └── workflows/               # CI/CD pipelines
        ├── build.yml            # Linux build and release
        └── test.yml             # Integration tests

Documentation

License

MIT / Apache 2.0 - See LICENSING.md

WireGuard is a registered trademark of Jason A. Donenfeld.

© 2026 OmniEdge Inc. Engineering the nervous system of the future.

About

OmniNervous: High-Performance P2P VPN for AI & Robotics

omniedge.io

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

4 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 39

OmniNervous v0.9.9 Latest
Feb 11, 2026
+ 38 releases

Packages

No packages published

Languages