AI Assist

Dokploy AI Assistant Integration

Dokploy v0.29 introduced an AI router that lets the server call out to an LLM provider to (a) analyse a failed deployment's build log and (b) suggest next steps. The ai-* MCP tools are how plugins drive that integration.

This skill teaches: which providers Dokploy supports, how to wire one up, how to invoke the two flagship endpoints (analyzeLogs and suggest), and what to do when AI is not configured.

The AI router calls run on the Dokploy server, not locally — Dokploy holds the provider credentials. The MCP tools just orchestrate.

Tool inventory

Step 1 — Check whether AI is already configured

Always do this first. If a provider already exists and is enabled, skip ahead to Step 3.

mcp__dokploy__ai-getEnabledProviders

Cross-check with ai-getAll if the enabled list is empty — there may be providers configured but turned off (isEnabled: false).

Step 2 — Configure a provider (only if none enabled)

Dokploy's AI router is provider-agnostic — anything that speaks the OpenAI chat-completions API works. Common choices:

Test, then create the provider

ai-testConnection and ai-getModels take the candidate payload (apiUrl + apiKey), not an aiId — so test BEFORE saving:

1. mcp__dokploy__ai-testConnection
   → { apiUrl: "https://api.openai.com/v1", apiKey: "<secret>", model: "gpt-4o-mini" }
   → returns { ok: true/false, error?: string }

2. mcp__dokploy__ai-create        # only after the test passes
   → {
       name: "openai-prod",
       apiKey: "<secret>",
       apiUrl: "https://api.openai.com/v1",
       model: "gpt-4o-mini",
       isEnabled: true
     }
   → returns { aiId }

3. (optional) mcp__dokploy__ai-getModels
   → { apiUrl: "https://api.openai.com/v1", apiKey: "<secret>" }   # NOT aiId
   → returns the endpoint's model list; useful if you want to switch the chosen model

If testConnection returns ok: false, do not move on. Common causes:

• Wrong apiUrl (forgot /v1, used the wrong path).
• Invalid / expired API key.
• Self-hosted endpoint not reachable from the Dokploy server's network namespace.

Disable rather than delete a misconfigured provider with ai-update { aiId, isEnabled: false } — that way audit history is preserved.

Step 3 — Analyse a failed deployment

This is the canonical workflow used by the debug-deploy skill and the /dokploy-dev:analyze command. ai-analyzeLogs does not fetch logs for you — you fetch the text first (via the read-logs skill) and pass it in.

1. Pick an enabled provider
   aiId = first entry from  mcp__dokploy__ai-getEnabledProviders

2. Fetch the log text (read-logs skill)
   build failure   → mcp__dokploy__deployment-readLogs { deploymentId, tail: 1000 }   → context: "build"
   app runtime     → mcp__dokploy__application-readLogs { applicationId, tail: 500 }   → context: "runtime"
   compose runtime → loop compose-readLogs per container, concatenate                 → context: "runtime"

3. Analyse
   mcp__dokploy__ai-analyzeLogs
     → { aiId, logs: "<the text from step 2>", context: "build" | "runtime" }
     → returns a root-cause summary + suggested fix

4. Apply the suggested fix
   → Update env vars / build type / Dockerfile / domain config, then `application-redeploy` / `compose-redeploy`

The response is a free-form LLM summary. Read it critically — the LLM doesn't know your codebase, only the log text you sent. If the suggestion contradicts what the log clearly shows, trust the log.

Cost / latency note

You control how much log goes to the LLM via the tail parameter when you fetch it. A stuck container restarting for hours can produce huge logs — keep tail modest (e.g. 500–1000) or use search to pre-filter to error lines before passing the text to ai-analyzeLogs, so you don't blow past the provider's context window.

Step 4 — Open-ended suggestions

When there's no specific failure but you want guidance ("what should I tighten on this app before going to production?"):

mcp__dokploy__ai-suggest
  → { aiId: "<enabled provider>", input: "<the question / state description text>", serverId?: "<optional>" }
  → returns suggestions

ai-suggest differs from ai-analyzeLogs in that input is a free-form question or state description you compose (there is no applicationId/prompt form) — describe the app's config, env, and recent history in the input text. Use it for:

• "Is my health-check configured correctly?"
• "Should I switch this from Nixpacks to Dockerfile?"
• "Recommend env vars I might be missing for Next.js production."
• "Anything dangerous about my Traefik labels?"

Fallback: when AI is not available

If you cannot enable a provider (offline server, no budget, policy), the debugging workflow still works without AI — it just falls back to the manual log-grep patterns in debug-deploy Step 2.

Communicate this to the user explicitly:

"Dokploy AI is not configured. I'll work through the build log manually. To enable AI-summarised analysis later, configure a provider via ai-create (see the ai-assist skill)."

Do not block on AI. The plugin must remain useful without it.

Security / privacy considerations

• Provider sends build logs externally — build logs can contain env var values from RUN echo $SECRET >> build.log-style mistakes. Audit before sending sensitive logs to a third-party LLM.
• Self-hosted Ollama / vLLM is the most privacy-preserving option for regulated workloads.
• API keys live in Dokploy — ai-getAll returns them masked. Rotate via ai-update if you suspect leakage.
• Audit log — every ai-analyzeLogs / ai-suggest call is recorded in auditLog-all. Useful for cost attribution.

Troubleshooting

See also

• debug-deploy — chains ai-analyzeLogs into the broader failure workflow
• api-reference/references/ai-and-debugging.md — REST API surface for the ai router
• /dokploy-dev:analyze command — one-shot wrapper around ai-analyzeLogs for the most recent failed deploy