By the end of this page you have a working protocol for handing a deployment to an AI agent without handing it your production box. The protocol is boring on purpose: a fact sheet, a prompt template, a guardrail list, a verification table, and a handoff document.
Most deployment guides stop at the config files. That is the easy part now. The hard part is that an agent will confidently do the wrong thing at 3 AM if the instructions leave room, and then report success. This chapter removes the room.
The fact sheet
Never let an agent start from a repository alone. It needs facts that are not in git, and guessing them is how you get a dashboard on 0.0.0.0/0. Copy this table into the task and fill every row.
## Deployment fact sheet
- Repo: git@... (branch, latest tag)
- App name / slug: app
- Domain: app.example.com
- VPS public IP: ${VPS_IP}
- Tailscale hostname/IP: ${TAILNET_HOST}
- SSH user: deploy
- Stack directory: /srv/app
- Registry: ${REGISTRY_HOST}/${ORG}/${APP}
- Image roles: web, worker
- Web port in container: 80
- Health path: /up
- Database engine/version: postgres 18 / mysql 8.2
- Queue + scheduler: horizon / schedule:work
- Secret source: Doppler project X config prd, synced to /srv/app/.env
- Backup target: ${BACKUP_TARGET}, retention 14 daily, 8 weekly
- Origin firewall: Cloudflare ranges only (managed by cf-only-web)
- Monitoring: Nightwatch project X, ntfy topic X
- Rollback procedure: ./deploy.sh --rollback vX.Y.Z
- Who approves DNS/Cloudflare changes: (name)
If a row is unknown, the agent stops and asks. A deployment started with a guessed hostname is a future incident with a timestamp.
The prompt template
This format works with Claude, GPT, Codex, or any agent that can run shell commands. It front-loads constraints, because agents follow constraints that appear before the work and forget ones mentioned at the end.
You are deploying one web app to one VPS. Work through the numbered plan below,
one step at a time. After every step, run its verification command and paste the
real output. Do not claim a step passed without output.
Context: <fact sheet>
Non-negotiable constraints:
- Never build images on the production host. Pull only.
- Never print, copy, or commit secrets. Reference them, do not echo them.
- One change per deploy. No drive-by refactors.
- Do not touch Cloudflare DNS, Access, or account-level settings without approval.
- Do not run destructive database commands (drop, truncate, import-leads, down -v).
- Before any migration: confirm a backup exists and name its path.
- Before any deploy: state the rollback command.
- If a fact is missing or ambiguous, stop and ask. Do not invent infrastructure.
Sources of truth (read these before acting):
- /srv/app/DEPLOY.md
- the repo's AGENTS.md or .ai/rules/
- this guide, the reference pages
Plan:
1. Verify the box hardening and the origin firewall. Verify: external curl of
${VPS_IP} on 443 must fail, curl through Cloudflare must return 200.
2. Verify Traefik routes this host and CrowdSec is in the middleware chain.
Verify: router list from the tailnet dashboard.
3. Verify the image contract: one web image, one worker image, immutable tags.
Verify: docker image ls and registry tags.
4. Run deploy.sh --check, then deploy.sh. Verify: /up 200, digest changed.
5. Verify TLS issuer is not TRAEFIK DEFAULT CERT.
6. Verify a backup exists from today and a restore drill is documented.
7. Report with the proof table at the end.
Stop conditions: any verification fails twice, any step would require a
destructive action, or any fact is missing. Report the blocker instead of
working around it.
The "paste the real output" rule is the highest-leverage sentence in the prompt. An agent that must show output will find out that the deploy step never ran; an agent that is allowed to summarize will tell you it did.
Guardrails
These are the rules that keep the blast radius small. They apply to humans too, which is why they work.
- One change per deploy. A release that changes the base image, the database schema, and the CDN rules at once has three possible causes when it breaks. Nobody learns anything.
- No secrets in chat, logs, or images. Reference paths and variable names. If a command needs a token, pipe it from a file inside the host, never inline it into a command that gets logged.
- Backup before migration, always. The agent must name the backup file before running
migrate. If the backup cannot be taken, the deploy does not happen. - State the rollback before deploying. One command, written into the deploy report. If it does not exist, fix that first.
- Verify externally. Local checks lie. Curl through Cloudflare, curl the origin directly, check the certificate issuer, check the digest, check the logs.
- Do not trust green CI. A pipeline can be green while the deploy step never ran. The digest and the external probe are the source of truth.
- Never build or compile on production. If a fix requires a rebuild, it goes through CI.
- Never
docker compose down -vunless the goal is to destroy data. It deletes volumes, logs, and the evidence of whatever you were debugging. - Ask about DNS and account permissions. DNS changes and Cloudflare account settings can take every app on the zone down at once.
- Leave a paper trail. The deploy report, the tag, and any surprise go into the AAR. The next agent inherits what you wrote, not what you remember.
The proof table
Agents love to write paragraphs. Make them write a table instead. This is the minimum evidence for "deployed".
| Check | Command | Expected | Actual |
|---|---|---|---|
| Public URL | curl -s -o /dev/null -w '%{http_code}' https://app.example.com/ |
200 | |
| Health | curl -fsS https://app.example.com/up |
2xx JSON | |
| Origin blocked | curl -s --max-time 5 -H 'Host: app.example.com' https://${VPS_IP}/ |
connection failure | |
| TLS issuer | openssl s_client -connect ${VPS_IP}:443 -servername app.example.com |
not TRAEFIK DEFAULT CERT |
|
| Routers | dashboard API /api/http/routers from tailnet |
host present, crowdsec middleware | |
| CrowdSec | cscli bouncers list, cscli decisions list |
bouncer connected | |
| Deploy digest | docker inspect on web container before/after |
changed | |
| Backup | `ls -lt ${BACKUP_DIR} | head` | today |
| Exceptions | Nightwatch issue list since tag | no new issues | |
| Rollback | docker image ls for immutable tags |
tag exists |
If a row cannot be filled with real output, the deployment is not done.
The failure modes of agent-driven deployments
These are the patterns to watch for, generalized from real incidents. Each one is preventable with a rule above.
| What it looks like | What actually happened | Prevention |
|---|---|---|
| "Deployed successfully" but nothing changed | Compose filename mismatch or the deploy job never ran; CI was green | Digest check, no-op warning, external probe |
| Site fine, one background job broken | A rotated secret never reached the host env file | Secret drift check, live preflight for critical keys |
| Two pipelines deploy the same stack | Old GitHub workflow left active next to the new CI | Audit .github and .crow, archive one, one deploy path per app |
| Dashboard or metrics public | Internal router enabled on the public entrypoint, or ipAllowList set to 0.0.0.0/0 | Dashboard behind tailnet plus basic auth, metrics on internal entrypoint, external scan |
| Health check green, users angry | /up touches no dependencies |
Dependency-aware health route plus post-deploy exception gate |
| Rollback impossible | Only mutable tags were published | Immutable tags from day one, tested quarterly |
| Backups "configured" for a year | Sidecar pointed at a hostname that no longer resolved | Staleness alert, restore drill |
| TLS warning quietly ignored | ACME token missing a scope, origin fell back to self-signed | Issuer check in the proof table |
| The agent "fixed" the whitelist | Whitelist widened during an incident and never narrowed | Canary that proves whitelist still discriminates |
| Config drift everywhere | Some apps on Doppler, some on .env, docs describing a third setup | One documented config source per app, drift check |
| Missing docs, repeated work | The deploy worked but nothing was written down | DEPLOY.md, AGENTS.md, AAR required for done |
Handoff: what the next agent needs
Three files make an app self-operable. Write them the day you deploy, not after the first incident.
DEPLOY.md
# Deploying app
## What this is
One paragraph: what the app does, which box it runs on, which domain.
## Pipeline
Tag vX.Y.Z on main triggers CI, which builds web and worker images, pushes them
to the registry, and runs deploy.sh on the host. Deploys never build on the host.
## Deploy
Tag and push, watch CI, then verify:
curl -fsS https://app.example.com/up
curl -s -o /dev/null -w '%{http_code}' https://app.example.com/
## Rollback
cd /srv/app && ./deploy.sh --rollback vX.Y.Z
## Restore
Latest backups live in /srv/app/backups. Restore drill:
<commands>
## Alerts
ntfy topic, Nightwatch project, who gets paged.
## Where secrets live
Doppler project/config, host .env path, mode 600. Never in git.
AGENTS.md (repo root)
The deploy section is the part that matters. Keep it short enough that an agent reads it.
## Deploy
- CI: .crow/build-push.yml, tag v* only, manual re-run allowed.
- Images: ${REGISTRY}/${ORG}/${APP}:web and :worker.
- Host: deploy@${VPS_IP}, stack /srv/app. Deploy key is forced-command.
- Never build on the host. Never deploy latest. Never skip migrations.
- Before migrate: confirm a backup. After deploy: /up must be 2xx.
- Rollback: ./deploy.sh --rollback vX.Y.Z
AAR
One page, after any non-trivial session. Scope, what worked, what broke, root causes, changes applied, verification, follow-ups. This is the artifact that stops a failure from repeating across apps, because the next agent reads it before touching a similar stack.
The maintenance loop
Deployment is a moment. Operations is a loop. Put these on a calendar and let the agent run them monthly.
- Monthly: backup restore drill into a throwaway container; certificate expiry check; dashboard and metrics exposure scan from outside; firewall rules still Cloudflare-only; disk usage and log rotation; dependency update PRs; secret rotation list; documentation drift review.
- Quarterly: rollback drill on a low-risk app; restore a full stack from scratch using only the docs; review CrowdSec decisions and whitelist canary; review alerts that fired and did not fire.
- After every incident: AAR, runbook update, one guardrail added if a human or agent could have prevented it.
Human approval points
An agent can do almost all of this alone. These are the moments where a human says yes or no, because the failure mode is not local to one app.
- DNS and Cloudflare account changes.
- Anything that deletes or truncates production data.
- Publishing a new public endpoint (a port, a route, a dashboard).
- Changing the deploy key scope or CI secrets.
- Changing the base image, runtime, or database engine major version.
- Any deploy without a tested rollback path.
Everything else, the agent should just do, verify, and report.
Failure modes
- Confident summary, no evidence. The agent reports success in prose. Fix: require the proof table and reject summaries without output.
- Guardrail amnesia. A long task buries the constraints from the top of the prompt. Fix: keep the constraint list short and repeat the stop conditions at every phase boundary.
- Context drift. The agent changes a file it was not asked to touch. Fix: explicit write scopes, one change per deploy, diff review before applying.
- Handoff gap. The deployment works but nothing is written down. Fix: the definition of done includes the handoff docs.
Checklist
- Fact sheet complete
- Prompt template used, including stop conditions
- Guardrails acknowledged in the plan
- Proof table filled with real output
- Rollback stated before deploy
- Handoff docs updated
- AAR written for any surprise
- Maintenance loop scheduled
The closing rule
The next agent will not remember this conversation. It will read the repo, the deploy script, and the docs. If those are good, it can deploy securely and roll back correctly. If they are bad, it will improvise, and improvisation on production infrastructure is how every story in the failure-modes table started.
Write for that next agent. It might be you, six months from now, at 3 AM, with no context and a green CI run that lies.
Proof you are done
- - The fact sheet is complete and every unknown row was answered by a human, not guessed.
- - The prompt used names the non-negotiable constraints, the plan, and the stop conditions.
- - Every claim in the report is backed by a command and its real output, not a summary.
- - The proof table is filled, including the origin-blocked and certificate-issuer rows.
- - The rollback command is written before the deploy starts.
- - `DEPLOY.md`, `AGENTS.md`, and the latest AAR exist and match the running system.