Overview

SSH Tunnel is OrbVPN's most resilient last-resort transport. When TLS-based protocols are fingerprinted and dropped by a censor, an SSH connection -- and especially its obfuscated variants -- often still slips through. The OrbMesh SSH service runs an embedded Ed25519 SSH server that allocates a tunnel IP per user and carries IP traffic over the SSH channel.

Four SSH Transports

The same /ssh/connect endpoint serves four transports, selected with the transport field:

ssh -- plain SSH on the listen port (default 2222).
ossh -- Obfuscated SSH: a ChaCha20 stream cipher keyed by Argon2id wraps the handshake so the stream carries no recognisable SSH banner. Runs on a dedicated OSSH port (default 2223).
ossh_ws -- OSSH carried inside a WebSocket at /api/v2/terminal, using a CDN cover domain as the TLS SNI while connecting directly to the server IP.
ossh_cdn -- OSSH routed through the Cloudflare CDN to /api/v2/terminal, so the connection is indistinguishable from ordinary HTTPS to a popular site.

When to Use SSH

Reach for SSH when WireGuard UDP, VLESS Reality, and OrbConnect have all been blocked -- typically in the harshest filtering conditions. Smart Connect places OSSH and OSSH-over-CDN late in the fallback chain for restricted regions precisely because they survive when nothing else does.

Connect (Client)

Registers the authenticated user with the SSH manager, allocates a tunnel IP, and returns everything the client needs to open the SSH (or OSSH) channel: the listen port, host key fingerprint, username, allocated IP, gateway, DNS, and -- when OSSH is enabled -- the OSSH port and obfuscation keyword.

POST/ssh/connect

Establish an SSH/OSSH tunnel and receive connection configuration

Authentication:Bearer Token

Device Token Required

Like all client-facing OrbMesh endpoints, /ssh/connect requires a device token from OrbNET's device authorization flow, not a user JWT. See the OrbMesh Authentication section.

Request Parameters

Parameter	Type	Required	Description
`transport`	string	Optional	Transport mode: "ssh" (plain), "ossh", "ossh_ws", or "ossh_cdn". May also be passed as the ?transport= query parameter. Defaults to "ssh".
`public_key`	string	Optional	The client's SSH public key (OpenSSH authorized_keys format). When provided, it is registered for public-key authentication. Optional.

Code Examples

# Plain SSH
curl -X POST https://198.51.100.1:8443/ssh/connect \
  -H "Authorization: Bearer DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transport": "ssh"}'

# Obfuscated SSH over CDN
curl -X POST https://198.51.100.1:8443/ssh/connect \
  -H "Authorization: Bearer DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transport": "ossh_cdn"}'

Response

200SSH tunnel registered successfully

{
  "success": true,
  "serverEndpoint": "198.51.100.1",
  "port": 2222,
  "hostKeyFingerprint": "SHA256:n4P5o7K2x...",
  "username": "10421",
  "allocatedIp": "10.12.0.42",
  "gateway": "10.12.0.1",
  "dns": ["8.8.8.8", "8.8.4.4"],
  "mtu": 1420,
  "transport": "ossh",
  "osshEnabled": true,
  "osshPort": 2223,
  "osshKeyword": "orbmesh-eastus-ossh-2026"
}

503SSH not enabled on this server

"SSH not enabled"

401Invalid or expired device token

"Unauthorized"

Response Fields

Field	Type	Description
`success`	boolean	Whether the SSH user was registered
`serverEndpoint`	string	Server hostname for the SSH connection
`port`	integer	SSH listen port (default 2222)
`hostKeyFingerprint`	string	SHA-256 fingerprint of the server's Ed25519 host key. Pin this to prevent man-in-the-middle attacks.
`username`	string	SSH username for this session (the user's numeric ID)
`allocatedIp`	string	Tunnel IP assigned to the client from the SSH subnet (10.12.0.0/24 by default)
`gateway`	string	Tunnel gateway IP address
`dns`	string[]	DNS servers to configure on the tunnel interface
`mtu`	integer	Tunnel MTU
`transport`	string	Echo of the requested transport (`ssh`, `ossh`, `ossh_ws`, `ossh_cdn`)
`osshEnabled`	boolean	Present and `true` when OSSH is available on this server
`osshPort`	integer	OSSH listen port (default 2223). Only present when OSSH is enabled.
`osshKeyword`	string	Per-server OSSH obfuscation secret, formatted `orbmesh-{region}-ossh-2026`. Only present when OSSH is enabled.
`wsPath`	string	WebSocket path `/api/v2/terminal`. Only present for `ossh_ws` and `ossh_cdn` transports.

OSSH Handshake Parameters

The OSSH obfuscation layer derives its keys with Argon2id (time=1, memory=64 MB, threads=4) from the osshKeyword, then encrypts the handshake with ChaCha20. After the SSH key-exchange completes (SSH_MSG_NEWKEYS), the obfuscation layer passes through and SSH's own encryption takes over. Clients must use the exact keyword returned here.

Disconnect (Client)

Terminates the user's SSH session, closes any active channels, releases the allocated tunnel IP, and reports the connection end to OrbNET.

POST/ssh/disconnect

Disconnect the SSH tunnel and release the allocated IP

Authentication:Bearer Token

Code Examples

curl -X POST https://198.51.100.1:8443/ssh/disconnect \
  -H "Authorization: Bearer DEVICE_TOKEN"

Response

200SSH session disconnected

{
  "success": true,
  "message": "SSH session disconnected"
}

Server Status

Returns the SSH service status, including whether OSSH is enabled, the listen ports, the host key fingerprint, and active session counts. No authentication is required, matching the other protocol /status endpoints.

GET/ssh/status

Get SSH service status, ports, and active session counts

Authentication:No Auth Required

Code Examples

curl -X GET https://198.51.100.1:8443/ssh/status

Response

200SSH service status (when enabled)

{
  "enabled": true,
  "running": true,
  "port": 2222,
  "osshEnabled": true,
  "osshPort": 2223,
  "hostKeyFingerprint": "SHA256:n4P5o7K2x...",
  "activeSessions": 12,
  "totalUsers": 38
}

200SSH service status (when disabled)

{
  "enabled": false
}

Response Fields

Field	Type	Description
`enabled`	boolean	Whether the SSH service is configured on this server
`running`	boolean	Whether the SSH listener is actively running
`port`	integer	SSH listen port (default 2222)
`osshEnabled`	boolean	Whether the OSSH obfuscation listener is enabled
`osshPort`	integer	OSSH listen port (default 2223)
`hostKeyFingerprint`	string	SHA-256 fingerprint of the server's Ed25519 host key
`activeSessions`	integer	Number of currently active SSH sessions
`totalUsers`	integer	Number of registered SSH users

Bridge & Generic Tunnel Support

SSH participates in OrbMesh's two cross-protocol facilities:

Bridge mode. Pass "protocol": "ssh" to /bridge/connect to register an SSH bridge session, then connect SSH to the entry (bridge) server, which relays to the exit server.
Generic tunnel. The /vpn/tunnel transport accepts ?type=ssh (or the X-VPN-Type: ssh header) to carry SSH IP traffic over the same multi-protocol HTTPS tunnel used by WireGuard and VLESS.

WireGuard -- WireGuard tunnel management
VLESS -- VLESS protocol endpoints
OrbConnect -- OrbConnect HTTPS-tunnel management
Bridge Mode -- Multi-hop bridge connections (supports protocol: ssh)
Smart Connect -- Automatic protocol/transport selection that places OSSH in restricted-region fallback chains

SSH Tunnel Endpoints

Overview

Four SSH Transports

When to Use SSH

Connect (Client)

Device Token Required

Request Parameters

Code Examples

Response

Response Fields

OSSH Handshake Parameters

Disconnect (Client)

Code Examples

Response

Server Status

Code Examples

Response

Response Fields

Bridge & Generic Tunnel Support

On this page

SSH Tunnel Endpoints

Overview

Four SSH Transports

When to Use SSH

Connect (Client)

Device Token Required

Request Parameters

Code Examples

Response

Response Fields

OSSH Handshake Parameters

Disconnect (Client)

Code Examples

Response

Server Status

Code Examples

Response

Response Fields

Bridge & Generic Tunnel Support

Related Endpoints

On this page