Docker API: container management over SSH

The Docker API executes Docker commands on a remote host over an existing SSH session. All container operations require a valid SSH session established via POST /docker/ssh/connect. Sessions are idle-scoped and automatically cleaned up after 60 minutes of inactivity. All endpoints require JWT authentication. Docker must be enabled for the target host (the enableDocker flag must be set in Host Settings).

Session management

Connect SSH session

POST /docker/ssh/connect Establishes an SSH connection to a host for Docker operations. Supports password, SSH key, OPKSSH, and keyboard-interactive authentication.

sessionId

string

required

A client-generated unique identifier for this session. Use UUIDs or similar.

hostId

number

required

ID of the target host in the Termix database. Credentials are resolved server-side.

userProvidedPassword

string

Optional password override. Takes precedence over stored credentials.

userProvidedSshKey

string

Optional SSH private key override (PEM format).

userProvidedKeyPassword

string

Passphrase for the override private key.

useSocks5

boolean

Route the connection through a SOCKS5 proxy.

socks5Host

string

SOCKS5 proxy hostname or IP.

socks5Port

number

SOCKS5 proxy port. Defaults to 1080.

socks5Username

string

SOCKS5 proxy username.

socks5Password

string

SOCKS5 proxy password.

socks5ProxyChain

object[]

Ordered array of SOCKS5 proxy chain nodes for multi-hop proxying.

The response varies based on whether additional authentication is needed:

success

boolean

true when the connection is established immediately.

message

string

Confirmation message.

connectionLogs

object[]

Structured connection log entries showing DNS, TCP, handshake, and auth stages.

requires_totp

boolean

Present and true when TOTP verification is needed. Follow up with POST /docker/ssh/connect-totp.

requires_warpgate

boolean

Present and true when Warpgate browser authentication is needed.

url

string

Warpgate authentication URL, present when requires_warpgate is true.

securityKey

string

Warpgate security key shown during authentication.

Error responses

Status	Meaning
400	Missing `sessionId` or `hostId`, or invalid SSH key format.
401	Authentication required, or session expired.
403	Docker is not enabled for this host, or access denied.
404	Host not found.
500	SSH connection failed.

Example request

cURL

curl -X POST https://your-termix-host/docker/ssh/connect \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "sess_abc123", "hostId": 7}'

Verify TOTP

POST /docker/ssh/connect-totp Completes a pending SSH connection by verifying a TOTP or keyboard-interactive code. Call this when POST /docker/ssh/connect returns requires_totp: true. The session must be verified within 3 minutes.

sessionId

string

required

Session ID from the initial connect call.

totpCode

string

required

One-time code from the authenticator app or the keyboard-interactive prompt.

Error responses

Status	Meaning
400	`sessionId` or `totpCode` missing.
401	Authentication required or TOTP code invalid.
404	TOTP session expired — reconnect.
408	TOTP session or verification timed out.

Complete Warpgate authentication

POST /docker/ssh/connect-warpgate Signals that the user has completed Warpgate browser authentication. Call this after the user visits the Warpgate URL. The Warpgate session expires after 5 minutes.

sessionId

string

required

Session ID from the initial connect call.

Disconnect SSH session

POST /docker/ssh/disconnect Terminates an SSH session and releases all associated resources.

sessionId

string

required

Session ID to disconnect.

Check session status

GET /docker/ssh/status

sessionId

string

required

Session ID to check.

success

boolean

Always true.

connected

boolean

Whether the session is currently connected.

Keep session alive

POST /docker/ssh/keepalive Resets the session idle timer. Call this periodically (e.g. every 30 seconds) to prevent automatic cleanup.

sessionId

string

required

Session ID to keep alive.

success

boolean

Always true when the session is alive.

connected

boolean

Session connection state.

lastActive

number

Unix timestamp (milliseconds) of the updated last-active time.

Error responses

Status	Meaning
400	Session ID missing or session not connected.
403	Session belongs to a different user.

Docker availability

Validate Docker

GET /docker/validate/:sessionId Verifies that Docker is installed and the daemon is accessible on the remote host.

sessionId

string

required

Active SSH session ID.

available

boolean

Whether Docker is usable.

version

string

Docker version string, present when available is true.

error

string

Human-readable error description when available is false.

code

string

Machine-readable error code. One of NOT_INSTALLED, DAEMON_NOT_RUNNING, or PERMISSION_DENIED.

Example request

cURL

curl -X GET https://your-termix-host/docker/validate/sess_abc123 \
  -H "Authorization: Bearer <token>"

Example response (200 — available)

{"available": true, "version": "24.0.5"}

Containers

List containers

GET /docker/containers/:sessionId Lists containers on the remote host.

sessionId

string

required

Active SSH session ID.

all

boolean

default:"true"

When true, includes stopped containers. Set to false for running containers only.

Returns an array of container objects:

[].id

string

Short container ID.

[].name

string

Container name.

[].image

string

Image name and tag.

[].status

string

Human-readable status (e.g. "Up 3 hours").

[].state

string

Machine-readable state: running, exited, paused, etc.

[].ports

string

Port mapping string.

[].created

string

Creation timestamp.

Example request

cURL

curl -X GET "https://your-termix-host/docker/containers/sess_abc123?all=true" \
  -H "Authorization: Bearer <token>"

Get container details

GET /docker/containers/:sessionId/:containerId Returns the full docker inspect output for a single container.

sessionId

string

required

Session ID.

containerId

string

required

Container ID or name. Only alphanumeric characters, dots, hyphens, and underscores are allowed.

Error responses

Status	Meaning
400	Session not connected.
404	Container not found.
500	Command execution error.

Start a container

POST /docker/containers/:sessionId/:containerId/start

sessionId

string

required

Session ID.

containerId

string

required

Container ID or name.

success

boolean

Always true on success.

message

string

"Container started successfully".

Stop a container

POST /docker/containers/:sessionId/:containerId/stop

sessionId

string

required

Session ID.

containerId

string

required

Container ID or name.

Restart a container

POST /docker/containers/:sessionId/:containerId/restart

sessionId

string

required

Session ID.

containerId

string

required

Container ID or name.

Pause a container

POST /docker/containers/:sessionId/:containerId/pause

sessionId

string

required

Session ID.

containerId

string

required

Container ID or name.

Unpause a container

POST /docker/containers/:sessionId/:containerId/unpause

sessionId

string

required

Session ID.

containerId

string

required

Container ID or name.

Remove a container

DELETE /docker/containers/:sessionId/:containerId/remove

Removing a running container without force=true returns a 400 error.

sessionId

string

required

Session ID.

containerId

string

required

Container ID or name.

force

boolean

default:"false"

When true, forces removal of a running container (docker rm -f).

Error responses

Status	Meaning
400	Session not connected, or container is running and `force` is not set.
404	Container not found.
500	Command execution error.

Example request

cURL

curl -X DELETE "https://your-termix-host/docker/containers/sess_abc123/my-container/remove?force=true" \
  -H "Authorization: Bearer <token>"

Get container logs

GET /docker/containers/:sessionId/:containerId/logs

sessionId

string

required

Session ID.

containerId

string

required

Container ID or name.

tail

number

default:"100"

Number of log lines to return from the end of the log.

timestamps

boolean

default:"false"

Prefix each log line with its timestamp.

since

string

Show logs since this timestamp (RFC 3339 / ISO 8601 format).

until

string

Show logs before this timestamp.

success

boolean

Always true on success.

logs

string

Combined stdout/stderr log output.

Example request

cURL

curl -X GET "https://your-termix-host/docker/containers/sess_abc123/nginx/logs?tail=50&timestamps=true" \
  -H "Authorization: Bearer <token>"

Get container stats

GET /docker/containers/:sessionId/:containerId/stats Returns a single snapshot of resource usage for a container (non-streaming).

sessionId

string

required

Session ID.

containerId

string

required

Container ID or name.

cpu

string

CPU usage percentage string (e.g. "2.34%").

memoryUsed

string

Memory used (e.g. "128MiB").

memoryLimit

string

Memory limit (e.g. "2GiB").

memoryPercent

string

Memory usage percentage.

netInput

string

Network bytes received.

netOutput

string

Network bytes sent.

blockRead

string

Block I/O bytes read.

blockWrite

string

Block I/O bytes written.

pids

string

Number of processes in the container.

Example request

cURL

curl -X GET https://your-termix-host/docker/containers/sess_abc123/nginx/stats \
  -H "Authorization: Bearer <token>"

Example response (200)

{
  "cpu": "0.15%",
  "memoryUsed": "52.3MiB",
  "memoryLimit": "7.77GiB",
  "memoryPercent": "0.66%",
  "netInput": "1.2GB",
  "netOutput": "350MB",
  "blockRead": "0B",
  "blockWrite": "12.4MB",
  "pids": "4"
}

Overview

Endpoints

Docker API: container management over SSH

Session management

Connect SSH session

Verify TOTP

Complete Warpgate authentication

Disconnect SSH session

Check session status

Keep session alive

Docker availability

Validate Docker

Containers

List containers

Get container details

Start a container

Stop a container

Restart a container

Pause a container

Unpause a container

Remove a container

Get container logs

Get container stats

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Session management

​Connect SSH session

​Verify TOTP

​Complete Warpgate authentication

​Disconnect SSH session

​Check session status

​Keep session alive

​Docker availability

​Validate Docker

​Containers

​List containers

​Get container details

​Start a container

​Stop a container

​Restart a container

​Pause a container

​Unpause a container

​Remove a container

​Get container logs

​Get container stats

Build docs developers (and LLMs) love

Session management

Connect SSH session

Verify TOTP

Complete Warpgate authentication

Disconnect SSH session

Check session status

Keep session alive

Docker availability

Validate Docker

Containers

List containers

Get container details

Start a container

Stop a container

Restart a container

Pause a container

Unpause a container

Remove a container

Get container logs

Get container stats