Local-proxy (dpc)

A CLI tool that maps local ports to clean .test domains. Instead of remembering that your frontend is on port 3000 and your API is on port 4000, you can visit http://frontend.test and http://api.test instead.

It handles three things automatically: writing to /etc/hosts, generating an nginx or Caddy config file, and reloading the server so changes take effect immediately.

Platform support

Fully supported on macOS. Linux support is partial: adding and removing proxies works, but dpc start and dpc stop rely on Homebrew services and will not work. Windows is not supported.

Prerequisites

You need either nginx or Caddy installed. On macOS the easiest way is through Homebrew:

# nginx
brew install nginx

# or Caddy
brew install caddy

For HTTPS support you also need mkcert:

brew install mkcert
mkcert -install

mkcert -install is a one-time setup that adds a local Certificate Authority to your system trust store. This is what makes browsers trust the generated certificates without showing a warning. You only need to run it once per machine.

Installation

npm install -g @moakk/local-proxy

Setup

Run this once after installing to let dpc detect which proxy server you have:

dpc init

If you picked nginx, make sure it is running before adding any proxies:

brew services start nginx

If you picked Caddy, start it with:

dpc start

Usage

# add a proxy
sudo dpc add frontend 3000

# add a proxy with HTTPS
sudo dpc add api 4000 --https

# see everything that is configured
dpc list

# remove a proxy
sudo dpc remove frontend

# start or stop the proxy server
dpc start
dpc stop

Most commands that touch /etc/hosts or the nginx config directory need sudo. You will see a clear error message if you forget.

Example

sudo dpc add frontend 3000
sudo dpc add api 4000
sudo dpc add admin 8080

dpc list
# frontend        http://frontend.test  ->  localhost:3000
# api             http://api.test       ->  localhost:4000
# admin           http://admin.test     ->  localhost:8080

Then open http://frontend.test in your browser and it routes straight to whatever is running on port 3000.

HTTPS example

sudo dpc add api 4000 --https
# https://api.test -> localhost:4000

The certificate is generated automatically using mkcert and stored at ~/.config/local-proxy/certs/. When you remove the proxy, the certificate files are removed too.

How it works

When you run dpc add frontend 3000 it does three things:

1. Adds 127.0.0.1 frontend.test to /etc/hosts so the domain resolves to your own machine
2. Writes a proxy config block for nginx or Caddy that forwards requests for frontend.test to localhost:3000
3. Reloads the proxy server so the config is picked up right away

When you use --https it also runs mkcert to generate a certificate and key for the domain, and updates the proxy config to listen on port 443 with those files.

Config and certificates are stored in ~/.config/local-proxy/. The proxy list is saved to ~/.config/local-proxy/config.json so it persists between sessions.

Commands

| Command | Description | | --- | --- | | dpc init | Detect and save your proxy server (run once after installing) | | dpc add <name> <port> | Add a new proxy | | dpc add <name> <port> --https | Add a new proxy with HTTPS | | dpc remove <name> | Remove a proxy and clean up all associated files | | dpc list | Show all configured proxies | | dpc start | Start the proxy server | | dpc stop | Stop the proxy server |

License

MIT