Skip to content
Switch branches/tags


Lightweight local proxy, useful for giving your local services memorable local domain names like myproject.wip instead of localhost:8000.

Key features!

  • Super simple proxy-based setup
  • Choose your own local tld, e.g. .localhost or .wip
  • Wildcard subdomains, e.g. *.devserver.wip
  • Zero config HTTPS support for all mapped URLs
  • Proxy mode: route requests to a local server
  • File server mode: serve files directly from a folder


Installation (brew)

brew install octavore/tools/lightproxy

Registering URL mappings

To map foo.wip to localhost:3000:

lightproxy set-dest foo.wip 3000

To map foo.wip to a folder:

lightproxy set-dir foo.wip ~/Code/foo/

Starting lightproxy

Open up a new terminal shell and run lightproxy.

Configure your system proxy (MacOS)

  1. Go to System Preferences > Network > Proxies.
  2. Select and check Automatic Proxy Configuration in the sidebar.
  3. Set the URL to http://localhost:7999/proxy.pac

screen shot 2018-06-26 at 8 46 00 pm

Configure your system proxy (Windows)

See here


All proxied URLS are also automatically available over https, i.e. http://foo.wip is also served with https at https://foo.wip.

Internally, lightproxy does this by listening for TLS connections on a separate port, 7998. You can change this port if it conflicts with another app you have running. You should never need to connect to it directly.

Please note that you will see browser warnings because lightproxy generates a self-signed certificate. To suppress the warnings, you can tell lightproxy to sign certificates using a locally trusted root CA.

Using a local root CA

  1. Generate a local CA key file

    openssl genrsa -out lightproxyCA.key 4096
    openssl req -x509 -new -nodes -key lightproxyCA.key -sha256 -days 1024 -out lightproxyCA.crt
  2. Trust the key file

    If you are on a Mac, open Keychain Access in System Preference, select the System keychain, select the Certificates category, and drag your key file into the list of certificates.

    Double click the certificate, open up the Trust section, and make sure When using this certificate: is set to Always Trust. Restart your browsers for this to take effect.

  3. Set ca_key_file in lightproxy's config

    Tell lightproxy where to find your files by setting the ca_key_file parameter in config.json (see below). Set it to the keyfile path you generated in step 1. Restart lightproxy.


URL mappings can be added easily using the commands above, but you can also edit the config file directly.

To view the current config and where it is saved, run this:

lightproxy config

Example config

  # only hosts ending in this tld are handled by the proxy
  "tld": "wip",

  # the local addr the proxy listens on
  "addr": "localhost:7999",

  # the local addr the proxy listens on internally to handle
  # TLSrequests
  "tls_addr": "localhost:7998",

  # if you are using a local CA, this should be set to the value
  # of the *.key file. The corresponding *.crt should be in the same
  # folder.
  "ca_key_file": "...",

  # all hosts to map. Entries must have `host` set, and
  # either `dest` (a local addr), or `dest_folder` (a folder)
  "entries": [
      "host": "ketchup.wip",
      "dest": "localhost:8000"
      "host": "goatcodes.wip",
      "dest": "localhost:8100"
      "host": "go.goatcodes.wip",
      "dest": "localhost:8100"
      "host": "blog.goatcodes.wip",
      "dest_folder": "/sites/goatblog"

Under the hood

lightproxy uses a proxy auto-config file to tell your system what URLs to send to the proxy.

By default, this PAC file is served at http://localhost:7999/proxy.pac. It contains a simple javascript function:

function FindProxyForURL(url, host) {
  if (shExpMatch(host, '*.wip')) {
    return 'PROXY';
  return 'DIRECT';



2019-12-11 / 1.2.1

  • Search both $XDG_CONFIG_HOME and $HOME/.config/lightproxy forconfig.json(preferring the former if set). This change improves thebrew installation` experience while maintaining backward compatability.

2019-05-10 / 1.2

  • Support wildcards in source url

2019-05-10 / 1.1

  • Added TLS support
  • Added tls_addr and ca_key_file config option