Update Environment

Update an existing Docker environment configuration

PUT /api/environments/{id}

Update Environment

cURL

curl --request PUT \
  --url https://api.example.com/api/environments/{id} \
  --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>",
  "labels": [
    "<string>"
  ],
  "publicIp": {},
  "updatedAt": "<string>",
  "403 Forbidden": {},
  "404 Not Found": {},
  "500 Internal Server Error": {}
}

Description

Updates the configuration of an existing Docker environment. Only the fields provided in the request body will be updated. The Docker client cache is automatically cleared after updates.

Authentication

Requires environments:edit permission when authentication is enabled.

Path Parameters

id · number · required

The unique identifier of the environment to update

Request Body

All fields are optional. Only include fields you want to update.

name · string

Display name of the environment

connectionType · string

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

port · number

Port number for Docker API connection

protocol · string

Connection protocol: http or https

socketPath · string

Unix socket path (used when connectionType is socket)

TLS Configuration

tlsCa · string

TLS Certificate Authority (CA) certificate in PEM format

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

tlsCert · string

TLS client certificate in PEM format

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

tlsKey · string

TLS client private key in PEM format

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

tlsSkipVerify · boolean

Skip TLS certificate verification

Hawser Configuration

hawserToken · string

Authentication token for hawser-standard connections

Display Options

icon · string

Icon identifier for UI display

labels · string[]

Array of label strings for categorization (maximum 10 labels)

Collection Settings

collectActivity · boolean

Enable collection of container activity events

collectMetrics · boolean

Enable collection of host metrics

highlightChanges · boolean

Highlight recent changes in the UI

Network Information

publicIp · string

Public IP address of the environment host. Set to empty string or null to remove.

Response

Returns the updated environment object with parsed labels and public IP.

id · number

Environment identifier

name · string

Updated name

labels · string[]

Parsed array of labels

publicIp · string | null

Public IP address

updatedAt · string

ISO 8601 timestamp of the update

Example Requests

Update Connection Type

{
  "connectionType": "direct",
  "host": "new-docker.example.com",
  "port": 2376,
  "protocol": "https"
}

Update TLS Configuration

{
  "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
}

Enable TLS Skip Verify (Insecure)

{
  "tlsSkipVerify": true
}

Update Labels and Icon

{
  "labels": ["production", "us-west-2", "primary"],
  "icon": "server"
}

Update Collection Settings

{
  "collectActivity": false,
  "collectMetrics": true
}

Switch to Hawser Standard

{
  "connectionType": "hawser-standard",
  "host": "hawser-proxy.example.com",
  "port": 8080,
  "protocol": "https",
  "hawserToken": "hwsr_new_token_here",
  "tlsCa": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

Switch to Hawser Edge

{
  "connectionType": "hawser-edge"
}

Update Public IP

{
  "publicIp": "198.51.100.42"
}

Remove Public IP

{
  "publicIp": null
}

Example Response

{
  "id": 1,
  "name": "Production",
  "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-west-2", "primary"],
  "publicIp": "198.51.100.42",
  "hawserToken": null,
  "hawserLastSeen": null,
  "hawserAgentId": null,
  "hawserAgentName": null,
  "hawserVersion": null,
  "hawserCapabilities": null,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-20T17:15:00.000Z"
}

Error Responses

403 Forbidden · object

User lacks environments:edit permission

{
  "error": "Permission denied"
}

404 Not Found · object

Environment does not exist

{
  "error": "Environment not found"
}

500 Internal Server Error · object

Failed to update environment

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

Behavior Notes

Cache Management

• The Docker client cache is automatically cleared before the update to ensure fresh connections
• This prevents stale connection issues when changing hosts, ports, or TLS settings

Subprocess Notification

• When collectActivity or collectMetrics settings are changed, subprocess collectors are automatically notified
• This ensures metric collection starts or stops immediately

Audit Logging

• All updates are logged in the audit trail
• Sensitive fields (TLS certificates, keys, tokens) are excluded from the audit diff
• The audit log includes a computed diff showing what changed

Partial Updates

• Only fields included in the request body are updated
• Omitted fields retain their current values
• To clear a field, explicitly set it to null or an empty string

Label Handling

• Labels array is only updated if explicitly provided
• Maximum of 10 labels per environment
• Labels are serialized as JSON in the database

Public IP Management

• Setting publicIp to null or empty string removes the IP
• Public IPs are stored separately and included in GET responses

Connection Type Examples

Socket Connection

{
  "connectionType": "socket",
  "socketPath": "/var/run/docker.sock"
}

Direct Connection (HTTP)

{
  "connectionType": "direct",
  "host": "192.168.1.100",
  "port": 2375,
  "protocol": "http"
}

Direct Connection (HTTPS with TLS)

{
  "connectionType": "direct",
  "host": "docker.example.com",
  "port": 2376,
  "protocol": "https",
  "tlsCa": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "tlsCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "tlsKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
}

Hawser Standard Connection

{
  "connectionType": "hawser-standard",
  "host": "hawser.example.com",
  "port": 8080,
  "protocol": "https",
  "hawserToken": "hwsr_abc123",
  "tlsCa": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

Hawser Edge Connection

{
  "connectionType": "hawser-edge"
}

Note: For Hawser Edge, the agent connects to Dockhand via WebSocket, so no host/port is needed.