Update Environment

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

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 formatFormat: Multi-line PEM string with BEGIN/END markers

tlsCert

string

TLS client certificate in PEM formatFormat: Multi-line PEM string with BEGIN/END markers

tlsKey

string

TLS client private key in PEM formatFormat: 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.

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.

API Overview

Container Management

Stack Management

Image Management

Network & Volume

Environment Management

Scheduling & Automation

​Description

​Authentication

​Path Parameters

​Request Body

​Connection Parameters

​TLS Configuration

​Hawser Configuration

​Display Options

​Collection Settings

​Network Information

​Response

​Example Requests

​Update Connection Type

​Update TLS Configuration

​Enable TLS Skip Verify (Insecure)

​Update Labels and Icon

​Update Collection Settings

​Switch to Hawser Standard

​Switch to Hawser Edge

​Update Public IP

​Remove Public IP

​Example Response

​Error Responses

​Behavior Notes

​Cache Management

​Subprocess Notification

​Audit Logging

​Partial Updates

​Label Handling

​Public IP Management

​Connection Type Examples

​Socket Connection

​Direct Connection (HTTP)

​Direct Connection (HTTPS with TLS)

​Hawser Standard Connection

​Hawser Edge Connection

Build docs developers (and LLMs) love

Description

Authentication

Path Parameters

Request Body

Connection Parameters

TLS Configuration

Hawser Configuration

Display Options

Collection Settings

Network Information

Response

Example Requests

Update Connection Type

Update TLS Configuration

Enable TLS Skip Verify (Insecure)

Update Labels and Icon

Update Collection Settings

Switch to Hawser Standard

Switch to Hawser Edge

Update Public IP

Remove Public IP

Example Response

Error Responses

Behavior Notes

Cache Management

Subprocess Notification

Audit Logging

Partial Updates

Label Handling

Public IP Management

Connection Type Examples

Socket Connection

Direct Connection (HTTP)

Direct Connection (HTTPS with TLS)

Hawser Standard Connection

Hawser Edge Connection