{
  "markdown": "# dokpilot\n\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/kyzdes/dokpilot-landing/main/public/brand/banner.png\" alt=\"Dokpilot — Deploy anything. One command. No DevOps.\" width=\"100%\" />\n</p>\n\n> Deploy and manage applications on VPS servers with Dokploy (Claude Code / Codex / Gemini skill).\n\n## Install\n\nDokpilot is a **local, single-user** skill — it runs on your machine, uses your\ncredentials, and deploys to **your** VPS. There is no hosted service.\n\n### Prerequisites\n\n- **Node.js 20+** (runs the local dashboard, standard-library only)\n- **jq** and **sshpass** — `brew install jq sshpass` (macOS) / `sudo apt install -y jq sshpass` (Ubuntu/Debian)\n- **git**, and a **VPS** you control (2 GB RAM / 30 GB disk minimum)\n- Optional: a **Cloudflare** token for DNS + SSL\n\n**Platform support:** on **macOS**, Dokploy/Cloudflare secrets live in the system\n**Keychain** and `servers.json` holds only `{_secret}` references. On\n**Linux / non-macOS** there is no OS keystore, so secrets are stored as\n**plaintext** in `servers.json` (mode `0600`) with a loud warning — keep that\nfile private and never commit it.\n\n### Mode B — clone + symlink (primary)\n\n```bash\ngit clone https://github.com/kyzdes/dokpilot.git ~/dokpilot\nmkdir -p ~/.claude/skills\n# the skill lives in the skills/dokpilot subfolder of the repo:\nln -s ~/dokpilot/skills/dokpilot ~/.claude/skills/dokpilot\n```\n\nLaunch the dashboard with `/dokpilot ui` (see [Dashboard](#dashboard-new-in-v40)).\nThe skill locates its own scripts and references via self-location, so the\nsymlink target is what matters.\n\n### Mode A — marketplace (coming soon)\n\nOnce a `dokpilot` entry lands in the `kyzdes/claude-skills` marketplace:\n\n```\n/plugin marketplace add kyzdes/claude-skills\n/plugin install dokpilot@claude-skills\n```\n\nUntil then, use **Mode B**.\n\nFull walkthrough (add server → secret store → first deploy):\n[`skills/dokpilot/references/install.md`](skills/dokpilot/references/install.md).\n\n---\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/badge/version-v4.4.0-00FF41?style=flat-square\" alt=\"Version\" />\n  <img src=\"https://img.shields.io/badge/pass_rate-100%25-00FF41?style=flat-square\" alt=\"Pass Rate\" />\n  <img src=\"https://img.shields.io/badge/stacks-20+-blue?style=flat-square\" alt=\"Stacks\" />\n  <img src=\"https://img.shields.io/badge/license-MIT-gray?style=flat-square\" alt=\"License\" />\n</p>\n\n# Dokpilot\n\n> One command to go from a GitHub repo to a live app with SSL, domain, and auto-deploy on push.\n\n```\n/dokpilot deploy github.com/user/my-app --domain app.example.com\n```\n\nDokpilot is a [Claude Code skill](https://docs.anthropic.com/en/docs/claude-code/skills) that turns Claude into a DevOps engineer for your VPS. It automates the full lifecycle through [Dokploy](https://dokploy.com) and CloudFlare DNS — setup, deploy, domains, databases, monitoring, and teardown.\n\n---\n\n## Benchmarks\n\nWe tested Claude with and without Dokpilot across 3 real-world DevOps scenarios:\n\n<table>\n<tr>\n<td width=\"50%\">\n\n### With Dokpilot\n- Pass rate: **100%**\n- Reads built-in references instantly\n- Uses correct tRPC API calls\n- DNS `--no-proxy` for Let's Encrypt\n- Auto-deploy via GitHub App (no webhooks)\n\n</td>\n<td width=\"50%\">\n\n### Without Dokpilot\n- Pass rate: **24%**\n- Googles outdated Dokploy docs\n- Misses required API fields\n- Breaks SSL with CloudFlare proxy\n- Recommends manual webhook setup\n\n</td>\n</tr>\n</table>\n\n> **Most revealing test:** When asked about auto-deploy, naked Claude recommends setting up webhooks — the exact opposite of how Dokploy works. Dokpilot correctly explains that the GitHub App handles it automatically.\n\n> The recorded eval transcripts are being regenerated against a neutral fixture server before public release (the originals referenced the author's own infrastructure).\n\n---\n\n## Quick Start\n\nInstall the skill first (see [Install](#install)), then:\n\n### 1. Set up your VPS\n\n```\n/dokpilot setup <server-ip> <root-password>\n```\n\nClaude SSHs in, installs Dokploy, configures the firewall, and walks you through\ncreating an admin account + generating a Dokploy API key.\n\n### 2. Deploy\n\n```\n/dokpilot deploy github.com/user/app --domain app.example.com\n```\n\nDokpilot **analyzes** the repo read-only, shows you a plan, and — after you\nconfirm — creates the project in Dokploy, sets up DNS + SSL, deploys, and\nenables auto-deploy on push. See [How It Works](#how-it-works) for the\ntwo-phase detail.\n\nFull onboarding walkthrough:\n[`skills/dokpilot/references/install.md`](skills/dokpilot/references/install.md).\n\n---\n\n## Commands\n\n| Command | Description |\n|:--------|:------------|\n| `/dokpilot setup <ip> <password>` | Set up a fresh VPS with Dokploy |\n| `/dokpilot deploy <url> [--domain D] [--dry-run]` | Deploy from GitHub |\n| `/dokpilot domain add <domain> <project>` | Add domain with SSL |\n| `/dokpilot domain remove <domain>` | Remove domain |\n| `/dokpilot domain list` | List all domains |\n| `/dokpilot db create <type> <name>` | Create database (postgres/mysql/mongo/redis) |\n| `/dokpilot db list` | List databases |\n| `/dokpilot db delete <name>` | Delete database |\n| `/dokpilot status` | Server + project status with resource warnings |\n| `/dokpilot logs <project> [--build]` | Runtime or build logs |\n| `/dokpilot destroy <project>` | Delete project (with confirmation) |\n| `/dokpilot config` | Manage servers and CloudFlare config |\n| `/dokpilot ui` | Launch the local web dashboard (new in v4.0) |\n\nAll commands support `--server <name>` for multi-server setups.\n\n---\n\n## Dashboard (new in v4.0)\n\n`/dokpilot ui` launches a local web dashboard at `http://127.0.0.1:<port>/`\n(bearer-token gated, 127.0.0.1-only) with:\n\n- **Servers + apps inventory** — live status from your configured Dokploy instances\n- **Deploy wizard** — paste a GitHub URL, answer the questions Claude asks, watch\n  the build stream live, click the resulting URL\n- **Live log tail** — SSE-streamed deploy logs via SSH `tail -f`\n- **Domains + DNS** — Dokploy domains × Cloudflare records, with one-click add\n- **Databases** — list, create (postgres / mysql / mariadb / mongo / redis)\n- **Claude console** — chat with Claude directly inside the dashboard; tool\n  calls and reasoning stream inline\n\nBackend is Node 20 stdlib only (zero npm deps), lives in\n[`mcp-server/ui-server/`](mcp-server/ui-server/). Start with `/dokpilot ui`,\nstop with `/dokpilot ui --stop`, status with `--status`.\n\n---\n\n## Supported Stacks\n\nAuto-detected from your project files:\n\n| Runtime | Frameworks |\n|:--------|:-----------|\n| **Node.js** | Next.js, Nuxt, NestJS, Express, Remix, Vite, Astro |\n| **Python** | Django, FastAPI, Flask |\n| **Go** | Any Go project |\n| **Rust** | Any Rust project |\n| **Ruby** | Rails, Sinatra |\n| **Java** | Spring Boot, Maven, Gradle |\n| **.NET** | ASP.NET Core |\n| **PHP** | Laravel, Symfony |\n| **Docker** | Dockerfile or docker-compose.yml |\n\n---\n\n## How It Works\n\nDeploy runs in **two phases** with a human gate in between. The target repo is\ntreated as **untrusted input** (see [SECURITY.md](SECURITY.md)).\n\n```\nYou: /dokpilot deploy github.com/user/app --domain app.example.com\n\n── Phase A · ANALYZE (read-only) ───────────────────────────────\n  Shallow-clones the repo into a throwaway dir. A headless agent\n  inspects it with Read / Grep / Glob ONLY (no Bash, no Write, no\n  bypassPermissions) and emits a schema-validated stack manifest\n  (e.g. Next.js + Prisma + PostgreSQL, env-var NAMES, build/start).\n\n── CONFIRM · plan-then-confirm gate ────────────────────────────\n  Dokpilot shows the plan and asks for any secret env vars\n  (NEXTAUTH_SECRET, etc.). Flagged/freeform commands are surfaced\n  here. Nothing infra-changing runs until you confirm.\n\n── Phase B · ACTUATE (infra only) ──────────────────────────────\n  Driven ONLY by the validated manifest (never re-reads the repo):\n    1. Creates project + PostgreSQL in Dokploy\n    2. Connects repo via GitHub App (auto-deploy enabled)\n    3. Sets build type (Nixpacks) with all required API fields\n    4. Creates DNS A-record in Cloudflare (--no-proxy for SSL)\n    5. Adds domain with Let's Encrypt certificate\n    6. Deploys, monitors logs, verifies HTTPS\n\nResult: https://app.example.com is live\n        Auto-deploy active — push to main to redeploy\n```\n\n> This is a **containment** posture, not a sandbox: Phase A has no write/exec\n> capability and the manifest is the only thing crossing into Phase B.\n\n### Deployment fallback chain\n\nIf the GitHub App isn't available, the skill automatically falls back:\n\n```\nGitHub App (recommended)\n  └─ Public git URL\n       └─ PAT-authenticated URL\n            └─ Manual Docker build on server\n```\n\n---\n\n## Architecture\n\n```\ndokpilot/                          # this repo\n├── skills/dokpilot/               # the skill itself (symlink target for Mode B)\n│   ├── SKILL.md                   # skill logic + command routing\n│   ├── scripts/                   # Bash core (D-002: shell, not Node)\n│   │   ├── dokploy-api.sh         # Dokploy tRPC client; destroy env-gate\n│   │   ├── cloudflare-dns.sh      # Cloudflare DNS (multi-part TLD support)\n│   │   ├── ssh-exec.sh            # SSH wrapper (normal/bg/poll modes)\n│   │   ├── secret-store.sh        # macOS Keychain wrapper\n│   │   └── wait-ready.sh          # URL health checker\n│   ├── references/                # built-in guides (primary source of truth)\n│   │   ├── install.md             # onboarding walkthrough\n│   │   ├── deploy-guide.md  setup-guide.md  stack-detection.md\n│   │   ├── secrets-management.md  troubleshooting.md  …\n│   ├── config/\n│   │   └── servers.json           # credentials / {_secret} refs (gitignored)\n│   └── templates/                 # VPS init script(s)\n├── mcp-server/ui-server/          # local dashboard backend (Node 20 stdlib, zero-dep)\n│   ├── server.js                  # 127.0.0.1 + bearer token + CSRF + Host allow-list\n│   ├── launch.sh                  # cross-platform launcher (/dokpilot ui)\n│   └── lib/\n│       ├── analyze-worker.js      # Phase A — read-only repo analysis\n│       ├── claude-worker.js       # Phase B — infra-only actuation (manifest-driven)\n│       ├── manifest.js            # the trust-boundary validator\n│       ├── worker-guard.js        # shared hard guard for the workers\n│       └── destroy-nonce.js       # server-minted single-use HMAC for UI deletes\n├── dokpilot-ui/                   # dashboard HTML/CSS/JS (static)\n└── scripts/clean-machine-smoke.sh # throwaway-HOME install smoke (Mode B)\n```\n\nThe security-critical boundary is the **manifest**: Phase A (read-only) emits\nit, `lib/manifest.js` validates it, and Phase B acts on *only* that. See\n[SECURITY.md](SECURITY.md).\n\n---\n\n## Security\n\n> ### ⚠️ What this can do to your machine, servers, and bill\n>\n> Dokpilot is a **real DevOps automation**, not a sandbox. Running as you, it can:\n>\n> - **Your machine:** run local shell, clone arbitrary third-party repos, and\n>   read the secrets you stored for it.\n> - **Your servers:** SSH in (often as `root`) and create, deploy, restart, and\n>   **delete** Dokploy projects, apps, databases, and domains.\n> - **Your DNS:** create/modify Cloudflare records for the zones your token covers.\n> - **Your bill:** each deploy runs a headless `claude` and **spends your own\n>   Claude usage**.\n>\n> **Only point it at repositories and servers you trust.** The full trust\n> boundary, threat model (repo prompt injection), two-phase defense, safety\n> controls, and honest residual risks are in **[SECURITY.md](SECURITY.md)**.\n\n### Cost & Privacy\n\n- **Cost:** every `analyze`/`deploy` consumes your Claude subscription/API\n  usage. Server, bandwidth, and domain costs are billed by your VPS and\n  registrar.\n- **Your data stays yours:** the repo and its env vars go to **your** Dokploy\n  instance over your credentials. Nothing is sent to a Dokpilot-controlled\n  service.\n- **Cloudflare token scope:** grant only **Zone → DNS → Edit** on the specific\n  zone(s) you deploy to — nothing broader.\n- **Local-only storage:** credentials live in your macOS **Keychain** (or a\n  `0600` `servers.json` on Linux, with a loud warning). Secret values are never\n  echoed.\n- **No telemetry:** Dokpilot has no analytics, no phone-home, no accounts.\n\n---\n\n## Documentation\n\n| Document | Description |\n|:---------|:------------|\n| [`SECURITY.md`](SECURITY.md) | Trust boundary, threat model, safety controls, residual risks |\n| [`CONTRIBUTING.md`](CONTRIBUTING.md) | How to contribute (issues-only support, hard constraints) |\n| [`skills/dokpilot/references/install.md`](skills/dokpilot/references/install.md) | Full onboarding walkthrough |\n| [`CHANGELOG.md`](CHANGELOG.md) | Full version history |\n\n---\n\n## Version History\n\n**Current: v4.0.0** (2026-05-24) — [Full changelog](CHANGELOG.md)\n\n- v4.0: Rebrand to Dokpilot, Dokploy v0.29+ baseline, local web dashboard with deploy wizard & SSE log streaming, real Claude console\n- v3.2: macOS Keychain secret store (`scripts/secret-store.sh`)\n- v3.1: Fixed GitHub App integration, 4-tier deploy fallback, command injection fix, `--dry-run` mode\n- v3.0: Built-in reference guides, MCP server, benchmarks (100% pass rate)\n- v2.0: Dokploy v0.27 compatibility (`environmentId`)\n- v1.0: Initial release — 8 commands, 20+ stacks\n\n---\n\n## Support & Contributing\n\nSolo-maintained, **issues-only** support — no SLA, no Discord, no roadmap\nvoting. Found a bug or want a new stack? [Open an issue](https://github.com/kyzdes/dokpilot/issues).\n\n- Contributor guide + hard constraints (Bash core, zero-dep ui-server, never\n  commit `servers.json`/`context-map-*/`): [CONTRIBUTING.md](CONTRIBUTING.md).\n- Security issues: follow responsible disclosure in [SECURITY.md](SECURITY.md)\n  — do not file them as normal public issues.\n\n## License\n\n[MIT](LICENSE) — provided **\"AS IS\", without warranty of any kind**. You run\nDokpilot against your own servers and repos at your own risk.\n",
  "bytes": 13832,
  "sha": "3f28b9de4dec46d5b8da35b97d607780c0d59d1fb18032c76db9bfb14f24c6bb",
  "repo_slug": "kyzdes/dokpilot",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_kyzdes_dokpilot_cf45ea2b/readme"
}