dev-serve

intent

spin up a dev server in a tmux session and expose it over HTTPS at <project>.YOUR_DOMAIN via Caddy reverse proxy. use this when you need a live dev environment accessible from outside localhost (tailscale, LAN, etc.) without manual DNS, TLS, or port forwarding. one command to launch, one to tear down.

inputs

environment variables:

• DEV_SERVE_DOMAIN (required): your wildcard domain, e.g. mini.example.com. must resolve to your server IP with wildcard DNS (*.mini.example.com).
• DEV_SERVE_STATE_DIR (optional, default ~/.config/dev-serve): where the skill stores state JSON (active servers list).
• CADDYFILE (optional, default ~/.config/caddy/Caddyfile): path to your Caddyfile.
• CADDY_ADMIN (optional, default http://localhost:2019): Caddy admin API endpoint.
• DEV_CMD (optional, auto-detected): override the dev server command. useful if auto-detection fails.

external connections:

• Caddy: must be running with wildcard DNS + TLS (delegated to caddy skill). skill reloads Caddy config via admin API, no sudo required.
• Caddy admin API: defaults to http://localhost:2019. ensure it's listening and accessible.

binary dependencies:

• tmux: session manager for dev servers.
• jq: JSON parsing for state and Caddy API responses.
• curl: HTTP requests to Caddy admin API and dev server healthchecks.
• node or compatible package manager: to read package.json and detect dev command.

local setup:

1. copy scripts/dev-serve.sh to ~/.local/bin/dev-serve and chmod +x.
2. set DEV_SERVE_DOMAIN in your shell profile (.bashrc, .zshrc, etc.) or export it inline.
3. ensure Caddy is running and admin API is accessible.
4. ensure ~/.config/dev-serve/ exists or is creatable (skill creates it if missing).

procedure

step 1: parse input and resolve repo path

• input: <repo-path> (e.g. ~/projects/myapp) and optional [port].
• expand ~ and relative paths to absolute path.
• extract subdomain name from the final directory: /home/user/projects/myapp → myapp.
• output: absolute path, subdomain name, domain (from DEV_SERVE_DOMAIN).

step 2: detect dev server command

• input: repo path, optional override DEV_CMD.
• if DEV_CMD is set, use it.
• else, read package.json in repo root, extract scripts.dev field.
• common fallbacks: if no dev script, check for dev:vite, dev:nuxt, dev:sveltekit, dev:next.
• if no dev script found, exit with error (user must provide DEV_CMD).
• output: dev command string (e.g. vite dev, next dev, npm run dev).

step 3: select or auto-assign port

• input: optional [port] argument, or none.
• if port provided, validate it (1-65535) and use it.
• if no port provided, auto-assign: scan from 5200 upward, check if port is in use via netstat or lsof, skip occupied ports, return first free port.
• output: port number (integer).

step 4: auto-patch Vite allowedHosts if needed

• input: repo path, subdomain name, domain.
• check if vite.config.ts, vite.config.js, vite.config.mts, or vite.config.mjs exists in repo root.
• if found, parse the config file for server.allowedHosts array.
• if the subdomain (e.g. myapp.YOUR_DOMAIN) is not already in the array, append it programmatically.
• if file is unreadable or config is non-standard, print a manual instruction and continue (do not block).
• output: success or manual instruction printed to stdout.

step 5: create tmux session and start dev server

• input: subdomain name, dev command, port.
• session name: dev-<subdomain>.
• check if session already exists; if yes, exit with error "server already running".
• create new tmux session: tmux new-session -d -s dev-<subdomain>.
• send dev command with --host 0.0.0.0 --port <port> flags injected (or equivalent for the framework).
• output: tmux session created, dev server process running in background.

step 6: poll for dev server to listen locally

• input: port, timeout (default 30 seconds).
• poll every 1 second: attempt nc -zv localhost <port> or curl http://localhost:<port> to check if port is accepting connections.
• if port opens within timeout, continue.
• if timeout expires, kill tmux session, print error, exit.
• output: dev server confirmed listening on localhost.

step 7: add Caddy reverse proxy route

• input: subdomain name, port, Caddyfile path, domain.
• append a new block to Caddyfile:

  <subdomain>.YOUR_DOMAIN {
    reverse_proxy localhost:<port>
  }
  

• output: Caddyfile updated with new route.

step 8: reload Caddy via admin API

• input: Caddyfile path, CADDY_ADMIN endpoint.
• POST to http://localhost:2019/load with the updated Caddyfile.
• parse response; on success (2xx), continue.
• on failure, print error details, remove the Caddyfile entry, kill tmux session, exit with error.
• output: Caddy config reloaded, new route live.

step 9: verify end-to-end (dev server HTTPS response)

• input: subdomain name, domain, timeout (default 90 seconds).
• poll every 2 seconds: curl -s -o /dev/null -w "%{http_code}" https://<subdomain>.YOUR_DOMAIN/.
• acceptable responses: 2xx, 3xx, or Connection Refused (dev server may not have a root endpoint).
• if any 2xx/3xx received, mark success.
• if 403, 404, Connection Refused after repeated attempts (indicates Caddy is serving but dev server not ready), continue waiting up to timeout.
• if 5xx or persistent failure after timeout, print error, clean up, exit.
• output: dev server confirmed accessible over HTTPS via subdomain.

step 10: save state and print success

• input: subdomain name, port, domain, pid of tmux session.
• append entry to state file (~/.config/dev-serve/servers.json):

  {
    "name": "<subdomain>",
    "port": <port>,
    "url": "https://<subdomain>.YOUR_DOMAIN",
    "started": "<ISO8601>",
    "tmux_session": "dev-<subdomain>"
  }
  

• print to stdout:

  ✓ dev-serve up: myapp on port 5200
    → https://myapp.YOUR_DOMAIN
  

• output: state persisted, user informed.

down command procedure:

1. input: subdomain name (e.g. myapp).
2. check state file for entry matching name.
3. if not found, exit with error.
4. kill tmux session: tmux kill-session -t dev-<subdomain>.
5. remove Caddy route from Caddyfile (delete the matching block).
6. reload Caddy via admin API.
7. remove entry from state file.
8. print ✓ dev-serve down: myapp.

ls command procedure:

1. read state file (~/.config/dev-serve/servers.json).
2. if empty or missing, print "no active dev servers".
3. else, iterate entries and print in table format: name | port | url | started.
4. output: formatted list to stdout.

restart command procedure:

1. input: subdomain name.
2. look up entry in state file.
3. if not found, exit with error.
4. kill tmux session: tmux kill-session -t dev-<subdomain>.
5. wait 2 seconds.
6. re-read dev command and port from state.
7. create new tmux session and start dev server (repeat steps 5-6 from "up" procedure).
8. poll for local listen (step 6).
9. skip Caddy update (route already exists).
10. verify HTTPS response (step 9).
11. print ✓ dev-serve restart: myapp.

decision points

if port is already in use:

• if auto-assigning, skip to next port.
• if user provided port, exit with error "port already in use".

if dev command cannot be auto-detected:

• print available scripts in package.json and error message.
• user must either add a dev script to package.json or set DEV_CMD environment variable.
• exit with error.

if Vite config auto-patch fails:

• print the manual fix (e.g. add allowedHosts: ['myapp.YOUR_DOMAIN'] to vite.config.ts).
• continue; dev server will start but user may see 403 errors until manually patched.

if tmux session already exists:

• exit with error " is already running (tmux session dev-)".
• user must run dev-serve restart <subdomain> or dev-serve down <subdomain> first.

if Caddy admin API is unreachable:

• print error and Caddy admin API endpoint that was attempted.
• exit; do not kill tmux session (leave it running for manual cleanup).
• hint: check if Caddy is running and admin API is on the expected endpoint.

if HTTPS healthcheck fails after 90 seconds:

• check if Caddy is serving 5xx errors (config issue) vs. dev server not responding (startup issue).
• if 5xx, remove Caddy route, kill tmux session, print error.
• if connection refused or timeout, print "dev server not responding; check tmux attach -t dev-<name>" and exit (leave tmux session for user inspection).

if DEV_SERVE_DOMAIN is not set:

• exit with error "DEV_SERVE_DOMAIN environment variable not set. set it or export in shell profile."

if state file is corrupted (invalid JSON):

• back up the corrupted file to servers.json.bak.
• initialize a new empty state file.
• print warning to stderr.
• continue (do not block).

output contract

up command:

• returns exit code 0 on success.
• stdout contains confirmation message and URL.
• state file (~/.config/dev-serve/servers.json) updated with new entry.
• Caddyfile appended with new route block.
• tmux session dev-<subdomain> created and running.

down command:

• returns exit code 0 on success.
• stdout contains confirmation message.
• tmux session killed.
• Caddyfile cleaned (route removed).
• state file entry removed.

ls command:

• returns exit code 0.
• stdout is table or list of active servers, or "no active dev servers" if empty.

restart command:

• returns exit code 0 on success.
• stdout contains confirmation message.
• tmux session killed and recreated.
• dev server running again on same port.
• Caddy route unchanged.

error cases:

• returns non-zero exit code.
• stderr contains human-readable error message.
• partial state not left behind (if up fails, tmux and Caddy entries cleaned up).

outcome signal

• you can visit https://<subdomain>.YOUR_DOMAIN in a browser (via tailscale, LAN, or public if DNS allows) and see your dev server running.
• dev-serve ls lists the active server with correct URL and port.
• tmux ls shows the dev-<subdomain> session active.
• curl -s https://<subdomain>.YOUR_DOMAIN -v returns 2xx/3xx or expected response from dev server (no 5xx, no cert errors).
• stopping with dev-serve down <subdomain> immediately removes the route; HTTPS access fails (Caddy 404).
• restarting with dev-serve restart <subdomain> does not change the URL or require DNS/TLS updates.