OrbMesh Server API Overview
VPN server protocol layer API for WireGuard, VLESS, and OrbConnect tunnels.
OrbMesh Server API
The VPN protocol layer running on every OrbVPN server. Manages WireGuard, VLESS, and OrbConnect tunnels, Smart DNS resolution, protocol mimicry, bridge mode, and local device pairing -- all powered by a high-performance Gin framework backend.
Base URL
OrbMesh runs independently on each VPN server. The base URL is the server's IP address on port 8443.
| Protocol | Base URL | Description |
|---|---|---|
| REST | https://{server-ip}:8443 | Per-server REST API endpoints |
| gRPC | grpc://{server-ip}:50052 | Per-server gRPC services |
| WebSocket | wss://{server-ip}:8443/ws/tunnel | WireGuard WebSocket tunnel |
Server Discovery
Server IPs and connection details are obtained from the OrbNET Servers API. You never need to hardcode server addresses -- query OrbNET first, then connect to the returned server endpoint.
Authentication
OrbMesh endpoints require a device token obtained through OrbNET's device authorization flow. This token proves that the connecting device has an active subscription and is authorized to use VPN services.
Authorization: Bearer DEVICE_TOKEN_FROM_ORBNETDevice Tokens vs. User Tokens
OrbMesh uses device tokens, not user JWT tokens. Device tokens are issued by OrbNET during device registration and contain server-specific authorization claims. See the Devices API for the device authorization flow.
API Categories
Health & Monitoring
Server health checks, readiness probes, and liveness endpoints. Used by load balancers and orchestration systems.
WireGuard
WireGuard tunnel management. Peer creation, key exchange, handshake monitoring, and WebSocket tunnel transport.
VLESS
VLESS protocol endpoints. Connection establishment, transport configuration (TCP, WebSocket, gRPC), and XTLS support.
OrbConnect
OpenConnect-compatible tunnel management. DTLS and TLS transport, split tunneling rules, and route configuration.
Smart DNS
On-server DNS resolution. Domain-based routing, streaming service unblocking, and DNS-over-HTTPS configuration.
Smart Connect
Intelligent server recommendations, latency telemetry, server load reporting, and optimal protocol selection.
Bridge Mode
Multi-hop bridge configuration. Entry/exit node setup, relay chaining, and obfuscated bridge transport.
Local Pairing
LAN device discovery via mDNS. Local network pairing, peer-to-peer tunneling, and nearby device mesh formation.
Protocol Mimicry
Disguise VPN traffic as legitimate services. 9 protocol profiles: Microsoft Teams, Google Meet, Shaparak, and more.
gRPC Services
370+ high-performance gRPC RPCs. Tunnel state streaming, telemetry ingestion, and bulk peer operations.
Protocol Support
OrbMesh supports multiple VPN protocols, each optimized for different network conditions and use cases.
WireGuard
Modern, high-performance VPN protocol with state-of-the-art cryptography. UDP-based with minimal overhead. Default protocol for most connections. Supports WebSocket transport for restrictive networks.
VLESS
Lightweight proxy protocol with minimal overhead. Supports multiple transports (TCP, WebSocket, gRPC) and XTLS for zero-copy encryption. Ideal for environments where WireGuard UDP is blocked.
OrbConnect
OpenConnect-compatible protocol with DTLS and TLS transport. Widely compatible with enterprise firewalls and corporate networks. Supports split tunneling and granular route control.
WebSocket Tunnel
WireGuard-over-WebSocket transport available at /ws/tunnel. Encapsulates WireGuard packets in WebSocket frames to traverse HTTP proxies and restrictive firewalls that block UDP traffic.
Protocol Mimicry
OrbMesh can disguise VPN traffic to appear as legitimate service traffic, bypassing deep packet inspection (DPI) and protocol-based blocking.
| Disguise Profile | Mimics | Use Case |
|---|---|---|
| Microsoft Teams | Teams video/audio calls | Corporate networks with Teams allowed |
| Google Meet | Meet video conferencing | Networks permitting Google services |
| Shaparak | Iranian banking gateway | Networks allowing financial traffic |
| Cloudflare | Cloudflare CDN traffic | General-purpose, low suspicion |
| Amazon AWS | AWS API traffic | Cloud-friendly networks |
| Apple iCloud | iCloud sync traffic | Apple ecosystem environments |
| Telegram MTProto | Telegram messaging | Regions with Telegram access |
| WhatsApp calls/messages | Networks permitting WhatsApp | |
| Custom | User-defined TLS fingerprint | Advanced users and custom deployments |
Automatic Protocol Selection
The Smart Connect system can automatically detect network restrictions and select the optimal protocol and mimicry profile. See the Smart Connect API for details.
Quick Start
Connect to an OrbMesh server and establish a WireGuard tunnel.
/api/v1/wireguard/peerCreate a new WireGuard peer and receive tunnel configuration
# Step 1: Create a WireGuard peer on the server
curl -X POST https://198.51.100.1:8443/api/v1/wireguard/peer \
-H "Authorization: Bearer DEVICE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"publicKey": "CLIENT_PUBLIC_KEY_BASE64",
"deviceId": "dev_abc123"
}'{
"success": true,
"data": {
"serverPublicKey": "SERVER_PUBLIC_KEY_BASE64",
"endpoint": "198.51.100.1:51820",
"allowedIPs": "10.8.0.42/32",
"dns": ["10.8.0.1"],
"keepalive": 25,
"mtu": 1420
}
}Key Endpoints
Server health, readiness, and liveness probes
Establish a new WireGuard tunnel with key exchange
Establish a VLESS tunnel with transport selection
Create an OpenConnect-compatible tunnel session
Set up domain-based DNS routing on the server
Report latency and receive optimal server recommendations
Configure multi-hop bridge relay with entry/exit nodes
Activate traffic disguise with a specific protocol profile
Architecture
Discover Servers via OrbNET
Query the OrbNET Servers API to get a list of available VPN servers with their IP addresses, load, and supported protocols.
Authorize Device
Register your device with OrbNET and receive a device token that grants access to OrbMesh server endpoints.
Connect to OrbMesh
Use the device token to authenticate with the OrbMesh API on the target server. Create a tunnel peer and receive your connection configuration.
Establish Tunnel
Use the returned configuration to establish a WireGuard, VLESS, or OrbConnect tunnel directly to the server. Traffic flows through the encrypted tunnel.
Ready to Connect?
Explore 68 REST endpoints and 370+ gRPC RPCs for managing VPN tunnels across WireGuard, VLESS, and OrbConnect protocols on every OrbVPN server.