Create Environment

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

import requests

url = "https://api.example.com/api/environments"

payload = {
    "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>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'
  })
};

fetch('https://api.example.com/api/environments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/environments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/environments"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"connectionType\": \"<string>\",\n  \"host\": \"<string>\",\n  \"port\": 123,\n  \"protocol\": \"<string>\",\n  \"socketPath\": \"<string>\",\n  \"tlsCa\": \"<string>\",\n  \"tlsCert\": \"<string>\",\n  \"tlsKey\": \"<string>\",\n  \"tlsSkipVerify\": true,\n  \"hawserToken\": \"<string>\",\n  \"icon\": \"<string>\",\n  \"labels\": [\n    \"<string>\"\n  ],\n  \"collectActivity\": true,\n  \"collectMetrics\": true,\n  \"highlightChanges\": true,\n  \"publicIp\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/environments")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"connectionType\": \"<string>\",\n  \"host\": \"<string>\",\n  \"port\": 123,\n  \"protocol\": \"<string>\",\n  \"socketPath\": \"<string>\",\n  \"tlsCa\": \"<string>\",\n  \"tlsCert\": \"<string>\",\n  \"tlsKey\": \"<string>\",\n  \"tlsSkipVerify\": true,\n  \"hawserToken\": \"<string>\",\n  \"icon\": \"<string>\",\n  \"labels\": [\n    \"<string>\"\n  ],\n  \"collectActivity\": true,\n  \"collectMetrics\": true,\n  \"highlightChanges\": true,\n  \"publicIp\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/environments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"connectionType\": \"<string>\",\n  \"host\": \"<string>\",\n  \"port\": 123,\n  \"protocol\": \"<string>\",\n  \"socketPath\": \"<string>\",\n  \"tlsCa\": \"<string>\",\n  \"tlsCert\": \"<string>\",\n  \"tlsKey\": \"<string>\",\n  \"tlsSkipVerify\": true,\n  \"hawserToken\": \"<string>\",\n  \"icon\": \"<string>\",\n  \"labels\": [\n    \"<string>\"\n  ],\n  \"collectActivity\": true,\n  \"collectMetrics\": true,\n  \"highlightChanges\": true,\n  \"publicIp\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

POST

api

environments

Create Environment

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

import requests

url = "https://api.example.com/api/environments"

payload = {
    "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>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'
  })
};

fetch('https://api.example.com/api/environments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/environments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/environments"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"connectionType\": \"<string>\",\n  \"host\": \"<string>\",\n  \"port\": 123,\n  \"protocol\": \"<string>\",\n  \"socketPath\": \"<string>\",\n  \"tlsCa\": \"<string>\",\n  \"tlsCert\": \"<string>\",\n  \"tlsKey\": \"<string>\",\n  \"tlsSkipVerify\": true,\n  \"hawserToken\": \"<string>\",\n  \"icon\": \"<string>\",\n  \"labels\": [\n    \"<string>\"\n  ],\n  \"collectActivity\": true,\n  \"collectMetrics\": true,\n  \"highlightChanges\": true,\n  \"publicIp\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/environments")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"connectionType\": \"<string>\",\n  \"host\": \"<string>\",\n  \"port\": 123,\n  \"protocol\": \"<string>\",\n  \"socketPath\": \"<string>\",\n  \"tlsCa\": \"<string>\",\n  \"tlsCert\": \"<string>\",\n  \"tlsKey\": \"<string>\",\n  \"tlsSkipVerify\": true,\n  \"hawserToken\": \"<string>\",\n  \"icon\": \"<string>\",\n  \"labels\": [\n    \"<string>\"\n  ],\n  \"collectActivity\": true,\n  \"collectMetrics\": true,\n  \"highlightChanges\": true,\n  \"publicIp\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/environments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"connectionType\": \"<string>\",\n  \"host\": \"<string>\",\n  \"port\": 123,\n  \"protocol\": \"<string>\",\n  \"socketPath\": \"<string>\",\n  \"tlsCa\": \"<string>\",\n  \"tlsCert\": \"<string>\",\n  \"tlsKey\": \"<string>\",\n  \"tlsSkipVerify\": true,\n  \"hawserToken\": \"<string>\",\n  \"icon\": \"<string>\",\n  \"labels\": [\n    \"<string>\"\n  ],\n  \"collectActivity\": true,\n  \"collectMetrics\": true,\n  \"highlightChanges\": true,\n  \"publicIp\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

string

required

Unique display name for the environment

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

string

Hostname or IP address (required for direct and hawser-standard types)

number

default:"2375"

Port number for Docker API connection

string

default:"http"

Connection protocol: http or https

string

default:"/var/run/docker.sock"

Unix socket path (used when connectionType is socket)

TLS Configuration

string

TLS Certificate Authority (CA) certificate in PEM format. Required for self-signed certificates.Format: Multi-line PEM string with BEGIN/END markers

string

TLS client certificate in PEM format for mutual TLS authentication.Format: Multi-line PEM string with BEGIN/END markers

string

TLS client private key in PEM format for mutual TLS authentication.Format: Multi-line PEM string with BEGIN/END markers

boolean

default:"false"

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

Hawser Configuration

string

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

Display Options

string

default:"globe"

Icon identifier for UI display

string[]

Array of label strings for categorization (maximum 10 labels)

Collection Settings

boolean

default:"true"

Enable collection of container activity events

boolean

default:"true"

Enable collection of host metrics (CPU, memory)

boolean

default:"true"

Highlight recent changes in the UI

Network Information

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

string

Name of the environment

string

ISO 8601 timestamp of creation

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

object

Invalid request dataMissing name:

{
  "error": "Name is required"
}

Missing host for direct/hawser-standard:

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

object

User lacks environments:create permission

{
  "error": "Permission denied"
}

object

Environment name already exists

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

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

​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

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