devwrap

Run local app commands behind Caddy with friendly local hostnames.

Install

Install latest release:

curl -fsSL https://raw.githubusercontent.com/iterate/devwrap/main/install.sh | bash

Install a specific release:

curl -fsSL https://raw.githubusercontent.com/iterate/devwrap/main/install.sh | bash -s -- -v 0.0.2

Quick Start

devwrap --name myapp -- pnpm dev

Use a custom host when needed:

devwrap --name web --host web.dev.test -- pnpm dev

Use @PORT when your app expects a CLI flag instead of env vars:

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

• unmanaged caddy: Caddy is already running on admin API 127.0.0.1:2019
• managed caddy: started by devwrap proxy start

Start managed Caddy:

devwrap proxy start

Privileged start (bind 80/443 if available):

devwrap proxy start -p

Shortcut: devwrap -p starts managed proxy when no --name + command are provided.

Common Commands

devwrap proxy status
devwrap proxy trust
devwrap proxy stop
devwrap ls
devwrap rm <name>
devwrap doctor

All commands support --json for scriptable output.

Examples:

devwrap proxy status --json
devwrap ls --json
devwrap --json --name api -- uvicorn app:app --port @PORT

Trust

devwrap proxy trust fetches the local CA root from Caddy admin API and installs trust using the same truststore approach used by Caddy.

For Node.js clients (fetch, undici, axios over HTTPS), you may also need to enable CA trust in Node:

• Newer Node versions: set NODE_USE_SYSTEM_CA=1 so Node uses system trust.
• Older Node versions (or as a fallback): set NODE_EXTRA_CA_CERTS to Caddy's local root cert path.

Caddy local root cert path is resolved from the Caddy data dir in this order:

• $DEVWRAP_CADDY_DATA_DIR (if set)
• else $CADDY_DATA_DIR (if set)
• else platform default Caddy data dir (macOS: ~/Library/Application Support/Caddy, Linux: ~/.local/share/caddy)

Append pki/authorities/local/root.crt to the selected data dir.

Example:

# Newer Node
export NODE_USE_SYSTEM_CA=1

# Older Node / fallback (macOS)
export NODE_EXTRA_CA_CERTS="$HOME/Library/Application Support/Caddy/pki/authorities/local/root.crt"

# Older Node / fallback (Linux)
export NODE_EXTRA_CA_CERTS="$HOME/.local/share/caddy/pki/authorities/local/root.crt"

Runtime Files

State is stored in:

• $XDG_STATE_HOME/devwrap
• fallback: ~/.local/state/devwrap

Files:

• state.json
• state.lock
• daemon.pid
• daemon.log

Development

Build + install from local source (dev flow):

./install-dev.sh

Source code lives in cmd/devwrap.

Build locally with:

/usr/local/go/bin/go build ./cmd/devwrap