List Environments

Retrieve all Docker environments configured in Dockhand

GET /api/environments

List Environments

cURL

curl --request GET \
  --url https://api.example.com/api/environments

200

{
  "id": 123,
  "name": "<string>",
  "host": "<string>",
  "port": 123,
  "protocol": "<string>",
  "connectionType": "<string>",
  "socketPath": "<string>",
  "tlsCa": "<string>",
  "tlsCert": "<string>",
  "tlsKey": "<string>",
  "tlsSkipVerify": true,
  "hawserToken": "<string>",
  "hawserLastSeen": "<string>",
  "hawserAgentId": "<string>",
  "hawserAgentName": "<string>",
  "hawserVersion": "<string>",
  "hawserCapabilities": [
    "<string>"
  ],
  "icon": "<string>",
  "collectActivity": true,
  "collectMetrics": true,
  "highlightChanges": true,
  "labels": [
    "<string>"
  ],
  "publicIp": {},
  "updateCheckEnabled": true,
  "updateCheckAutoUpdate": true,
  "imagePruneEnabled": true,
  "timezone": {},
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "403 Forbidden": {},
  "500 Internal Server Error": {}
}

Description

Retrieves a list of all Docker environments. In Enterprise mode with authentication enabled, results are filtered based on the user’s accessible environments unless the user is an admin.

Authentication

Requires environments:view permission when authentication is enabled.

Response

Returns an array of environment objects with parsed labels, public IPs, and additional settings.

Environment Object

id · number · required

Unique identifier for the environment

name · string · required

Display name of the environment

host · string

Hostname or IP address for remote Docker connections (required for direct and hawser-standard types)

port · number · default: "2375"

Port number for Docker API connection

protocol · string · default: "http"

Connection protocol: http or https

connectionType · string · default: "socket"

Type of Docker connection:

• socket - Local Unix socket
• direct - Direct TCP connection to Docker API
• hawser-standard - HTTP proxy via Hawser agent
• hawser-edge - WebSocket reverse proxy via Hawser agent

socketPath · string · default: "/var/run/docker.sock"

Unix socket path (used when connectionType is socket)

tlsCa · string

TLS Certificate Authority (CA) certificate in PEM format

tlsCert · string

TLS client certificate in PEM format

tlsKey · string

TLS client private key in PEM format

tlsSkipVerify · boolean · default: "false"

Skip TLS certificate verification (insecure, not recommended for production)

hawserToken · string

Authentication token for hawser-standard connections

hawserLastSeen · string

ISO 8601 timestamp of last connection from Hawser Edge agent

hawserAgentId · string

Unique identifier of the connected Hawser Edge agent

hawserAgentName · string

Name of the connected Hawser Edge agent

hawserVersion · string

Version of the Hawser agent software

hawserCapabilities · string[]

JSON array of agent capabilities: ["compose", "exec", "metrics"]

icon · string · default: "globe"

Icon identifier for UI display

collectActivity · boolean · default: "true"

Enable collection of container activity events

collectMetrics · boolean · default: "true"

Enable collection of host metrics

highlightChanges · boolean · default: "true"

Highlight recent changes in the UI

labels · string[]

Array of label strings for categorization (max 10 labels)

publicIp · string | null

Public IP address of the environment host

updateCheckEnabled · boolean

Whether automatic update checking is enabled

updateCheckAutoUpdate · boolean

Whether automatic updates are enabled

imagePruneEnabled · boolean

Whether automatic image pruning is enabled

timezone · string | null

Timezone identifier for the environment

createdAt · string

ISO 8601 timestamp of environment creation

updatedAt · string

ISO 8601 timestamp of last update

Example Response

[
  {
    "id": 1,
    "name": "Production",
    "host": "prod-docker.example.com",
    "port": 2376,
    "protocol": "https",
    "connectionType": "direct",
    "socketPath": "/var/run/docker.sock",
    "tlsCa": "-----BEGIN CERTIFICATE-----\n...",
    "tlsCert": "-----BEGIN CERTIFICATE-----\n...",
    "tlsKey": "-----BEGIN PRIVATE KEY-----\n...",
    "tlsSkipVerify": false,
    "icon": "server",
    "collectActivity": true,
    "collectMetrics": true,
    "highlightChanges": true,
    "labels": ["production", "us-east-1"],
    "publicIp": "203.0.113.42",
    "updateCheckEnabled": true,
    "updateCheckAutoUpdate": false,
    "imagePruneEnabled": true,
    "timezone": "America/New_York",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:22:00.000Z"
  },
  {
    "id": 2,
    "name": "Local Development",
    "connectionType": "socket",
    "socketPath": "/var/run/docker.sock",
    "port": 2375,
    "protocol": "http",
    "tlsSkipVerify": false,
    "icon": "laptop",
    "collectActivity": true,
    "collectMetrics": true,
    "highlightChanges": true,
    "labels": ["development"],
    "publicIp": null,
    "updateCheckEnabled": false,
    "updateCheckAutoUpdate": false,
    "imagePruneEnabled": false,
    "timezone": null,
    "createdAt": "2024-01-10T09:15:00.000Z",
    "updatedAt": "2024-01-10T09:15:00.000Z"
  },
  {
    "id": 3,
    "name": "Edge Server",
    "connectionType": "hawser-edge",
    "port": 2375,
    "protocol": "http",
    "socketPath": "/var/run/docker.sock",
    "tlsSkipVerify": false,
    "icon": "cloud",
    "collectActivity": true,
    "collectMetrics": true,
    "highlightChanges": true,
    "labels": ["edge", "remote"],
    "publicIp": null,
    "updateCheckEnabled": false,
    "updateCheckAutoUpdate": false,
    "imagePruneEnabled": false,
    "timezone": "UTC",
    "hawserLastSeen": "2024-01-20T15:30:00.000Z",
    "hawserAgentId": "edge-agent-001",
    "hawserAgentName": "Edge Agent 1",
    "hawserVersion": "1.2.0",
    "hawserCapabilities": ["compose", "exec", "metrics"],
    "createdAt": "2024-01-18T12:00:00.000Z",
    "updatedAt": "2024-01-20T15:30:00.000Z"
  }
]

Error Responses

403 Forbidden · object

User lacks environments:view permission

{
  "error": "Permission denied"
}

500 Internal Server Error · object

Failed to retrieve environments

{
  "error": "Failed to get environments"
}