CLI reference

start, status, and stopCopy Anchor Link

devproxy start [--listen 127.0.0.1:7654] [--caddy-admin URL] [--docker-desktop]
devproxy status [--json] [--daemon http://127.0.0.1:7654]
devproxy stop [--daemon http://127.0.0.1:7654]

start launches the shared daemon in the background and waits until embedded Caddy and the control API are ready. Running it again reports the existing daemon. It stays active when the shell closes. Logs go to devproxy/daemon.log under the user cache directory. status reports its process ID; stop shuts down the daemon and its embedded Caddy. For a custom --listen address, pass its corresponding --daemon origin to status, stop, and service commands. Startup at login is not automatic.

serveCopy Anchor Link

devproxy serve [--listen 127.0.0.1:7654] [--caddy-admin URL] [--docker-desktop]

Runs embedded Caddy, the local dashboard, and the control API in the foreground. The control listener must use 127.0.0.1; its default port is 7654. Pass --caddy-admin http://127.0.0.1:2019 to use a dedicated external Caddy instance instead. --docker-desktop requires --caddy-admin and makes external Caddy reach host services through host.docker.internal.

runCopy Anchor Link

devproxy run --project PROJECT [--worktree NAME] [--route /api] [--url-env APP_URL] [--ready-timeout 60s] [--daemon http://127.0.0.1:7654] SERVICE -- COMMAND [ARGS...]

Starts a child command on an available port. The child must listen on that port, either by reading PORT or by accepting a {port} argument. run waits up to 60 seconds by default for a TCP listener on 127.0.0.1, then registers the service. If startup or registration fails, it stops the child. On exit, it removes the registration.

devproxy run --project kasta --url-env NEXT_PUBLIC_APP_URL web -- next dev -p '{port}'

The child receives:

{port} is replaced in each command argument. The service must accept the allocated port; devproxy does not change its own configuration.

registerCopy Anchor Link

devproxy register --project PROJECT --port PORT [--worktree NAME] [--route /api] [--daemon http://127.0.0.1:7654] SERVICE

Registers a service already listening on 127.0.0.1:PORT. Use this for an API, frontend, nginx, or a container whose HTTP port is published to the host. Leave register running while the service needs its URL.

listCopy Anchor Link

devproxy list [--json] [--daemon http://127.0.0.1:7654]

Prints the URL, route, service name, and local host port of every active registration on this machine. Use --daemon if the daemon runs at a nondefault address.

Use --json for scripts and agents. It emits one JSON array of active registrations, including each registration's id, project, worktree, service, route, port, host, url, and expires_at. An empty list is [].

inspectCopy Anchor Link

devproxy inspect [--json] [--route /api] [--daemon http://127.0.0.1:7654] ID|HOST|URL

Shows one active registration with its ID, project, worktree, service, URL, host, route, local port, and lease expiration. Pass the ID from list --json, a hostname such as example-feature.localhost, or a service URL such as https://example-feature.localhost. When several routes share a hostname or URL, select one with --route or use its ID. --json emits one registration object with the same fields as list --json. A missing or ambiguous registration returns an error.

Shared service flagsCopy Anchor Link

Pass flags before SERVICE. run also needs -- before the child command. See Routes and URLs for naming and path rules.