feat: support custom hosts with internal wildcard TLS

Author: BlankParticle

ARCHITECTURE.md

@@ -5,7 +5,7 @@
 `devwrap` is a local development CLI that:
 
 - Runs an app command with an assigned local app port.
-- Registers a host route like `myapp.localhost` in Caddy.
+- Registers a host route like `myapp.localhost` (or a custom `--host`) in Caddy.
 - Uses Caddy as the reverse proxy and TLS terminator.
 - Reuses any existing Caddy Admin API when available.
 - Spawns its own embedded Caddy wrapper daemon only when needed.
@@ -14,6 +14,7 @@ Core user run shape:
 
 ```bash
 devwrap --name myapp -- <command...>
+devwrap --name myapp --host myapp.dev.test -- <command...>
 ```
 
 Example:
@@ -94,15 +95,16 @@ devwrap --name=<app> -- <cmd...>
 Flow:
 
 1. Parse/validate app name (`[a-z0-9-]`, not leading/trailing `-`).
-2. Ensure Caddy Admin is available (unmanaged or managed).
-3. Acquire lease from file state and sync routes directly to Caddy Admin.
-4. Print HTTPS/HTTP URLs.
-5. Warn if Caddy local CA is not trusted.
-6. Run child command with:
+2. Resolve host (`--host` or default `<name>.localhost`) and validate hostname format.
+3. Ensure Caddy Admin is available (unmanaged or managed).
+4. Acquire lease from file state and sync routes directly to Caddy Admin.
+5. Print HTTPS/HTTP URLs.
+6. Warn if Caddy local CA is not trusted.
+7. Run child command with:
    - `PORT=<assigned-port>` in env
    - `DEVWRAP_APP=<name>` in env
    - `@PORT` token replacement in argv
-7. Forward signals to child; release lease on exit.
+8. Forward signals to child; release lease on exit.
 
 ### Proxy Commands
 
@@ -179,7 +181,7 @@ Special handling:
 For each app, route created with:
 
 - `@id: devwrap-<app-name>`
-- host match: `<app>.localhost`
+- host match: app host from state (`--host` override or `<app>.localhost`)
 - handler: reverse proxy to `127.0.0.1:<app-port>`
 
 Route update behavior:
@@ -194,7 +196,7 @@ This preserves non-devwrap routes while replacing devwrap-managed entries.
 
 ## TLS + Trust
 
-Embedded Caddy is configured with internal issuer for `localhost` and `*.localhost`.
+Embedded Caddy is configured with internal issuer for all subjects, so custom hosts still use devwrap's local CA.
 
 For managed mode, embedded Caddy is configured with explicit file-system storage root so CA material is reusable:
 

README.md

@@ -1,6 +1,6 @@
 # devwrap
 
-Run local app commands behind Caddy with friendly localhost hostnames.
+Run local app commands behind Caddy with friendly local hostnames.
 
 ## Install
 
@@ -22,12 +22,20 @@ curl -fsSL https://raw.githubusercontent.com/iterate/devwrap/main/install.sh | b
 devwrap --name myapp -- pnpm dev
 ```
 
+Use a custom host when needed:
+
+```bash
+devwrap --name web --host web.dev.test -- pnpm dev
+```
+
 Use `@PORT` when your app expects a CLI flag instead of env vars:
 
 ```bash
 devwrap --name dev-server -- vite dev --port @PORT
 ```
 
+By default hosts are `<name>.localhost`.
+
 `devwrap` also sets `PORT=<allocated port>`, `DEVWRAP_APP=<name>`, and `DEVWRAP_HOST=<https url>` for the child process.
 
 ## Proxy Modes

cmd/devwrap/cli.go

@@ -20,13 +20,14 @@ func run(args []string) error {
 
 func newRootCommand() *cobra.Command {
 	var name string
+	var host string
 	var privileged bool
 
 	root := &cobra.Command{
 		Use:           "devwrap --name <name> -- <cmd...>",
 		Short:         "Local dev reverse proxy helper",
-		Long:          "Run local apps behind Caddy and map <name>.localhost. Use @PORT in your command arguments to inject the allocated app port.",
-		Example:       "  devwrap --name myapp -- pnpm dev\n  devwrap --name api -- uvicorn app:app --port @PORT\n  devwrap -p",
+		Long:          "Run local apps behind Caddy and map routes to local app ports. Use @PORT in your command arguments to inject the allocated app port.",
+		Example:       "  devwrap --name myapp -- pnpm dev\n  devwrap --name api -- uvicorn app:app --port @PORT\n  devwrap --name web --host web.dev.test -- pnpm dev\n  devwrap -p",
 		SilenceUsage:  true,
 		SilenceErrors: true,
 		Args:          cobra.ArbitraryArgs,
@@ -46,7 +47,7 @@ func newRootCommand() *cobra.Command {
 				}
 				return errors.New("missing command after '--'")
 			}
-			return runApp(name, args, privileged)
+			return runApp(name, host, args, privileged)
 		},
 	}
 
@@ -62,6 +63,7 @@ func newRootCommand() *cobra.Command {
 	})
 
 	root.Flags().StringVar(&name, "name", "", "App route name (e.g. myapp)")
+	root.Flags().StringVar(&host, "host", "", "Custom hostname (default: <name>.localhost)")
 	root.Flags().BoolVarP(&privileged, "privileged", "p", false, "Use sudo to spawn proxy if Caddy is not already running")
 	root.PersistentFlags().BoolVar(&outputJSON, "json", false, "Output JSON for scripting")
 
@@ -143,16 +145,21 @@ func helpOnArgValidationError(next cobra.PositionalArgs) cobra.PositionalArgs {
 	}
 }
 
-func runApp(name string, cmdArgs []string, privileged bool) error {
+func runApp(name, host string, cmdArgs []string, privileged bool) error {
 	if err := validateName(name); err != nil {
 		return err
 	}
 
+	resolvedHost, err := hostForApp(name, host)
+	if err != nil {
+		return err
+	}
+
 	if err := ensureCaddyOrDaemon(privileged); err != nil {
 		return err
 	}
 
-	lease, err := acquireLease(name, os.Getpid())
+	lease, err := acquireLease(name, resolvedHost, os.Getpid())
 	if err != nil {
 		if checkDaemonReachable() {
 			if path, logErr := daemonLogPath(); logErr == nil {

cmd/devwrap/client.go

@@ -31,8 +31,8 @@ func apiClient() *http.Client {
 	return adminHTTPClient
 }
 
-func acquireLease(name string, pid int) (Lease, error) {
-	return requestLeaseDirect(name, pid)
+func acquireLease(name, host string, pid int) (Lease, error) {
+	return requestLeaseDirect(name, host, pid)
 }
 
 func releaseLeaseSelected(name string, pid int) {

cmd/devwrap/host.go

@@ -0,0 +1,51 @@
+package main
+
+import (
+	"errors"
+	"strings"
+)
+
+func hostForApp(name, customHost string) (string, error) {
+	if customHost == "" {
+		return name + ".localhost", nil
+	}
+	host, err := normalizeHost(customHost)
+	if err != nil {
+		return "", err
+	}
+	return host, nil
+}
+
+func normalizeHost(raw string) (string, error) {
+	host := strings.ToLower(strings.TrimSpace(raw))
+	if host == "" {
+		return "", errors.New("host cannot be empty")
+	}
+	if strings.Contains(host, "://") {
+		return "", errors.New("host must be a hostname without scheme")
+	}
+	if strings.Contains(host, "/") {
+		return "", errors.New("host must not include a path")
+	}
+	if strings.Contains(host, ":") {
+		return "", errors.New("host must not include a port")
+	}
+	if strings.HasPrefix(host, ".") || strings.HasSuffix(host, ".") || strings.Contains(host, "..") {
+		return "", errors.New("host format is invalid")
+	}
+	for _, label := range strings.Split(host, ".") {
+		if label == "" {
+			return "", errors.New("host format is invalid")
+		}
+		if label[0] == '-' || label[len(label)-1] == '-' {
+			return "", errors.New("host labels cannot start or end with '-'")
+		}
+		for _, r := range label {
+			if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '-' {
+				continue
+			}
+			return "", errors.New("host can use lowercase letters, numbers, dots, and dashes")
+		}
+	}
+	return host, nil
+}

cmd/devwrap/local_state.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"sort"
 	"strconv"
+	"strings"
 	"time"
 )
 
@@ -114,21 +115,30 @@ func localStatusFromFiles() (ProxyStatus, error) {
 	return out, nil
 }
 
-func requestLeaseDirect(name string, pid int) (Lease, error) {
+func requestLeaseDirect(name, host string, pid int) (Lease, error) {
 	var lease Lease
 	err := withStateLock(func() error {
 		state, err := loadLocalState()
 		if err != nil {
 			return err
 		}
+		appHost, err := hostForApp(name, host)
+		if err != nil {
+			return err
+		}
 		for appName, app := range state.Apps {
 			if !processAlive(app.PID) {
 				delete(state.Apps, appName)
+				continue
+			}
+			if appName != name && strings.EqualFold(app.Host, appHost) {
+				return fmt.Errorf("host %q is already used by app %q", appHost, appName)
 			}
 		}
 
 		app, ok := state.Apps[name]
 		if ok {
+			app.Host = appHost
 			app.PID = pid
 			app.StartedAt = time.Now().UTC().Format(time.RFC3339)
 		} else {
@@ -138,7 +148,7 @@ func requestLeaseDirect(name string, pid int) (Lease, error) {
 			}
 			app = App{
 				Name:      name,
-				Host:      name + ".localhost",
+				Host:      appHost,
 				Port:      port,
 				PID:       pid,
 				StartedAt: time.Now().UTC().Format(time.RFC3339),

cmd/devwrap/proxy_caddy.go

@@ -38,8 +38,7 @@ func startEmbeddedCaddy(httpPort, httpsPort int) error {
 			"tls": map[string]any{
 				"automation": map[string]any{
 					"policies": []map[string]any{{
-						"subjects": []string{"localhost", "*.localhost"},
-						"issuers":  []map[string]any{{"module": "internal"}},
+						"issuers": []map[string]any{{"module": "internal"}},
 					}},
 				},
 			},