VLESS Endpoints
VLESS protocol tunnel management including client connections, REALITY camouflage, and user provisioning on OrbMesh servers.
Connect (Client)
Establishes a VLESS tunnel connection. The server assigns a VLESS UUID and returns the connection parameters including REALITY camouflage settings for DPI evasion.
/vless/connectEstablish a VLESS tunnel connection with REALITY camouflage configuration
Device Token Required
This endpoint requires a device token obtained from OrbNET's device authorization flow. See the OrbMesh Authentication section for details.
When to Use VLESS
VLESS is ideal when WireGuard UDP traffic is blocked. It operates over TCP/TLS and uses REALITY to make the connection appear as legitimate HTTPS traffic to a well-known domain (e.g., www.microsoft.com), making it highly resistant to deep packet inspection.
Code Examples
curl -X POST https://198.51.100.1:8443/vless/connect \
-H "Authorization: Bearer DEVICE_TOKEN" \
-H "Content-Type: application/json"Response
{
"success": true,
"vlessUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"serverEndpoint": "198.51.100.1",
"serverPort": 8443,
"realityPublicKey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0K...",
"realitySNI": "www.microsoft.com"
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or expired device token"
}
}Response Fields
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the connection was established |
vlessUuid | string | Assigned VLESS UUID for this session. Use this as the user ID in your VLESS client configuration. |
serverEndpoint | string | Server IP address or hostname |
serverPort | integer | Server port (default 8443) |
realityPublicKey | string | REALITY public key for TLS camouflage. Used by the client to establish the REALITY handshake. |
realitySNI | string | Server Name Indication value for REALITY. The connection appears as HTTPS traffic to this domain. |
REALITY Camouflage
REALITY is an advanced TLS camouflage technology. When a DPI system inspects the connection, it sees a valid TLS handshake to www.microsoft.com (or another configured SNI). The actual VPN traffic is indistinguishable from legitimate HTTPS. This makes VLESS+REALITY one of the most censorship-resistant protocols available.
Disconnect (Client)
Terminates an active VLESS connection and removes the user session from the server.
/vless/disconnectDisconnect the current VLESS tunnel and clean up the session
Code Examples
curl -X POST https://198.51.100.1:8443/vless/disconnect \
-H "Authorization: Bearer DEVICE_TOKEN"Response
{
"success": true,
"message": "Disconnected successfully"
}Server Status (Internal)
Returns the current VLESS service status, including whether REALITY is enabled and the active user count. Used by OrbNET for monitoring.
/vless/statusGet VLESS server status including REALITY state and user count
Internal Endpoint
This endpoint is called by OrbNET for server monitoring and orchestration. It is not intended for client applications. Access requires an internal API key.
Code Examples
curl -X GET https://198.51.100.1:8443/vless/status \
-H "X-API-Key: INTERNAL_API_KEY"Response
{
"success": true,
"enabled": true,
"running": true,
"publicKey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0K...",
"userCount": 37,
"endpoint": "198.51.100.1:8443"
}VLESS TCP Tunnel
Establishes the raw VLESS TCP tunnel for data transport. This endpoint handles the actual VLESS protocol data flow after a connection has been established via /vless/connect.
/vless/tunnelVLESS TCP tunnel for data transport with optional bridge relay
Dual Authentication
This endpoint accepts both JWT bearer tokens (for client connections) and API keys (for bridge server-to-server relay). When a bridge server forwards traffic from its entry node to this exit server, it authenticates with an API key.
Code Examples
# Client connection (JWT auth)
curl -X POST https://198.51.100.1:8443/vless/tunnel \
-H "Authorization: Bearer DEVICE_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @vless_payload.bin
# Bridge relay (API key auth)
curl -X POST https://198.51.100.1:8443/vless/tunnel \
-H "X-API-Key: BRIDGE_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary @relay_payload.binAdd User (Internal)
Provisions a VLESS user on the server. Called by OrbNET during user setup. Returns the assigned VLESS UUID.
/vless/add-userProvision a new VLESS user on the server (called by OrbNET)
Internal Management Endpoint
This endpoint is called exclusively by OrbNET for user lifecycle management. Client applications should use /vless/connect instead.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
userUuid | string | Required | The unique user identifier from OrbNET. |
email | string | Required | The user's email address for identification and logging. |
Code Examples
curl -X POST https://198.51.100.1:8443/vless/add-user \
-H "X-API-Key: INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"userUuid": "usr_abc123",
"email": "user@example.com"
}'Response
{
"success": true,
"vlessUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}Remove User (Internal)
Removes a VLESS user from the server and terminates any active sessions. Called by OrbNET during user cleanup.
/vless/remove-userRemove a VLESS user from the server (called by OrbNET)
Internal Management Endpoint
This endpoint is called exclusively by OrbNET. Client applications should use /vless/disconnect instead.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
userUuid | string | Required | The unique user identifier whose VLESS account should be removed. |
Code Examples
curl -X POST https://198.51.100.1:8443/vless/remove-user \
-H "X-API-Key: INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"userUuid": "usr_abc123"
}'Response
{
"success": true,
"message": "User removed successfully"
}Related Endpoints
- Health & Monitoring -- Server health and protocol status
- WireGuard -- WireGuard tunnel management
- OrbConnect -- OrbConnect tunnel management
- Bridge Mode -- Multi-hop bridge connections
- Protocol Mimicry -- Traffic disguise profiles