Dokploy Infrastructure Management

Dokploy is a self-hosted PaaS. All management happens through its REST API using curl. No CLI tools or bash scripts — construct curl commands directly.

Authentication & Request Pattern

Environment variables (must be set):

```
DOKPLOY_API_URL
```
— base URL of the Dokploy instance (e.g.,
```
https://dokploy.example.com
```
)
```
DOKPLOY_API_KEY
```
— API token generated from Dokploy UI: Settings → Profile → API/CLI Section

All endpoints follow the pattern:

$DOKPLOY_API_URL/api/{router}.{procedure}

GET request (reads)

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/{endpoint}?{param}={value}"

Parameters are flat query params. Do NOT use tRPC

?input=

encoding — it doesn't work on the OpenAPI surface.

POST request (all mutations)

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/{endpoint}" \
  -d '{"param": "value"}'

Every mutation (create, update, remove, deploy, start, stop, reload) uses POST. Never use PUT, PATCH, or DELETE.

Always pipe output through

jq

for readability:

| jq .

Response Formats

Not all endpoints return JSON objects. Be aware of these patterns:

application.update
, application.saveEnvironment
, and other mutation endpoints may return a bare
```
true
```
instead of the updated object. Do not pipe these through
```
jq
```
with object filters — use
```
jq .
```
or skip
```
jq
```
entirely.
application.deploy
returns empty output on success.
GET endpoints (
```
*.one
```
,
```
*.all
```
) return full JSON objects.
When in doubt, don't assume the response shape — capture raw output first.

Critical: The Resource Hierarchy

Project
  └── Environment (default: "production")
        ├── Applications
        ├── Databases (postgres, mysql, mariadb, mongo, redis)
        └── Compose services

Every project has at least one environment. The default is named "production" with
```
isDefault: true
```
.
Creating any resource requires
environmentId
, NOT
projectId
.
To get
```
environmentId
```
: fetch the project with
```
project.one
```
, then read
```
.environments[0].environmentId
```
(or find the environment by name).

This is the most common source of errors. Always fetch the environment first.

Quick Reference

Projects & Environments

Task	Endpoint	Method	Key Params
List all projects	`project.all`	GET	—
Get project details	`project.one`	GET	`projectId`
Create project	`project.create`	POST	`name` , `description`
Update project	`project.update`	POST	`projectId` , `name` , `description`
Delete project	`project.remove`	POST	`projectId`

Applications

Task	Endpoint	Method	Key Params
Get app details	`application.one`	GET	`applicationId`
Create app	`application.create`	POST	`name` , `environmentId`
Update app	`application.update`	POST	`applicationId` , ...
Delete app	`application.delete`	POST	`applicationId`
Deploy app	`application.deploy`	POST	`applicationId`
Start app	`application.start`	POST	`applicationId`
Stop app	`application.stop`	POST	`applicationId`
Redeploy app	`application.redeploy`	POST	`applicationId`
Save env vars	`application.saveEnvironment`	POST	`applicationId` , `env` , `buildArgs` , `buildSecrets` , `createEnvFile`
Set build type	`application.saveBuildType`	POST	`applicationId` , `buildType` , ...

Databases

All database types share the same operation pattern. Replace

{type}

with:

postgres

mysql

mariadb

mongo

redis

Task	Endpoint	Method	Key Params
Get DB details	`{type}.one`	GET	`{type}Id`
Create DB	`{type}.create`	POST	`name` , `environmentId` , `databasePassword` , ...
Delete DB	`{type}.remove`	POST	`{type}Id`
Deploy DB	`{type}.deploy`	POST	`{type}Id`
Start DB	`{type}.start`	POST	`{type}Id`
Stop DB	`{type}.stop`	POST	`{type}Id`

Note: Each type uses its own ID field name:

postgresId

mysqlId

mariadbId

mongoId

redisId

Domains

Task	Endpoint	Method	Key Params
Get domain	`domain.one`	GET	`domainId`
Domains for app	`domain.byApplicationId`	GET	`applicationId`
Create domain	`domain.create`	POST	`host` , `applicationId` , `port`
Update domain	`domain.update`	POST	`domainId` , `host` , ...
Delete domain	`domain.delete`	POST	`domainId`

Compose

Task	Endpoint	Method	Key Params
Get compose	`compose.one`	GET	`composeId`
Create compose	`compose.create`	POST	`name` , `environmentId`
Update compose	`compose.update`	POST	`composeId` , ...
Delete compose	`compose.delete`	POST	`composeId` , `deleteVolumes`
Deploy compose	`compose.deploy`	POST	`composeId`
Start compose	`compose.start`	POST	`composeId`
Stop compose	`compose.stop`	POST	`composeId`
List services	`compose.loadServices`	GET	`composeId`

Deployments

Task	Endpoint	Method	Key Params
List deployments	`deployment.all`	GET	`applicationId`
By type	`deployment.allByType`	GET	`id` , `type`

type

values:

application

compose

server

schedule

previewDeployment

backup

volumeBackup

Servers

Task	Endpoint	Method	Key Params
List servers	`server.all`	GET	—
Get server	`server.one`	GET	`serverId`
Create server	`server.create`	POST	`name` , `ipAddress` , `port` , `username` , `sshKeyId`
Delete server	`server.remove`	POST	`serverId`

Common Workflows

List all projects with their resources

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/project.all" | jq .

The response includes nested environments with all applications, databases, and compose services summarized.

Deploy an existing application

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/application.deploy" \
  -d '{"applicationId": "THE_APP_ID"}' | jq .

Create a new app in an existing project

Step 1 — Get the project's environmentId:

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/project.one?projectId=PROJECT_ID" \
  | jq '.environments[] | select(.isDefault) | .environmentId'

Step 2 — Create the application:

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/application.create" \
  -d '{"name": "my-app", "environmentId": "ENV_ID"}' | jq .

Create a full project from scratch

Step 1 — Create the project:

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/project.create" \
  -d '{"name": "My Project", "description": "Project description"}' | jq .

Step 2 — Get the new project's environmentId from the response, or fetch it:

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/project.all" \
  | jq '.[] | select(.name == "My Project") | .environments[0].environmentId'

Step 3 — Create resources using that environmentId (apps, databases, compose).

Check deployment status

For applications:

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/deployment.all?applicationId=APP_ID" | jq '.[0]'

For compose services:

bash

curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
  "$DOKPLOY_API_URL/api/deployment.allByType?id=COMPOSE_ID&type=compose" | jq '.[0]'

Set environment variables on an app

Env vars are set as a single newline-separated string block, not key-value pairs.

Required fields:

buildArgs

buildSecrets

, and

createEnvFile

are mandatory (use empty strings and

false

as defaults):

bash

curl -s -X POST \
  -H "x-api-key: $DOKPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  "$DOKPLOY_API_URL/api/application.saveEnvironment" \
  -d '{
    "applicationId": "APP_ID",
    "env": "DATABASE_URL=postgres://...\nREDIS_URL=redis://...\nNODE_ENV=production",
    "buildArgs": "",
    "buildSecrets": "",
    "createEnvFile": false
  }'

Important Notes

```
project.all
```
returns a comprehensive overview — use it to discover IDs before drilling down.
Deployment is asynchronous. After triggering deploy, poll
```
deployment.all
```
or
```
deployment.allByType
```
to check status.
Destructive operations (
```
remove
```
,
```
delete
```
) cannot be undone. Always confirm with the user first.
The Swagger UI is available at
```
$DOKPLOY_API_URL/swagger
```
for interactive API exploration (admin only).

Reference Files

For full endpoint details with all parameters:

Need details about...	Read
Projects & environments	`references/api-projects.md`
Applications (CRUD, deploy, build types, git providers)	`references/api-applications.md`
Databases (PostgreSQL, MySQL, MariaDB, MongoDB, Redis)	`references/api-databases.md`
Domains (create, update, certificates)	`references/api-domains.md`
Docker Compose services	`references/api-compose.md`
Deployment history & logs	`references/api-deployments.md`
Server management	`references/api-servers.md`

dokploy

NPX Install

Tags

SKILL.md Content

Dokploy Infrastructure Management

Authentication & Request Pattern

GET request (reads)

POST request (all mutations)

Response Formats

Critical: The Resource Hierarchy

Quick Reference

Projects & Environments

Applications

Databases

Domains

Compose

Deployments

Servers

Common Workflows

List all projects with their resources

Deploy an existing application

Create a new app in an existing project

Create a full project from scratch

Check deployment status

Set environment variables on an app

Important Notes

Reference Files