Start and manage tmux-backed dev servers exposed through Caddy at wildcard subdomains.
Start a dev server in a tmux session and expose it via Caddy at <project>.YOUR_DOMAIN. One command up, one command down.
Install the script:
cp scripts/dev-serve.sh ~/.local/bin/dev-serve
chmod +x ~/.local/bin/dev-serve
Set your domain (one of):
DEV_SERVE_DOMAIN in your shell profileDOMAIN variable in the scriptRequirements:
tmux, jq, curllocalhost:2019dev-serve up <repo-path> [port] # Start dev server + add Caddy route
dev-serve down <name> # Stop dev server + remove Caddy route
dev-serve ls # List active dev servers
dev-serve restart <name> # Restart dev server (keep Caddy route)
~/projects/myapp → myapp.YOUR_DOMAIN)package.json scripts.dev (supports vite, next, nuxt, sveltekit)allowedHosts if a vite config file existsdev-<name> with --host 0.0.0.0 --port <port># 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
| 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 |
allowedHostsVite 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.
Browser (Tailscale / LAN / etc.)
→ DNS: *.YOUR_DOMAIN → your server IP
→ Caddy (HTTPS with auto certs)
→ reverse_proxy localhost:<port>
→ Dev server (in tmux session)
Dev server not starting:
tmux attach -t dev-<name> # 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: