lpm proxy

lpm proxy manages the local daemon that routes friendly hostnames, such as app.localhost, to services that lpm dev starts.

For HTTPS routes, the proxy terminates TLS. The child dev server continues to use HTTP.

lpm proxy [action]

Use this command to inspect routes, run a temporary daemon, or install a persistent service for the current user.

Examples

lpm proxy status        # show the daemon, listeners, and active routes
lpm proxy list          # show only active routes
lpm proxy start         # run the daemon in the foreground
lpm proxy start --detach
lpm proxy start --http-port 8080
lpm proxy start --tls-port 9443
lpm proxy start --tls-port 9443 --http-redirect-port 9080
lpm proxy stop
lpm proxy install --tls-port 9443
lpm proxy install --privileged-ports
lpm proxy uninstall
lpm proxy uninstall --privileged-ports
lpm proxy status --json

Choose an action

status is the default action. A bare lpm proxy command equals lpm proxy status.

How proxy routing works

The proxy separates the browser connection from the dev-server connection:

1. lpm dev starts the child service with a plain HTTP endpoint.
2. If no daemon runs, lpm dev starts the proxy daemon in the background.
3. lpm dev registers each configured hostname against the final service port.
4. The proxy selects a route from the request hostname and forwards the request to the service.
5. When the dev session exits, lpm dev releases its route lease.

HTTP forwarding streams response bodies and supports WebSocket and HMR upgrades.

lpm dev requires an HTTPS proxy listener for configured hostnames. A control-only daemon or a plain HTTP listener is not sufficient.

Do not enable framework HTTPS for a proxied child service. Let the proxy terminate TLS and forward to the plain HTTP service.

Recipes

Use app.localhost without privileged ports

Add a high HTTPS port to lpm.json:

{
  "proxy": {
    "host": "app.localhost",
    "port": 9443,
    "httpRedirect": false
  }
}

Then start the dev server:

lpm dev

If no daemon runs, lpm dev starts one in the background. It registers app.localhost for the lifetime of the dev session.

The startup output shows the exact URL with port 9443. A *.localhost hostname does not require a hosts-file entry.

Route multiple services

Give each service a different hostname:

{
  "proxy": {
    "port": 9443,
    "httpRedirect": false
  },
  "services": {
    "web": {
      "command": "vite",
      "port": 5173,
      "host": "web.localhost"
    },
    "api": {
      "command": "node api.js",
      "port": 4000,
      "host": "api.localhost"
    }
  }
}

lpm dev
lpm proxy list

The route table shows each hostname, service, project directory, and final upstream port.

Start the proxy manually

Use a foreground daemon while you diagnose listener or certificate errors:

lpm proxy start --tls-port 9443 --http-redirect-port 9080

When another terminal does not need the proxy log, use a detached daemon:

lpm proxy start --detach --tls-port 9443

The detached command waits for the daemon to report that it is ready.

Change the listeners

An existing daemon does not accept listener changes from another detached start. Stop the daemon before you select new listeners.

lpm proxy status
lpm proxy stop
lpm proxy start --detach --tls-port 9443

If an installed service owns the daemon, use lpm proxy uninstall to remove that persistent service.

Listener selection

Listener flags are exact overrides. If one listener flag is present, LPM CLI does not read listener values from lpm.json.

When you want configuration-based listeners, run start or install from the directory that contains lpm.json.

The listener flags bind only to 127.0.0.1. Port 0 lets the operating system select an available port.

--http-redirect-port requires --tls-port in the same command:

lpm proxy start --tls-port 9443 --http-redirect-port 9080

Install a persistent service

Install a user-scoped service on a high port:

lpm proxy install --tls-port 9443

The installation also starts the service. The service uses the current directory as its project directory.

On Linux and macOS, a user service cannot bind ports from 1 through 1023. Use high ports or install the privileged forwarder.

Use ports 443 and 80 on Linux or macOS

Run the command as the target user:

lpm proxy install --privileged-ports

Do not run the full command with sudo. LPM CLI uses sudo only for the root-owned forwarder files and service.

The command installs two services:

• A proxy daemon for the current user.
• A root-owned loopback forwarder for low ports.

Without explicit listener flags, the forwarder exposes HTTPS on port 443. It also exposes the redirect on 80 unless proxy.httpRedirect is false.

The user daemon selects an available HTTPS backend port from 9443. It selects a redirect backend port from 9080.

The privileged forwarder supports HTTPS and HTTP redirects. It does not support plain --http-port forwarding.

CAUTION: Do not use --replace unless you intend to replace the privileged forwarder of another user.

Remove only the user service:

lpm proxy uninstall

Remove the user service and the privileged forwarder:

lpm proxy uninstall --privileged-ports

The uninstall command refuses to remove a privileged forwarder that belongs to another user.

Certificates and hosts files

An HTTPS listener selects the matching project certificate by SNI. Route registration prepares or refreshes the certificate chain for each hostname.

The proxy daemon does not install the root CA into the trust store. lpm dev uses the normal certificate consent flow.

localhost and *.localhost do not need hosts-file entries. Other local hostnames require a managed entry in the system hosts file.

lpm dev asks for consent before it changes the hosts file. When the dev session exits, it removes the project block.

If an interrupted session leaves an LPM CLI-managed block, remove it with:

lpm hosts clean

The proxy start and stop actions do not manage hosts-file entries. lpm hosts owns that cleanup.

lpm dev --https uses a separate LPM CLI frontend. It does not configure the local-domain proxy listener.

Status and JSON output

lpm proxy status shows the daemon status, PID, bound listeners, and active routes. lpm proxy list shows only the active routes.

Use JSON for scripts and diagnostics:

lpm proxy status --json
lpm proxy list --json
lpm proxy start --detach --json

The JSON object includes these fields:

• running
• pid
• httpAddr
• httpRedirectAddr
• tlsAddr
• routes
• stale
• stateError

Saved listener addresses can remain in the JSON object while stale is true. In that state, running is false and no routes are active.

Foreground lpm proxy start --json is not supported. Use lpm proxy status --json from another terminal.

Flags

Related configuration

See the full lpm.json reference for hostname validation and service fields.

See also

• lpm dev — start services and register proxy routes
• lpm cert — manage the local CA and project certificates
• lpm hosts — remove managed hosts-file blocks
• lpm ports — inspect local listeners