Server Management

API endpoints for managing remote servers, monitoring, and infrastructure setup in Dokploy

The Server API allows you to manage remote servers, configure monitoring, and perform infrastructure operations.

Create Server

cURL

curl -X POST "https://your-dokploy-instance.com/api/server.create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "description": "Main production deployment server",
    "ipAddress": "192.168.1.100",
    "port": 22,
    "username": "deploy",
    "sshKeyId": "ssh_key_123",
    "serverType": "deploy"
  }'

Register a new remote server for deployments or builds.

Body Parameters

name · string · required

Display name for the server.

description · string

Optional description of the server’s purpose.

ipAddress · string · required

IP address or hostname of the server.

port · number · required

SSH port number (typically 22).

username · string · required

SSH username for connecting to the server.

sshKeyId · string · required

ID of the SSH key to use for authentication.

serverType · string · required

Type of server.

Show options

• deploy - Server for deploying applications
• build - Server for building application images

---

Get Server

cURL

curl -X GET "https://your-dokploy-instance.com/api/server.one?serverId=server_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Retrieve details of a specific server.

Query Parameters

serverId · string · required

The ID of the server to retrieve.

---

List All Servers

cURL

curl -X GET "https://your-dokploy-instance.com/api/server.all" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get all servers in your organization with service counts.

Response

Returns an array of servers with the total count of services (applications, databases, compose files) deployed on each server.

---

Setup Server

cURL

curl -X POST "https://your-dokploy-instance.com/api/server.setup" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serverId": "server_123"
  }'

Install required dependencies on a server (Docker, buildpacks, etc.).

Body Parameters

serverId · string · required

The ID of the server to set up.

---

Validate Server

cURL

curl -X GET "https://your-dokploy-instance.com/api/server.validate?serverId=server_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Check if a server has all required dependencies installed.

Query Parameters

serverId · string · required

The ID of the server to validate.

Response

docker · object

Docker installation status.

Show child attributes

enabled · boolean

Whether Docker is installed and accessible.

version · string

Docker version string.

rclone · object

Rclone installation status.

Show child attributes

enabled · boolean

version · string

nixpacks · object

Nixpacks installation status.

Show child attributes

enabled · boolean

version · string

buildpacks · object

Cloud Native Buildpacks installation status.

Show child attributes

enabled · boolean

version · string

railpack · object

Railpack installation status.

Show child attributes

enabled · boolean

version · string

isDokployNetworkInstalled · boolean

Whether the Dokploy Docker network is configured.

isSwarmInstalled · boolean

Whether Docker Swarm mode is initialized.

isMainDirectoryInstalled · boolean

Whether the main Dokploy directory structure exists.

---

Security Audit

cURL

curl -X GET "https://your-dokploy-instance.com/api/server.security?serverId=server_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Perform a security audit on a server.

Query Parameters

serverId · string · required

The ID of the server to audit.

Response

ufw · object

UFW (Uncomplicated Firewall) status.

Show child attributes

installed · boolean

active · boolean

defaultIncoming · string

Default incoming traffic policy (deny/allow).

ssh · object

SSH configuration.

Show child attributes

enabled · boolean

keyAuth · boolean

Whether key-based authentication is enabled.

permitRootLogin · string

passwordAuth · string

usePam · string

nonRootUser · object

Show child attributes

hasValidSudoUser · boolean

Whether a non-root sudo user exists.

unattendedUpgrades · object

Automatic security updates configuration.

Show child attributes

installed · boolean

active · boolean

updateEnabled · number

upgradeEnabled · number

fail2ban · object

Fail2ban intrusion prevention status.

Show child attributes

installed · boolean

enabled · boolean

active · boolean

sshEnabled · string

sshMode · string

---

Setup Monitoring

cURL

curl -X POST "https://your-dokploy-instance.com/api/server.setupMonitoring" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serverId": "server_123",
    "metricsConfig": {
      "server": {
        "refreshRate": 5,
        "port": 9090,
        "token": "monitoring_token",
        "urlCallback": "https://your-instance.com/api/metrics",
        "retentionDays": 7,
        "cronJob": "0 0 * * *",
        "thresholds": {
          "cpu": 80,
          "memory": 85
        }
      },
      "containers": {
        "refreshRate": 10,
        "services": {
          "include": ["app-*"],
          "exclude": ["test-*"]
        }
      }
    }
  }'

Configure monitoring and metrics collection for a server.

Body Parameters

serverId · string · required

The ID of the server to configure.

metricsConfig · object · required

Metrics collection configuration.

Show child attributes

server · object · required

Server-level metrics configuration.

Show child attributes

refreshRate · number · required

Metrics refresh rate in seconds (minimum: 2).

port · number · required

Port for metrics endpoint (minimum: 1).

token · string · required

Authentication token for metrics endpoint.

urlCallback · string · required

Callback URL for metrics delivery.

retentionDays · number · required

Number of days to retain metrics (minimum: 1).

cronJob · string · required

Cron expression for cleanup schedule.

thresholds · object · required

Alert thresholds.

Show child attributes

cpu · number · required

CPU usage threshold percentage (0-100).

memory · number · required

Memory usage threshold percentage (0-100).

containers · object · required

Container-level metrics configuration.

Show child attributes

refreshRate · number · required

Container metrics refresh rate in seconds (minimum: 2).

services · object · required

Service filtering configuration.

Show child attributes

include · array

Array of service name patterns to include.

exclude · array

Array of service name patterns to exclude.

---

Update Server

cURL

curl -X POST "https://your-dokploy-instance.com/api/server.update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serverId": "server_123",
    "name": "Updated Server Name",
    "description": "Updated description",
    "ipAddress": "192.168.1.100",
    "port": 22,
    "username": "deploy",
    "sshKeyId": "ssh_key_123",
    "serverType": "deploy"
  }'

Update server configuration.

Body Parameters

serverId · string · required

The ID of the server to update.

name · string · required

Updated server name.

description · string

Updated description.

ipAddress · string · required

Updated IP address or hostname.

port · number · required

Updated SSH port.

username · string · required

Updated SSH username.

sshKeyId · string · required

Updated SSH key ID.

serverType · string · required

Server type (deploy or build).

command · string

Custom setup command.

---

Remove Server

cURL

curl -X POST "https://your-dokploy-instance.com/api/server.remove" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serverId": "server_123"
  }'

Delete a server from your infrastructure. The server must have no active services.

Body Parameters

serverId · string · required

The ID of the server to remove.

---

Get Server Metrics

cURL

curl -X GET "https://your-dokploy-instance.com/api/server.getServerMetrics?url=https://metrics.example.com&token=metrics_token&dataPoints=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Retrieve server metrics data from the monitoring endpoint.

Query Parameters

url · string · required

The metrics endpoint URL.

token · string · required

Authentication token for the metrics endpoint.

dataPoints · string · required

Number of data points to retrieve.

Response

Returns an array of metric data points with CPU, memory, disk, and network statistics.