Dokploy Deployment

Deploy and manage applications on a self-hosted Dokploy instance (v0.28+, tested through v0.29.x). Dokploy is an open-source PaaS (alternative to Vercel/Heroku) using Docker + Traefik v3.

DOKPLOY_URL must NOT end with /api. The MCP server appends /api itself; a base URL
ending in /api sends every request to /api/api/... and all calls fail. Use
https://dokploy.example.com.

Quick Reference

First Run — Setup

On first use, check if the Dokploy MCP server is configured. If not, run the interactive setup:

1. Check: is a "dokploy" MCP server configured? (`claude mcp list`)
2. If NO → run: python3 skills/dokploy-api-mcp/scripts/setup.py
   (or the full path in the user's skill installation directory)
3. The script will:
   - Ask for the Dokploy URL (e.g., https://dokploy.example.com — without /api)
   - Ask for the API key (Dashboard → Settings → Profile → API/CLI)
   - Validate the connection and report how many endpoints the instance exposes
   - Ask which tool surface to use (tools / gateway / both)
   - Register the server via `claude mcp add-json`, or print the JSON to paste
     manually if the CLI is unavailable
4. Tell the user: "Restart Claude Code to activate the Dokploy MCP server."

With CLI arguments (non-interactive):

python3 skills/dokploy-api-mcp/scripts/setup.py --url https://dokploy.example.com --key YOUR_API_KEY --mode gateway

Add --insecure only for instances with a self-signed certificate — it disables TLS verification, and the API key then travels over an unverified connection.

After setup, the MCP server (@sattva/dokploy-mcp, ~540 tools) will be available on next Claude Code restart. Prefer MCP tools over curl for all operations.

Environment Variables

Before using this skill, ensure these are available:

DOKPLOY_URL=https://dokploy.example.com
DOKPLOY_API_KEY=<generated-api-token>

Generate API token: Dashboard → Settings → Profile → API/CLI → Generate.

Deployment Workflow

Step 1: Check Current State

# Get application status
curl -s -X GET "${DOKPLOY_URL}/api/trpc/application.one?input=$(python3 -c "
import urllib.parse, json
print(urllib.parse.quote(json.dumps({'json':{'applicationId':'APP_ID'}})))
")" -H "x-api-key: ${DOKPLOY_API_KEY}"

Step 2: Trigger Deploy

# Deploy application (POST — mutation)
curl -s -X POST "${DOKPLOY_URL}/api/application.deploy" \
  -H "x-api-key: ${DOKPLOY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"json":{"applicationId":"APP_ID"}}'

Step 3: Monitor Deploy Status

# Poll deployment status
curl -s -X GET "${DOKPLOY_URL}/api/trpc/deployment.all?input=$(python3 -c "
import urllib.parse, json
print(urllib.parse.quote(json.dumps({'json':{'applicationId':'APP_ID'}})))
")" -H "x-api-key: ${DOKPLOY_API_KEY}"

Step 4: Verify Health

curl -sk "https://<app-domain>/api/health"

API Reference

Dokploy uses tRPC internally. Two request formats:

Queries (read) — GET with encoded input

GET /api/trpc/<router>.<procedure>?input=URL_ENCODED({"json":{...}})
Header: x-api-key: <token>

Mutations (write) — POST with JSON body

POST /api/<router>.<procedure>
Header: x-api-key: <token>
Header: Content-Type: application/json
Body: {"json":{...}}

Key Endpoints

See [references/API-REFERENCE.md](references/API-REFERENCE.md) for the full list (the v0.28.4 baseline; run settings.getOpenApiDocument for your instance's actual set).

CLI Usage

# Install
npm install -g @dokploy/cli

# Authenticate (creates ~/.config/dokploy/config.json)
dokploy authenticate

# Verify token
dokploy verify

# Application management
dokploy app create   # Create new application
dokploy app deploy   # Deploy application
dokploy app stop     # Stop application
dokploy app delete   # Delete application

# Database management
dokploy db create    # Create database service
dokploy db delete    # Delete database service

# Environment variables
dokploy env set      # Set env vars
dokploy env list     # List env vars

# Project management
dokploy project create
dokploy project list

MCP Server (full API coverage, ~540 tools)

When MCP is available, ALWAYS prefer MCP tools over curl. MCP handles tRPC URL encoding and response parsing automatically.

See [references/MCP-TOOLS.md](references/MCP-TOOLS.md) for the full tool reference.

Server behavior (v1.1.0+)

• Safety annotations: GET tools carry readOnlyHint, mutating verbs (deploy/delete/stop/update/...) carry destructiveHint — clients can highlight or gate dangerous calls.
• Responses are compact JSON, truncated above DOKPLOYMAXRESPONSECHARS (default 50000) with a truncated marker — refine the query instead of raising the limit blindly.
• Requests time out after DOKPLOYTIMEOUTMS (default 30s); GET is retried on 5xx/429.
• OpenAPI spec is cached in the OS temp dir — the server survives a temporarily unreachable Dokploy.

Gateway mode (v1.2.0+) — 4 tools instead of 540

DOKPLOY_MODE=gateway in the server's env replaces the per-endpoint tools with four:

Flow: search → describe → call/mutate. Measured cost: 2.7 KB of tools/list instead of 239 KB (−98.9%); a full discover-and-invoke cycle ≈ 0.8k tokens. Each tool rejects endpoints of the wrong kind before any request, so the read/write distinction survives — this is why there are four tools and not one generic call.

Use gateway mode for broad exploratory access; use tools mode (default) or a DOKPLOYTOOLS profile when the same handful of endpoints is used every time. DOKPLOYMODE=both exposes both surfaces.

Recommended: filter the tool set

The full list is ~540 tools (~60k tokens of tools/list). For day-to-day deploys set a profile in the env block:

"DOKPLOY_TOOLS": "project_*,application_*,compose_*,deployment_*,docker_*,domain_*,postgres_*,redis_*,backup_*,rollback_*,schedule_*,settings_health"

This cuts the payload by ~70% and still covers all routine work. DOKPLOY_READONLY=1 gives a safe monitoring-only profile (GET tools only).

Setup

Automatic (recommended): Run the setup script from the "First Run" section above — it configures MCP automatically.

Manual — add to the mcpServers object of your Claude config (~/.claude.json for Claude Code; claude mcp add-json does it for you):

{
  "mcpServers": {
    "dokploy": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@sattva/dokploy-mcp@latest"],
      "env": {
        "DOKPLOY_URL": "https://dokploy.example.com",
        "DOKPLOY_API_KEY": "<your-api-token>",
        "DOKPLOY_MODE": "gateway"
      }
    }
  }
}

Note: DOKPLOYURL carries no /api suffix — see the warning at the top. Note: On macOS/Linux use "command": "npx", "args": ["-y", "@sattva/dokploy-mcp@latest"]. Local dev: "command": "node", "args": ["<path>/dokploy-mcp/dist/index.js"]. Env vars: DOKPLOYMODE (tools/gateway/both), DOKPLOYTOOLS, DOKPLOYREADONLY, DOKPLOYTIMEOUTMS, DOKPLOYMAXRESPONSE_CHARS.

MCP Tools by Category (counts from Dokploy v0.28.4; v0.29.x adds ~90 more: ai, forwardAuth, customRole, whitelabeling, patch_*, etc.)

MCP Deployment Workflow

1. application_one                → check current status
2. application_saveEnvironment    → set/update env vars if needed
3. application_saveBuildType      → ensure Dockerfile build configured
4. application_deploy             → trigger deployment
5. application_one                → poll until applicationStatus = "done"
6. curl health endpoint           → verify app is working

Logs — available through MCP (v0.29.x)

Logs are not Dashboard-only. Verified on v0.29.8, all read-only:

Typical flow: deploymentall(applicationId) → take the newest deploymentId → deploymentreadLogs. Only live streaming stays WebSocket-only; use the Dashboard when you need to watch a build in real time.

Remaining MCP limitations

• Docker exec into a container — no API endpoint, use SSH to the VPS

Everything else is available through MCP tools, including: Redis, MariaDB, MongoDB, Compose, Backups, Notifications, Schedules, Rollbacks, SSO, Patches, Organizations, and more.

Common Pitfalls

See [references/PITFALLS.md](references/PITFALLS.md) for detailed solutions.

Build Types

Dokploy supports:

Services (Databases)

Create via Dashboard → Project → Add Service:

• PostgreSQL — internal hostname: <appName>:5432
• MySQL/MariaDB — internal hostname: <appName>:3306
• MongoDB — internal hostname: <appName>:27017
• Redis — internal hostname: <appName>:6379

Internal hostnames use Docker network. External ports optional (may need firewall rules).

Domain & SSL

1. Add domain via Dashboard or API (domain.create)
2. Point DNS A-record to VPS IP
3. Dokploy auto-provisions Let's Encrypt certificate via Traefik v3
4. HTTPS works automatically after DNS propagation

Next.js Specific Guide

See [references/NEXTJS-GUIDE.md](references/NEXTJS-GUIDE.md) for full details on deploying Next.js 14/15 to Dokploy.