> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Finsys/dockhand/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Environment

> Update an existing Docker environment configuration

## 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

<ParamField path="id" type="number" required>
  The unique identifier of the environment to update
</ParamField>

## Request Body

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

<ParamField body="name" type="string">
  Display name of the environment
</ParamField>

<ParamField body="connectionType" type="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
</ParamField>

### Connection Parameters

<ParamField body="host" type="string">
  Hostname or IP address
</ParamField>

<ParamField body="port" type="number">
  Port number for Docker API connection
</ParamField>

<ParamField body="protocol" type="string">
  Connection protocol: `http` or `https`
</ParamField>

<ParamField body="socketPath" type="string">
  Unix socket path (used when `connectionType` is `socket`)
</ParamField>

### TLS Configuration

<ParamField body="tlsCa" type="string">
  TLS Certificate Authority (CA) certificate in PEM format

  **Format:** Multi-line PEM string with BEGIN/END markers
</ParamField>

<ParamField body="tlsCert" type="string">
  TLS client certificate in PEM format

  **Format:** Multi-line PEM string with BEGIN/END markers
</ParamField>

<ParamField body="tlsKey" type="string">
  TLS client private key in PEM format

  **Format:** Multi-line PEM string with BEGIN/END markers
</ParamField>

<ParamField body="tlsSkipVerify" type="boolean">
  Skip TLS certificate verification
</ParamField>

### Hawser Configuration

<ParamField body="hawserToken" type="string">
  Authentication token for `hawser-standard` connections
</ParamField>

### Display Options

<ParamField body="icon" type="string">
  Icon identifier for UI display
</ParamField>

<ParamField body="labels" type="string[]">
  Array of label strings for categorization (maximum 10 labels)
</ParamField>

### Collection Settings

<ParamField body="collectActivity" type="boolean">
  Enable collection of container activity events
</ParamField>

<ParamField body="collectMetrics" type="boolean">
  Enable collection of host metrics
</ParamField>

<ParamField body="highlightChanges" type="boolean">
  Highlight recent changes in the UI
</ParamField>

### Network Information

<ParamField body="publicIp" type="string">
  Public IP address of the environment host. Set to empty string or null to remove.
</ParamField>

## Response

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

<ResponseField name="id" type="number">
  Environment identifier
</ResponseField>

<ResponseField name="name" type="string">
  Updated name
</ResponseField>

<ResponseField name="labels" type="string[]">
  Parsed array of labels
</ResponseField>

<ResponseField name="publicIp" type="string | null">
  Public IP address
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of the update
</ResponseField>

## Example Requests

### Update Connection Type

```json theme={null}
{
  "connectionType": "direct",
  "host": "new-docker.example.com",
  "port": 2376,
  "protocol": "https"
}
```

### Update TLS Configuration

```json theme={null}
{
  "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)

```json theme={null}
{
  "tlsSkipVerify": true
}
```

### Update Labels and Icon

```json theme={null}
{
  "labels": ["production", "us-west-2", "primary"],
  "icon": "server"
}
```

### Update Collection Settings

```json theme={null}
{
  "collectActivity": false,
  "collectMetrics": true
}
```

### Switch to Hawser Standard

```json theme={null}
{
  "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

```json theme={null}
{
  "connectionType": "hawser-edge"
}
```

### Update Public IP

```json theme={null}
{
  "publicIp": "198.51.100.42"
}
```

### Remove Public IP

```json theme={null}
{
  "publicIp": null
}
```

## Example Response

```json theme={null}
{
  "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

<ResponseField name="403 Forbidden" type="object">
  User lacks `environments:edit` permission

  ```json theme={null}
  {
    "error": "Permission denied"
  }
  ```
</ResponseField>

<ResponseField name="404 Not Found" type="object">
  Environment does not exist

  ```json theme={null}
  {
    "error": "Environment not found"
  }
  ```
</ResponseField>

<ResponseField name="500 Internal Server Error" type="object">
  Failed to update environment

  ```json theme={null}
  {
    "error": "Failed to update environment"
  }
  ```
</ResponseField>

## 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

```json theme={null}
{
  "connectionType": "socket",
  "socketPath": "/var/run/docker.sock"
}
```

### Direct Connection (HTTP)

```json theme={null}
{
  "connectionType": "direct",
  "host": "192.168.1.100",
  "port": 2375,
  "protocol": "http"
}
```

### Direct Connection (HTTPS with TLS)

```json theme={null}
{
  "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

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

### Hawser Edge Connection

```json theme={null}
{
  "connectionType": "hawser-edge"
}
```

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