Customize Nucleus Server

OmniEdge v2.x includes built-in nucleus mode that allows you to run your own signaling and relay server. This is ideal for air-gapped environments, low-latency requirements, or compliance needs.

Operating Modes

OmniEdge CLI supports three operating modes:

Quick Start

Nucleus Mode (Signaling Server Only)

Run a dedicated signaling server that helps other nodes connect:

# Start nucleus server on port 51821 with a secret
sudo omniedge start --mode nucleus --port 51821 --secret "YourSecretMin16Chars"

Requirements:

• Secret must be at least 16 characters
• Port must be accessible from your edge devices (UDP)
• No authentication required (nucleus doesn't join networks)

Dual Mode (Hub + Client)

Run a node that both participates in the mesh AND acts as a signaling server:

# Start as both VPN client and nucleus server
sudo omniedge start -n <network_id> --mode dual --secret "YourSecretMin16Chars"

This is useful for a central gateway or hub node in your network.

Edge Mode (Default)

Regular VPN client that connects to your nucleus server:

# Connect to a network (uses configured nucleus)
sudo omniedge start -n <network_id>

Self-Hosted / Air-Gapped Deployment

For completely offline environments with no cloud dependency:

Step 1: Set Up Nucleus Server

On your central server (e.g., lab gateway with static IP):

sudo omniedge start --mode nucleus --port 51821 --secret "LabSecret2026!"

Step 2: Configure Edge Devices

Edge devices discover each other through your nucleus server. Configure via the dashboard or use the API to point devices to your custom nucleus.

Step 3: Connect Edge Devices

On each edge device:

sudo omniedge start -n <network_id>

Use Cases

Secure Research Environments

Run nucleus in an isolated network segment for sensitive research projects. All signaling stays within your infrastructure.

Industrial Robotics

Deploy nucleus on a local gateway for robot fleet management. Minimal latency for real-time control applications.

Defense and Government

Meet compliance requirements by keeping all traffic and signaling within controlled infrastructure.

Privacy-Critical Deployments

No data touches OmniEdge cloud servers. Complete control over your mesh network.

Why Run Your Own Nucleus?

1. Lower Latency

Default public servers may be geographically distant from your devices. A local nucleus reduces signaling latency, especially important for:

• Real-time robot control
• Industrial automation
• Time-sensitive applications

2. Air-Gapped Networks

For networks that cannot connect to the internet:

• Research labs
• Classified environments
• Industrial control systems

3. Compliance Requirements

Keep all network coordination within your infrastructure:

• Data sovereignty requirements
• Industry regulations (HIPAA, SOC2, etc.)
• Internal security policies

4. Full Control

You control:

• Server location and resources
• Network policies
• Access logs and monitoring
• Uptime and maintenance schedules

Command Reference

# Nucleus mode options
omniedge start --mode nucleus [OPTIONS]

Options:
  --port <PORT>      UDP port for signaling (default: 51820)
  --secret <SECRET>  Cluster secret (minimum 16 characters, required)
  -v, --verbose      Enable verbose logging

# Dual mode options
omniedge start --mode dual [OPTIONS]

Options:
  -n, --network-id <ID>  Virtual network to join (required)
  --secret <SECRET>      Cluster secret (minimum 16 characters, required)
  --port <PORT>          UDP port for signaling (default: 51820)

Network Requirements

Ensure your firewall allows:

• Inbound UDP on the nucleus port from edge devices
• Outbound UDP from edge devices to nucleus

Docker Deployment

You can also run nucleus in a Docker container using the official omniedge-docker image:

# Nucleus mode (signaling server)
docker run -d --name omniedge-nucleus \
  --network host \
  --restart unless-stopped \
  omniedge/omniedge:latest \
  nucleus --secret "YourSecretMin16Chars" --port 51821

For edge mode (VPN client):

docker run -d --name omniedge \
  --privileged --network host \
  -v /dev/net/tun:/dev/net/tun \
  omniedge/omniedge:latest \
  edge -n <network-id> -s <security-key>

For dual mode (VPN + signaling):

docker run -d --name omniedge-dual \
  --privileged --network host \
  -v /dev/net/tun:/dev/net/tun \
  omniedge/omniedge:latest \
  dual -n <network-id> -s <security-key> --secret "YourSecretMin16Chars"

Docker Compose

# Nucleus mode
OMNIEDGE_SECRET=YourSecretMin16Chars docker compose up omniedge-nucleus -d

# Edge mode
OMNIEDGE_NETWORK_ID=<id> OMNIEDGE_SECURITY_KEY=<key> docker compose up omniedge-edge -d

# Dual mode
OMNIEDGE_NETWORK_ID=<id> OMNIEDGE_SECURITY_KEY=<key> OMNIEDGE_SECRET=<secret> docker compose up omniedge-dual -d

See omniedge-docker for the full docker-compose.yml and more options.

Note: --network host is required for proper UDP networking. Edge/dual modes require --privileged and access to /dev/net/tun.

Migration from v1.x Supernode

If you were using the legacy Docker supernode from v1.x:

The v2.x nucleus is built directly into the CLI binary - no separate Docker image required (though Docker deployment is still supported).

Troubleshooting

"Secret must be at least 16 characters"

The secret is used for encrypted signaling. Use a strong secret:

# Generate a random secret
openssl rand -base64 24

Edge devices can't connect to nucleus

1. Check firewall allows UDP on your nucleus port
2. Verify nucleus is running: omniedge status or ps aux | grep omniedge
3. Check network connectivity: nc -uvz <nucleus_ip> 51821

High latency between peers

If peers are connecting through relay when they could connect directly:

1. Ensure both peers have outbound UDP access
2. Check NAT traversal settings: omniedge config show
3. Try enabling port mapping: omniedge config portmap on

If you have more questions, feel free to discuss.