Getting started

PrerequisitesCopy Anchor Link

• Go 1.26 or newer and Just to build the CLI. Node.js 22 or newer and npm are needed when rebuilding the dashboard.
• A service that listens on a host TCP port. Containerized services must publish that port to the host.

The CLI binary has no Node.js runtime dependency. Node.js is also used to develop this documentation site.

Build the CLICopy Anchor Link

From the devproxy repository:

just build

Use just go to build from the checked-in dashboard assets without Node.js. Use bin/devproxy in the commands below, or put the binary on your PATH and use devproxy.

To install or update from this checkout, run just install. It rebuilds the dashboard and binary, then installs devproxy to ~/.local/bin. Make sure that directory is on your PATH. Set DEVPROXY_INSTALL_DIR to use another writable directory. Restart a running daemon with devproxy stop and devproxy start after updating.

Start the proxy and daemonCopy Anchor Link

Start the shared background daemon once. It runs Caddy in the same process, with its admin endpoint disabled:

bin/devproxy start

The command returns when Caddy and the control API are ready. The daemon continues after the terminal closes and serves all your projects. Check it with bin/devproxy status, stop it with bin/devproxy stop, or use bin/devproxy serve to run it in the foreground. HTTPS listens on host loopback port 443, so stop any other local proxy using that port first. On Linux systems that restrict privileged ports, grant the built binary permission to bind port 443 before starting it:

sudo setcap cap_net_bind_service=+ep "$(realpath bin/devproxy)"

If you used just install, apply the capability to $(command -v devproxy) instead of bin/devproxy. Reapply it after each update. The embedded mode is an evolutionary prototype; it does not start automatically at login or migrate the existing Docker certificate authority.

Use an external CaddyCopy Anchor Link

An existing dedicated Caddy instance is still supported with --caddy-admin. Devproxy replaces that instance's configuration, so do not use one serving unrelated sites.

On Docker Desktop for macOS, run:

just serve-desktop

This uses a bridge network and publishes Caddy's ports only on the host loopback address. Keep serve running, or start Caddy separately and use bin/devproxy start --caddy-admin http://127.0.0.1:2019 --docker-desktop. On Linux Docker Engine or macOS OrbStack, use host networking instead:

docker compose -f caddy/compose.yml up -d
bin/devproxy start --caddy-admin http://127.0.0.1:2019

You can also run Caddy natively with the included caddy/Caddyfile and pass --caddy-admin http://127.0.0.1:2019 to start.

Open https://devproxy.localhost for the dashboard. If your browser does not yet trust Caddy's local certificate, follow Trust local HTTPS.

Register a development serviceCopy Anchor Link

Run this from the service's Git worktree. --project is a stable project name; the worktree folder supplies the instance name.

bin/devproxy run --project example web -- next dev -p '{port}'

run picks a free port, sets PORT and DEVPROXY_URL, replaces {port} in command arguments, waits for the port to listen, and registers its route. Keep the command running while you need the URL. Open https://example-<worktree-folder>.localhost.

For a service that is already listening on port 3001, keep a separate registration command running:

bin/devproxy register --project example --port 3001 api

Check active URLs with bin/devproxy list or the dashboard. See CLI reference for all flags and Routes and URLs for multiple services on one origin.

Trust local HTTPSCopy Anchor Link

Embedded Caddy keeps its local certificate authority under the user config directory in devproxy/caddy. On macOS, if the first HTTPS request still shows an untrusted certificate, trust its root:

security add-trusted-cert -d -r trustRoot -k "$HOME/Library/Keychains/login.keychain-db" "$HOME/Library/Application Support/devproxy/caddy/pki/authorities/local/root.crt"

For the external Docker mode, the Compose volume retains a separate Caddy authority. After its first HTTPS request, copy and trust that root:

docker compose -f caddy/compose.desktop.yml cp caddy:/data/caddy/pki/authorities/local/root.crt ./devproxy-root.crt
security add-trusted-cert -d -r trustRoot -k "$HOME/Library/Keychains/login.keychain-db" ./devproxy-root.crt

The trust command may ask for your macOS password. On Linux, use caddy/compose.yml in the copy command and add the root certificate to your system or browser trust store using your distribution's process. The copied certificate is ignored by this repository's Git configuration.