cp scripts/dev-serve.sh ~/.local/bin/dev-serve
chmod +x ~/.local/bin/dev-serve

dev-serve up  [port] # 启动开发服务器 + 添加 Caddy 路由
dev-serve down  # 停止开发服务器 + 移除 Caddy 路由
dev-serve ls # 列出活动的开发服务器
dev-serve restart  # 重启开发服务器（保留 Caddy 路由）

# 使用自动分配的端口启动（从 5200 开始，跳过已用端口）
dev-serve up ~/projects/myapp # → https://myapp.YOUR_DOMAIN
# 指定端口
dev-serve up ~/projects/myapp 5200
# 覆盖开发命令
DEV_CMD="bun dev" dev-serve up ~/projects/myapp 5300
# 停止并清理
dev-serve down myapp
# 列出正在运行的内容
dev-serve ls

浏览器（Tailscale / LAN 等）→ DNS: *.YOUR_DOMAIN → 您的服务器 IP → Caddy（自动证书的 HTTPS）→ reverse_proxy localhost: → 开发服务器（在 tmux 会话中）

tmux attach -t dev- # 查看发生了什么

caddy reload --config ~/.config/caddy/Caddyfile --address localhost:2019

server: { allowedHosts: ['myapp.YOUR_DOMAIN'] }

Start a dev server in a tmux session and expose it via Caddy at .YOUR_DOMAIN. One command up, one command down.

Setup

• Install the script:

   cp scripts/dev-serve.sh ~/.local/bin/dev-serve
   chmod +x ~/.local/bin/dev-serve
   

• Set your domain (one of):

- Export DEV_SERVE_DOMAIN in your shell profile - Or edit the DOMAIN variable in the script

• Requirements:

- Caddy running with wildcard DNS + TLS (see caddy skill) - tmux, jq, curl - Caddy admin API on localhost:2019

CLI

dev-serve up  [port]      # Start dev server + add Caddy route
dev-serve down                 # Stop dev server + remove Caddy route
dev-serve ls                         # List active dev servers
dev-serve restart              # Restart dev server (keep Caddy route)

How It Works

• Derives subdomain from the repo folder name (~/projects/myapp → myapp.YOUR_DOMAIN)
• Detects the dev command from package.json scripts.dev (supports vite, next, nuxt, sveltekit)
• Auto-patches Vite allowedHosts if a vite config file exists
• Starts the dev server in a tmux session named dev- with --host 0.0.0.0 --port
• Adds a Caddy route + dashboard link to the Caddyfile
• Reloads Caddy via admin API (no sudo, no restart)
• Verifies end-to-end: waits for the dev server to listen, then polls HTTPS until 2xx/3xx (up to 90s)

Examples

# Start with auto-assigned port (starts at 5200, skips used ports)
dev-serve up ~/projects/myapp
# → https://myapp.YOUR_DOMAIN
# Explicit port
dev-serve up ~/projects/myapp 5200
# Override dev command
DEV_CMD="bun dev" dev-serve up ~/projects/myapp 5300
# Stop and clean up
dev-serve down myapp
# List what's running
dev-serve ls

Configuration

Variable	Default	Description
DEV_SERVE_DOMAIN	(must be set)	Your wildcard domain (e.g. mini.example.com)
DEV_SERVE_STATE_DIR	~/.config/dev-serve	Where state JSON is stored
CADDYFILE	~/.config/caddy/Caddyfile	Path to your Caddyfile
CADDY_ADMIN	http://localhost:2019	Caddy admin API address
DEV_CMD	(auto-detected)	Override the dev server command

Port Convention

• Permanent services: 3100 range (managed in Caddyfile directly)
• Dev servers: 5200+ (managed by dev-serve, auto-assigned)

Vite allowedHosts

Vite blocks requests from unrecognized hostnames. dev-serve up automatically patches vite.config.ts (or .js/.mts/.mjs) to add the subdomain. If auto-patching fails, it prints the manual fix.

Architecture

Browser (Tailscale / LAN / etc.)
  → DNS: *.YOUR_DOMAIN → your server IP
    → Caddy (HTTPS with auto certs)
      → reverse_proxy localhost:
        → Dev server (in tmux session)

Companion Skills

• caddy — Required. Sets up the Caddy reverse proxy with wildcard TLS.

Troubleshooting

Dev server not starting:

tmux attach -t dev-    # see what happened

Cert not provisioning (curl exit 35): Wait 30-60s for DNS-01 challenge. Check tail -20 /var/log/caddy-error.log.

Caddy reload failed:

caddy reload --config ~/.config/caddy/Caddyfile --address localhost:2019

403 from Vite: The subdomain wasn't added to allowedHosts. Add it manually to your vite.config.ts:

server: { allowedHosts: ['myapp.YOUR_DOMAIN'] }