Create Environment

Create a new Docker environment in Dockhand

POST /api/environments

Create Environment

cURL

curl --request POST \
  --url https://api.example.com/api/environments \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "connectionType": "<string>",
  "host": "<string>",
  "port": 123,
  "protocol": "<string>",
  "socketPath": "<string>",
  "tlsCa": "<string>",
  "tlsCert": "<string>",
  "tlsKey": "<string>",
  "tlsSkipVerify": true,
  "hawserToken": "<string>",
  "icon": "<string>",
  "labels": [
    "<string>"
  ],
  "collectActivity": true,
  "collectMetrics": true,
  "highlightChanges": true,
  "publicIp": "<string>"
}
'

200

{
  "id": 123,
  "name": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "400 Bad Request": {},
  "403 Forbidden": {},
  "409 Conflict": {},
  "500 Internal Server Error": {}
}

Description

Creates a new Docker environment with the specified configuration. Supports four connection types: local Unix socket, direct TCP connection, Hawser Standard (HTTP proxy), and Hawser Edge (WebSocket reverse proxy).

Authentication

Requires environments:create permission when authentication is enabled.

Request Body

name · string · required

Unique display name for the environment

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

Connection Parameters

host · string

Hostname or IP address (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

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

Unix socket path (used when connectionType is socket)

TLS Configuration

tlsCa · string

TLS Certificate Authority (CA) certificate in PEM format. Required for self-signed certificates.

Format: Multi-line PEM string with BEGIN/END markers

tlsCert · string

TLS client certificate in PEM format for mutual TLS authentication.

Format: Multi-line PEM string with BEGIN/END markers

tlsKey · string

TLS client private key in PEM format for mutual TLS authentication.

Format: Multi-line PEM string with BEGIN/END markers

tlsSkipVerify · boolean · default: "false"

Skip TLS certificate verification. Warning: Insecure, not recommended for production use.

Hawser Configuration

hawserToken · string

Authentication token for hawser-standard connections. Must match the token configured on the Hawser agent.

Display Options

icon · string · default: "globe"

Icon identifier for UI display

labels · string[]

Array of label strings for categorization (maximum 10 labels)

Collection Settings

collectActivity · boolean · default: "true"

Enable collection of container activity events

collectMetrics · boolean · default: "true"

Enable collection of host metrics (CPU, memory)

highlightChanges · boolean · default: "true"

Highlight recent changes in the UI

Network Information

publicIp · string

Public IP address of the environment host

Response

Returns the created environment object with all fields populated.

id · number

Unique identifier for the newly created environment

name · string

Name of the environment

createdAt · string

ISO 8601 timestamp of creation

updatedAt · string

ISO 8601 timestamp of last update

Example Requests

Local Socket Connection

{
  "name": "Local Development",
  "connectionType": "socket",
  "socketPath": "/var/run/docker.sock",
  "icon": "laptop",
  "labels": ["development", "local"]
}

Direct Connection with TLS

{
  "name": "Production Server",
  "connectionType": "direct",
  "host": "docker.example.com",
  "port": 2376,
  "protocol": "https",
  "tlsCa": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKZ...\n-----END CERTIFICATE-----",
  "tlsCert": "-----BEGIN CERTIFICATE-----\nMIIDYTCCAkmgAwIBAgIJALK...\n-----END CERTIFICATE-----",
  "tlsKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w...\n-----END PRIVATE KEY-----",
  "tlsSkipVerify": false,
  "publicIp": "203.0.113.42",
  "icon": "server",
  "labels": ["production", "us-east-1"],
  "collectActivity": true,
  "collectMetrics": true
}

Direct Connection with Self-Signed Certificate

{
  "name": "Staging Server",
  "connectionType": "direct",
  "host": "staging.internal",
  "port": 2376,
  "protocol": "https",
  "tlsCa": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKZ...\n-----END CERTIFICATE-----",
  "tlsSkipVerify": false,
  "icon": "test-tube",
  "labels": ["staging"]
}

Hawser Standard Connection

{
  "name": "Remote Docker Host",
  "connectionType": "hawser-standard",
  "host": "hawser.example.com",
  "port": 8080,
  "protocol": "https",
  "hawserToken": "hwsr_abc123def456ghi789jkl",
  "tlsCa": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKZ...\n-----END CERTIFICATE-----",
  "icon": "network",
  "labels": ["remote", "hawser"]
}

Hawser Edge Connection

{
  "name": "Edge Location",
  "connectionType": "hawser-edge",
  "icon": "cloud",
  "labels": ["edge", "remote"],
  "collectActivity": true,
  "collectMetrics": true
}

Example Response

{
  "id": 4,
  "name": "Production Server",
  "host": "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\"]",
  "hawserToken": null,
  "hawserLastSeen": null,
  "hawserAgentId": null,
  "hawserAgentName": null,
  "hawserVersion": null,
  "hawserCapabilities": null,
  "createdAt": "2024-01-20T16:45:00.000Z",
  "updatedAt": "2024-01-20T16:45:00.000Z"
}

Error Responses

400 Bad Request · object

Invalid request data

Missing name:

{
  "error": "Name is required"
}

Missing host for direct/hawser-standard:

{
  "error": "Host is required for this connection type"
}

403 Forbidden · object

User lacks environments:create permission

{
  "error": "Permission denied"
}

409 Conflict · object

Environment name already exists

{
  "error": "An environment with this name already exists"
}

500 Internal Server Error · object

Failed to create environment

{
  "error": "Failed to create environment"
}

Notes

• Environment names must be unique
• In Enterprise mode, the creator is automatically assigned the Admin role for the new environment
• PEM certificates are automatically cleaned (whitespace trimmed) before storage
• Labels are limited to a maximum of 10 per environment
• After creation, subprocess collectors are notified to begin monitoring the new environment
• For hawser-edge connections, the environment is created but remains inactive until an agent connects