Dokploy Remote Management Skill

Manage a remote Dokploy instance via its REST API (383 endpoints, 40 domains).

Prerequisites

IMPORTANT: Before running any command, check if the venv exists. If it does not, create it and install dependencies:

if [ ! -d "<SKILL_DIR>/.venv" ]; then cd <SKILL_DIR> python3 -m venv .venv .venv/bin/pip install httpx fi

PYTHON=<SKILL_DIR>/.venv/bin/python3

Environment variables (REQUIRED):

export DOKPLOY_URL="https://your-dokploy-instance.com" export DOKPLOY_API_KEY="your-api-key-here"

Script Location

<SKILL_DIR>/scripts/dokploy.py

Usage Pattern

$PYTHON scripts/dokploy.py <domain> <action> [--param-name value ...]

Quick Reference

Domain Actions Description

project

all , create , one , update , remove , duplicate

Manage projects

application

one , create , deploy , redeploy , start , stop , update , delete , ... Manage applications (27 actions)

compose

one , create , deploy , start , stop , update , delete , ... Manage Docker Compose services (26 actions)

postgres

one , create , deploy , start , stop , update , remove , ... PostgreSQL databases (14 actions)

mysql

one , create , deploy , start , stop , update , remove , ... MySQL databases (13 actions)

mariadb

one , create , deploy , start , stop , update , remove , ... MariaDB databases (13 actions)

mongo

one , create , deploy , start , stop , update , remove , ... MongoDB databases (13 actions)

redis

one , create , deploy , start , stop , update , remove , ... Redis instances (14 actions)

docker

getContainers , getConfig , restartContainer , ... Docker operations (7 actions)

domain

create , update , delete , one , byApplicationId , ... Domain management (9 actions)

server

all , one , create , update , remove , setup , ... Server management (16 actions)

settings

getDokployVersion , getIp , health , cleanAll , ... System settings (39 actions)

backup

create , update , remove , one , manualBackup* , ... Backup management (11 actions)

notification

all , create* , update* , test* , remove , ... Notifications (26 actions)

user

all , get , one , update , remove , createApiKey , ... User management (19 actions)

organization

all , create , update , delete , one , ... Organizations (8 actions)

deployment

all , allByCompose , allByServer , allByType , killProcess

Deployments (5 actions)

destination

all , create , update , remove , one , testConnection

Backup destinations (6 actions)

certificates

all , create , one , remove

SSL certificates (4 actions)

registry

all , create , update , remove , one , testRegistry

Docker registries (6 actions)

ssh-key

all , create , update , remove , one , generate

SSH keys (6 actions)

github

githubProviders , one , getGithubBranches , ... GitHub integration (6 actions)

gitlab

gitlabProviders , one , create , update , ... GitLab integration (7 actions)

gitea

giteaProviders , one , create , update , ... Gitea integration (8 actions)

bitbucket

bitbucketProviders , one , create , update , ... Bitbucket integration (7 actions)

git-provider

getAll , remove

Git providers (2 actions)

environment

byProjectId , create , update , remove , one , duplicate

Environments (6 actions)

schedule

create , update , delete , list , one , runManually

Scheduled tasks (6 actions)

security

create , update , delete , one

Basic auth security (4 actions)

port

create , update , delete , one

Port mappings (4 actions)

mounts

create , update , remove , one , allNamedByApplicationId

Volume mounts (5 actions)

redirects

create , update , delete , one

URL redirects (4 actions)

rollback

delete , rollback

Rollback management (2 actions)

cluster

addManager , addWorker , getNodes , removeWorker

Swarm cluster (4 actions)

swarm

getNodeApps , getNodeInfo , getNodes

Swarm info (3 actions)

ai

create , delete , deploy , get , getAll , update , ... AI features (9 actions)

stripe

canCreateMoreServers , createCheckoutSession , ... Billing (4 actions)

admin

setupMonitoring

Admin (1 action)

volume-backups

create , delete , list , one , runManually , update

Volume backups (6 actions)

preview-deployment

all , delete , one

Preview deployments (3 actions)

notification

all , create* , update* , test* , ... Notifications (26 actions)

Common Commands

List all projects

$PYTHON scripts/dokploy.py project all

Get Dokploy version

$PYTHON scripts/dokploy.py settings getDokployVersion

Get system health

$PYTHON scripts/dokploy.py settings health

Get server IP

$PYTHON scripts/dokploy.py settings getIp

List Docker containers

$PYTHON scripts/dokploy.py docker getContainers

Get a specific project

$PYTHON scripts/dokploy.py project one --project-id "abc123"

Create a project

$PYTHON scripts/dokploy.py project create --name "My Project" --description "Description"

Create an application

$PYTHON scripts/dokploy.py application create --name "my-app" --environment-id "env123"

Deploy an application

$PYTHON scripts/dokploy.py application deploy --application-id "app123"

Stop an application

$PYTHON scripts/dokploy.py application stop --application-id "app123"

Create a PostgreSQL database

$PYTHON scripts/dokploy.py postgres create
--name "my-db"
--app-name "my-db-app"
--database-name "mydb"
--database-user "admin"
--database-password "secret"
--environment-id "env123"

List all servers

$PYTHON scripts/dokploy.py server all

List all users

$PYTHON scripts/dokploy.py user all

Get current user

$PYTHON scripts/dokploy.py user get

Create a notification (Discord)

$PYTHON scripts/dokploy.py notification createDiscord
--name "alerts"
--webhook-url "https://discord.com/api/webhooks/..."
--app-build-error true
--app-deploy true
--database-backup true
--dokploy-restart true
--docker-cleanup true
--server-threshold true
--decoration true

Raw output (no wrapper)

$PYTHON scripts/dokploy.py --raw project all

Custom timeout

$PYTHON scripts/dokploy.py --timeout 120 compose deploy --compose-id "comp123"

CLI Flags

Global flags

Flag Description Default

--raw

Output raw API response (no {"success": true, "data": ...} wrapper) false

--timeout

Request timeout in seconds 60

Parameter naming

CLI flags use kebab-case, converted from the API's camelCase:

• applicationId → --application-id

• environmentId → --environment-id

• composeId → --compose-id

• serverId → --server-id

Parameter types

API Type CLI Input Example

string

Plain text --name "my-app"

number / integer

Numeric string --port 3000

boolean

true /false , yes /no , 1 /0 , on /off

--enabled true

array

JSON array string --watch-paths '["src/", "lib/"]'

object

JSON object string --metrics-config '{"cpu": true}'

Common Workflows

Full project setup

1. Create project

$PYTHON scripts/dokploy.py project create --name "production"

2. Get environments for the project

$PYTHON scripts/dokploy.py environment byProjectId --project-id "PROJECT_ID"

3. Create application in environment

$PYTHON scripts/dokploy.py application create --name "api" --environment-id "ENV_ID"

4. Configure and deploy

$PYTHON scripts/dokploy.py application deploy --application-id "APP_ID"

Database management

Create a PostgreSQL database

$PYTHON scripts/dokploy.py postgres create --name "db" --app-name "db-app"
--database-name "mydb" --database-user "user" --database-password "pass"
--environment-id "ENV_ID"

Start it

$PYTHON scripts/dokploy.py postgres start --postgres-id "PG_ID"

Create a backup

$PYTHON scripts/dokploy.py backup create --schedule "0 2 * * *" --prefix "daily"
--destination-id "DEST_ID" --database "mydb" --database-type postgres
--postgres-id "PG_ID"

Server monitoring

Check system health

$PYTHON scripts/dokploy.py settings health

Get version

$PYTHON scripts/dokploy.py settings getDokployVersion

List containers

$PYTHON scripts/dokploy.py docker getContainers

Clean unused images

$PYTHON scripts/dokploy.py settings cleanUnusedImages

Output Format

Success:

{ "success": true, "data": { ... } }

Error (stderr):

{ "success": false, "error": "Error message", "status_code": 401, "detail": { ... } }

Exit codes:

Code Meaning

0

Success

1

API error or runtime error

2

Usage error (missing domain/action)

Technical Notes

• All 383 Dokploy API endpoints are supported (40 domains)

• API uses tRPC-over-REST: GET /api/<router>.<procedure> for queries, POST for mutations

• Authentication via x-api-key header

• Automatic retry on 5xx errors (up to 2 retries with backoff)

• Default timeout: 60 seconds (configurable via --timeout )

• Single dependency: httpx

• Boolean parameters accept: true /false , yes /no , 1 /0 , on /off (case-insensitive). Invalid values are rejected with an error.

• Array/object parameters accept JSON strings

• Error messages redact sensitive data (API keys, tokens) from URLs and response details