Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Termix-SSH/Termix/llms.txt

Use this file to discover all available pages before exploring further.

The Tunnels API lets you establish and manage server-to-server (S2S) SSH tunnels and client-to-server (C2S) relay sessions. All tunnel operations require a valid JWT, which can be supplied as a jwt cookie or a Bearer token in the Authorization header. Tunnel connections are non-blocking: POST /ssh/tunnel/connect returns immediately and uses Server-Sent Events (SSE) or polling to track progress. A tunnel name uniquely identifies a tunnel and is constructed as {hostId}::{tunnelIndex}::{displayName}::{sourcePort}::{endpointHost}::{endpointPort}.

​
Get all tunnel statuses

Requires authentication via JWT cookie or Authorization: Bearer <token> header.
GET /ssh/tunnel/status Returns a snapshot of every tunnel’s current status, keyed by tunnel name.
​
[tunnelName]
object
Status object for a single tunnel.
cURL
curl -X GET https://your-termix-host/ssh/tunnel/status \
  -H "Authorization: Bearer <token>"

{
  "1::0::my-server::8080::endpoint-host::80": {
    "connected": true,
    "status": "connected"
  },
  "2::1::dev-db::5432::db-host::5432": {
    "connected": false,
    "status": "retrying",
    "retryCount": 1,
    "maxRetries": 3,
    "nextRetryIn": 4,
    "reason": "Connection refused"
  }
}

​
Stream tunnel status (SSE)

GET /ssh/tunnel/status/stream Opens a Server-Sent Events stream that emits a statuses event containing the full status snapshot whenever any tunnel changes state. A : keepalive comment is sent every 30 seconds to keep the connection alive.
Keep-alive is sent as an SSE comment, not an event. Standard SSE clients ignore it automatically.
The response Content-Type is text/event-stream. Each message has the form: 
event: statuses
data: {"tunnelName": {...}, ...}

​
Get tunnel status by name

GET /ssh/tunnel/status/:tunnelName
​
tunnelName
string
required
The fully-qualified tunnel name (e.g. 1::0::my-server::8080::endpoint::80).
​
name
string
The tunnel name.
​
status
object
Status object identical to the entry in the all-statuses response.
StatusMeaning
401Authentication required.
404Tunnel name not found in the status registry.
cURL
curl -X GET "https://your-termix-host/ssh/tunnel/status/1::0::myserver::8080::endpoint::80" \
  -H "Authorization: Bearer <token>"

​
Connect a tunnel

POST /ssh/tunnel/connect Enqueues an SSH tunnel connection. Returns immediately; track progress via the status stream or polling.
​
name
string
required
Tunnel name in {hostId}::{tunnelIndex}::{displayName}::{sourcePort}::{endpointHost}::{endpointPort} format.
​
sourceHostId
number
required
ID of the source SSH host in the Termix database.
​
tunnelIndex
number
Index of this tunnel in the host’s tunnel connection list.
​
sourceIP
string
required
IP address of the source host.
​
sourceSSHPort
number
required
SSH port of the source host.
​
sourceUsername
string
required
Username for the source host SSH connection.
​
endpointHost
string
required
Human-readable name or user@ip identifier of the endpoint host.
​
endpointPort
number
required
Port to expose on the endpoint host side.
​
sourcePort
number
required
Port to bind on the source host side.
​
mode
string
default:"remote"
Tunnel direction. One of local, remote, or dynamic.
​
maxRetries
number
default:"3"
Maximum number of reconnection attempts on failure.
​
retryInterval
number
default:"5000"
Milliseconds to wait between retry attempts.
​
autoStart
boolean
default:"false"
Whether this tunnel should reconnect automatically on server restart.
​
message
string
Confirmation message, always "Connection request received".
​
tunnelName
string
The tunnel name that was submitted.
StatusMeaning
400Missing or invalid tunnel configuration, or tunnel name does not match config fields.
401Authentication required.
403The authenticated user does not have read access to the source host.
500Internal error while enqueuing the connection (e.g. endpoint host could not be resolved).
cURL
curl -X POST https://your-termix-host/ssh/tunnel/connect \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "1::0::my-server::8080::endpoint-host::80",
    "sourceHostId": 1,
    "tunnelIndex": 0,
    "sourceIP": "192.168.1.10",
    "sourceSSHPort": 22,
    "sourceUsername": "ubuntu",
    "endpointHost": "endpoint-host",
    "endpointPort": 80,
    "sourcePort": 8080,
    "mode": "remote"
  }'

{
  "message": "Connection request received",
  "tunnelName": "1::0::my-server::8080::endpoint-host::80"
}

​
Disconnect a tunnel

POST /ssh/tunnel/disconnect Cleanly tears down an active tunnel connection. Sets the manualDisconnect flag so retries are suppressed.
​
tunnelName
string
required
Name of the tunnel to disconnect.
​
message
string
Confirmation message.
​
tunnelName
string
The tunnel name that was disconnected.
StatusMeaning
400tunnelName was not provided.
401Authentication required.
403User does not have access to the tunnel’s source host.
500Internal error during cleanup.
cURL
curl -X POST https://your-termix-host/ssh/tunnel/disconnect \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"tunnelName": "1::0::my-server::8080::endpoint-host::80"}'

​
Cancel a tunnel retry

POST /ssh/tunnel/cancel Cancels a pending retry sequence for a tunnel that is in the retrying or waiting state without retrying again.
​
tunnelName
string
required
Name of the tunnel whose retry should be cancelled.
​
message
string
Confirmation message.
​
tunnelName
string
The tunnel name.
StatusMeaning
400tunnelName was not provided.
401Authentication required.
403User does not have access to the tunnel’s source host.
500Internal error during cleanup.
cURL
curl -X POST https://your-termix-host/ssh/tunnel/cancel \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"tunnelName": "1::0::my-server::8080::endpoint-host::80"}'

​
C2S relay (WebSocket)

Client-to-server relay sessions are negotiated over WebSocket rather than HTTP. After upgrading the connection, send a JSON open or test message to establish the relay.

​
Open message

{
  "type": "open",
  "tunnelConfig": {
    "sourceHostId": 1,
    "mode": "local",
    "targetHost": "127.0.0.1",
    "sourcePort": 3000,
    "endpointPort": 3000
  }
}

​
Test message

Send "type": "test" with the same tunnelConfig to verify connectivity without keeping the relay open.

​
Server messages

typeMeaning
readyRelay is established and ready for data. For remote mode, includes bindHost and bindPort.
connectionNew inbound connection in remote mode. Includes streamId.
dataBinary data for a remote-mode stream. Includes streamId and base64-encoded data.
closeA stream was closed. Includes streamId.
errorFatal relay error. Includes error message string.
For local and dynamic modes, binary WebSocket frames carry raw TCP data after the initial ready acknowledgment.

Build docs developers (and LLMs) love

Get started for freeTalk to us