OrbMesh Server API Overview
VPN server protocol layer API for WireGuard, VLESS, OrbConnect, and SSH tunnels with bridge mode, Smart DNS, and local pairing.
OrbMesh Server API
The VPN protocol layer running on every OrbVPN server. Manages WireGuard, VLESS, OrbConnect, and SSH tunnels, Smart DNS resolution, protocol mimicry, bridge mode, and local device pairing -- the censorship-resistant engine behind OrbVPN, powering connections in Iran, Russia, and China.
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
OrbVPN's own HTTPS-tunnel protocol. CSTP/DTLS transport, FIPS 140-3 mode, CDN-fronting, split tunneling, and route configuration -- built to traverse enterprise firewalls and corporate networks.
SSH Tunnel
SSH-based VPN transport with OSSH obfuscation (ChaCha20 + Argon2id), OSSH-over-WebSocket, and OSSH-over-CDN variants. A resilient last-resort path where every other protocol is fingerprinted.
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 VLESS traffic as legitimate services. 10 mimicry profiles: Microsoft Teams, Google, Shaparak, Zoom, WeChat, and more.
Bridge Discovery
Server-to-server bridge discovery and live relay metrics. Inspect cached exit servers, force re-discovery, and monitor relay throughput and latency.
gRPC Services
374 high-performance gRPC RPCs. Tunnel state streaming, telemetry ingestion, port forwarding, static IP, 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
OrbVPN's own HTTPS-tunnel protocol with CSTP and DTLS transport, FIPS 140-3 mode, and CDN-fronting. Built to traverse enterprise firewalls and corporate networks. Supports split tunneling and granular route control.
SSH Tunnel
SSH-based VPN transport with OSSH obfuscation (ChaCha20 stream cipher keyed by Argon2id). OSSH-over-WebSocket and OSSH-over-CDN variants survive deep packet inspection where TLS-based protocols are fingerprinted and dropped.
WebSocket & CDN Tunnels
WireGuard-over-WebSocket transport at /wireguard/ws, plus CDN-fronting that wraps WireGuard, VLESS, OrbConnect, and OSSH inside ordinary HTTPS to Cloudflare. Defeats UDP blocking and protocol-based filtering.
Protocol Mimicry
OrbMesh disguises VLESS traffic so it appears to be a legitimate, allowed service -- defeating deep packet inspection (DPI) and protocol-based blocking. Mimicry shapes the Reality SNI, TLS fingerprint, and HTTP header patterns to match the target service. Ten profiles ship today, several tuned for specific censorship regimes.
| Mimicry Profile | Mimics | Best For |
|---|---|---|
| Teams | Microsoft Teams calls | Corporate networks where Teams is allowed |
| Google services traffic | Networks permitting Google | |
| Shaparak | Iranian banking gateway | Iran -- financial traffic is rarely blocked |
| DoH | DNS-over-HTTPS resolvers | Networks that allow encrypted DNS |
| Zoom | Zoom video conferencing | Education and enterprise networks |
| FaceTime | Apple FaceTime calls | Apple ecosystem environments |
| VK | VKontakte traffic | Russia -- domestic social traffic |
| Yandex | Yandex services | Russia -- domestic search/cloud |
| WeChat messaging | China -- ubiquitous, low suspicion | |
| HTTPS | Generic HTTPS to popular sites | General-purpose, low suspicion |
Mimicry Is a VLESS Transport Feature
Mimicry profiles shape the Reality / XTLS-Vision transport that VLESS uses by default. They are not a separate protocol -- you select VLESS, then apply a mimicry profile (directly or via Smart Connect) to make the encrypted tunnel look like one of these services on the wire.
Automatic Protocol Selection
The Smart Connect system automatically detects network restrictions and races protocol + transport + mimicry combinations, verifying that real traffic flows and the public IP actually changes before committing. See the Smart Connect API for details.
Quick Start
Connect to an OrbMesh server and establish a WireGuard tunnel. There is no /api/v1 prefix on OrbMesh server endpoints -- paths are mounted at the server root on port 8443.
/wireguard/connectEstablish a WireGuard tunnel and receive peer configuration
# Establish a WireGuard tunnel on the server
curl -X POST https://198.51.100.1:8443/wireguard/connect \
-H "Authorization: Bearer DEVICE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"publicKey": "CLIENT_PUBLIC_KEY_BASE64"
}'{
"success": true,
"publicKey": "CLIENT_PUBLIC_KEY_BASE64",
"serverPublicKey": "xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=",
"ip": "10.8.0.42/32",
"gateway": "10.8.0.1",
"serverEndpoint": "198.51.100.1:51820",
"dns": ["10.8.0.1", "1.1.1.1"],
"allowedIPs": ["0.0.0.0/0", "::/0"],
"mtu": 1420,
"keepalive": 25
}Full Tunnel Reference
See the WireGuard endpoints page for the complete request/response field reference, the WebSocket and HTTP tunnel transports, and bridge (multi-hop) mode via exitServerId.
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 OrbConnect HTTPS-tunnel session (CSTP/DTLS)
Establish an SSH/OSSH tunnel for DPI-resistant transport
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 72 REST endpoints and 374 gRPC RPCs for managing VPN tunnels across WireGuard, VLESS, OrbConnect, and SSH protocols -- with bridge mode, Smart DNS, and protocol mimicry -- on every OrbVPN server.