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