AI Agents Guide (Autonomous Deployments)

How AI coding agents (Cursor, Windsurf, Claude Code, Cline, Roo, Copilot, Antigravity) use EPD to provision servers and deploy applications autonomously.

---

The Philosophy: Why CLI & curl > MCP for Deployments

Many platforms attempt to build heavy MCP (Model Context Protocol) servers for deployments. We deliberately chose not to do this.

Here is why a clean CLI and raw curl is a strictly superior abstraction for AI coding agents:

1. Native Shell Capabilities: Modern AI coding models (Claude 3.7 / Sonnet, OpenAI o3, Gemini, DeepSeek) are exceptionally skilled at running shell commands via their native terminal tools (bash, run_command).
2. Zero MCP Configuration Bloat: MCP requires installing daemon processes, registering JSON configurations (.cursor/mcp.json, claude_desktop_config.json), handling Node.js socket bridges, and debugging RPC schema mismatches. A CLI requires zero setup:

   curl -fsSL https://epd.peppi.dev/install.sh | bash

3. Universal Portability: The exact same commands work in Cursor, Windsurf, Claude Code, GitHub Actions CI/CD, local terminals, and remote SSH jump boxes without installing specialized tool plugins.
4. Machine-Readable Output: EPD provides structured flags like --json (epd status --json), predictable exit codes (0 = success, 1 = config, 2 = network, 3 = healthcheck timeout), and clean stdout/stderr streams that LLMs parse with near 100% accuracy.

---

LLM Documentation Feeds (llms.txt)

AI agents do not need to scrape HTML pages or navigate complex client-rendered web apps. EPD provides standardized, token-efficient, plain-markdown feeds:

Endpoint	Description	Command
/llms.txt	Concise index of core documentation & CLI commands	curl -s https://epd.peppi.dev/llms.txt
/llms-full.txt	Complete single-file markdown reference with full schema & recipes	curl -s https://epd.peppi.dev/llms-full.txt

If an AI agent needs to understand how a specific EPD command or epd.yml property works, instruct it to fetch:

curl -s https://epd.peppi.dev/llms.txt

---

Agent System Prompt Snippet

You can copy and paste this snippet directly into your project's .cursorrules, CLAUDE.md, or AGENTS.md file:

### Deployment & Server Operations (EPD)
When asked to deploy, inspect, or manage server infrastructure:
1. Always use the `epd` CLI (`curl -fsSL https://epd.peppi.dev/install.sh | bash` if not installed).
2. For documentation lookups, fetch raw markdown directly from:
   - `curl -s https://epd.peppi.dev/llms.txt`
   - `curl -s https://epd.peppi.dev/llms-full.txt`
3. Before deploying, run `epd doctor --local` to validate `epd.yml` and container settings.
4. Deploy with `epd deploy`. EPD performs zero-downtime blue/green container switching fronted by Traefik.
5. Verify deployment health using `epd status --json`.
6. If a deployment fails or health checks timeout, execute `epd rollback` to revert traffic instantly.

---

Automated AI Agent Playbook

Here is the standard 5-step lifecycle an AI agent should execute when deploying a repository:

1. Initialize Project Configuration

If epd.yml does not exist in the repository, the agent should run epd init non-interactively:

epd init \
  --name "my-saas" \
  --host "159.69.120.45" \
  --domain "app.example.com" \
  --port 3000 \
  --dockerfile

This creates an optimized multi-stage Dockerfile (if absent) and an epd.yml configured for zero-downtime blue/green deployments.

2. Pre-flight Validation

The agent validates local tooling, Dockerfile syntax, and environment configurations without initiating remote SSH connections:

epd doctor --local
epd config

3. Server Provisioning (Clean VPS)

If deploying to a fresh Ubuntu or Debian server for the first time, the agent provisions Docker, Traefik, Let's Encrypt, and CrowdSec security with one command:

epd setup --host 159.69.120.45

4. Zero-Downtime Deployment

The agent triggers the build and live cutover:

epd deploy

During this command:

• EPD builds the container on the target server.
• Boots the new container slot (e.g. green).
• Probes /health repeatedly until HTTP 200 OK is received.
• Hot-swaps Traefik routing dynamically without dropping a single active HTTP connection.
• Drains and stops the old slot (blue).

5. Verification & JSON Parsing

The agent inspects the running cluster state in machine-readable JSON:

epd status --json

Example JSON response:

{
  "project": "my-saas",
  "activeSlot": "green",
  "activeVersion": "v1.2.4",
  "domain": "app.example.com",
  "ssl": "active",
  "slots": {
    "green": { "status": "running", "replicas": 2, "healthy": true, "port": 3001 },
    "blue": { "status": "stopped", "replicas": 0, "healthy": false, "port": 3000 }
  },
  "accessories": {
    "postgres": { "status": "healthy", "port": 5432 }
  }
}

If issues are detected:

# View last 50 log lines
epd logs -n 50

# Revert immediately to previous working slot
epd rollback

---

Exit Codes Reference for Scripting

AI agents should evaluate standard shell exit codes ($?):

Exit Code	Meaning	Agent Action
0	Success	Continue task or report deployment URL.
1	Configuration Error	Read error output, inspect epd.yml or Dockerfile, fix syntax.
2	SSH / Network Failure	Check server IP, SSH key permissions (chmod 600 ~/.ssh/id_rsa), or firewall.
3	Healthcheck Timeout	Check application logs (epd logs -n 50), verify internal port and /health route. Run epd rollback.
4	Deployment Lock Active	Another deployment is in progress. Inspect lock with epd lock status.