How do I install the Caddy skill?

Run npx skillmds@latest add muninn-huginn/caddy in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Caddy safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Caddy?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Caddy free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

muninn-huginn (@muninn-huginn) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Caddy by muninn-huginn — Agent Skill

Name: Caddy
Author: muninn-huginn

Caddy

Manage local development proxies using Caddy server's Admin API. Use when users need to allocate localhost ports, create reverse proxies for local dev servers, track which ports are in use across Claude Code sessions, or access apps via friendly URLs like myapp.localhost. Triggers on "set up a proxy", "allocate a port", "what's running on localhost", "register my app", or any Caddy configuration task.

File contents

Caddy Local Proxy Manager

Manage local development reverse proxies via Caddy's Admin API at localhost:2019.

Session Naming

When registering a proxy, use one of these approaches:

User provides name: Use exactly what they specify
Generate from context: Use project directory name + short random suffix (e.g., myapp-x7k2)

Example generation:

NAME="$(basename "$PWD" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g')-$(head -c4 /dev/urandom | xxd -p | head -c4)"

Quick Reference

Task	Command
Check status	`curl -sf http://localhost:2019/config/`
List routes	`curl -sf http://localhost:2019/config/apps/http/servers/local_proxies/routes`
Add route	`POST /config/apps/http/servers/local_proxies/routes`
Delete route	`DELETE /id/proxy_<name>`

Workflows

Check Caddy Status

curl -sf http://localhost:2019/config/ 2>/dev/null

If fails: "Caddy not running. Install: brew install caddy, Start: caddy start"

List All Proxies

curl -sf http://localhost:2019/config/apps/http/servers/local_proxies/routes 2>/dev/null

Display as table: Name | URL | Backend

Register a Proxy

Get or generate name (ask user or generate from project + random)
Find available port (if not specified):

for port in $(seq 3000 3100); do
  lsof -i :$port > /dev/null 2>&1 || { echo $port; break; }
done

Initialize server if needed:

curl -sf http://localhost:2019/config/apps/http/servers/local_proxies > /dev/null 2>&1 || \
curl -sf -X POST http://localhost:2019/load \
  -H "Content-Type: application/json" \
  -d '{"apps":{"http":{"servers":{"local_proxies":{"listen":[":80"],"routes":[]}}}}}'

Add route (replace NAME and PORT):

curl -sf -X POST "http://localhost:2019/config/apps/http/servers/local_proxies/routes" \
  -H "Content-Type: application/json" \
  -d '{"@id":"proxy_NAME","match":[{"host":["NAME.localhost"]}],"handle":[{"handler":"reverse_proxy","upstreams":[{"dial":"localhost:PORT"}]}],"terminal":true}'

Report: "Registered: http://NAME.localhost → localhost:PORT"

Remove a Proxy

curl -sf -X DELETE "http://localhost:2019/id/proxy_NAME"

Update a Proxy

Delete then re-add with new port.

Route JSON Structure

{
  "@id": "proxy_<name>",
  "match": [{"host": ["<name>.localhost"]}],
  "handle": [{"handler": "reverse_proxy", "upstreams": [{"dial": "localhost:<port>"}]}],
  "terminal": true
}

Error Handling

Error	Solution
Caddy not running	`brew install caddy && caddy start`
Port 80 denied	`sudo caddy start`
Route exists	Ask to update or pick different name

Platform Notes

macOS: *.localhost resolves to 127.0.0.1 automatically
Linux: May need /etc/hosts entries

---name: caddydescription: Manage local development proxies using Caddy server's Admin API. Use when users need to allocate localhost ports, create reverse proxies for local dev servers, track which ports are in use across Claude Code sessions, or access apps via friendly URLs like myapp.localhost. Triggers on "set up a proxy", "allocate a port", "what's running on localhost", "register my app", or any Caddy configuration task.---# Caddy Local Proxy ManagerManage local development reverse proxies via Caddy's Admin API at `localhost:2019`.## Session NamingWhen registering a proxy, use one of these approaches:1. **User provides name**: Use exactly what they specify2. **Generate from context**: Use project directory name + short random suffix (e.g., `myapp-x7k2`)Example generation:```bashNAME="$(basename "$PWD" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g')-$(head -c4 /dev/urandom | xxd -p | head -c4)"```## Quick Reference| Task | Command ||------|---------|| Check status | `curl -sf http://localhost:2019/config/` || List routes | `curl -sf http://localhost:2019/config/apps/http/servers/local_proxies/routes` || Add route | `POST /config/apps/http/servers/local_proxies/routes` || Delete route | `DELETE /id/proxy_<name>` |## Workflows### Check Caddy Status```bashcurl -sf http://localhost:2019/config/ 2>/dev/null```If fails: "Caddy not running. Install: `brew install caddy`, Start: `caddy start`"### List All Proxies```bashcurl -sf http://localhost:2019/config/apps/http/servers/local_proxies/routes 2>/dev/null```Display as table: Name | URL | Backend### Register a Proxy1. **Get or generate name** (ask user or generate from project + random)2. **Find available port** (if not specified):```bashfor port in $(seq 3000 3100); do lsof -i :$port > /dev/null 2>&1 || { echo $port; break; }done```3. **Initialize server if needed**:```bashcurl -sf http://localhost:2019/config/apps/http/servers/local_proxies > /dev/null 2>&1 || \curl -sf -X POST http://localhost:2019/load \ -H "Content-Type: application/json" \ -d '{"apps":{"http":{"servers":{"local_proxies":{"listen":[":80"],"routes":[]}}}}}'```4. **Add route** (replace NAME and PORT):```bashcurl -sf -X POST "http://localhost:2019/config/apps/http/servers/local_proxies/routes" \ -H "Content-Type: application/json" \ -d '{"@id":"proxy_NAME","match":[{"host":["NAME.localhost"]}],"handle":[{"handler":"reverse_proxy","upstreams":[{"dial":"localhost:PORT"}]}],"terminal":true}'```5. **Report**: "Registered: http://NAME.localhost → localhost:PORT"### Remove a Proxy```bashcurl -sf -X DELETE "http://localhost:2019/id/proxy_NAME"```### Update a ProxyDelete then re-add with new port.## Route JSON Structure```json{ "@id": "proxy_<name>", "match": [{"host": ["<name>.localhost"]}], "handle": [{"handler": "reverse_proxy", "upstreams": [{"dial": "localhost:<port>"}]}], "terminal": true}```## Error Handling| Error | Solution ||-------|----------|| Caddy not running | `brew install caddy && caddy start` || Port 80 denied | `sudo caddy start` || Route exists | Ask to update or pick different name |## Platform Notes- **macOS**: `*.localhost` resolves to 127.0.0.1 automatically- **Linux**: May need `/etc/hosts` entries

Frequently asked questions