Create Environment

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.

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

API Overview

Container Management

Stack Management

Image Management

Network & Volume

Environment Management

Scheduling & Automation

Create Environment

Description

Authentication

Request Body

Connection Parameters

TLS Configuration

Hawser Configuration

Display Options

Collection Settings

Network Information

Response

Example Requests

Local Socket Connection

Direct Connection with TLS

Direct Connection with Self-Signed Certificate

Hawser Standard Connection

Hawser Edge Connection

Example Response

Error Responses

Notes

Build docs developers (and LLMs) love

API Overview

Container Management

Stack Management

Image Management

Network & Volume

Environment Management

Scheduling & Automation

​Description

​Authentication

​Request Body

​Connection Parameters

​TLS Configuration

​Hawser Configuration

​Display Options

​Collection Settings

​Network Information

​Response

​Example Requests

​Local Socket Connection

​Direct Connection with TLS

​Direct Connection with Self-Signed Certificate

​Hawser Standard Connection

​Hawser Edge Connection

​Example Response

​Error Responses

​Notes

Build docs developers (and LLMs) love

Description

Authentication

Request Body

Connection Parameters

TLS Configuration

Hawser Configuration

Display Options

Collection Settings

Network Information

Response

Example Requests

Local Socket Connection

Direct Connection with TLS

Direct Connection with Self-Signed Certificate

Hawser Standard Connection

Hawser Edge Connection

Example Response

Error Responses

Notes