front-proxy

front-proxy

Reach apps on local ports, like localhost:3000, through real-looking domains, like local-dev.mylivedomain.com, over HTTP or HTTPS.

While it runs, front-proxy adds your domains to /etc/hosts, pointing them at 127.0.0.1, and runs a reverse proxy on ports 80 and 443. When it stops, it removes them. The proxy reads the Host header of each request and forwards it to the port you mapped to that domain. HTTPS uses locally trusted certificates from mkcert. Because the mapping lives in the OS, it works in every browser and tool on your machine, not just one.

  Browser, curl, Playwright...

│ │ https://local-dev.mylivedomain.com ▼ ┌───────────────────────────────────────────────┐ │ /etc/hosts │ │ 127.0.0.1 local-dev.mylivedomain.com │ └───────────────────────────────────────────────┘ │ │ 127.0.0.1:443 (or :80 for http) ▼ ┌───────────────────────────────────────────────┐ │ front-proxy │ │ 1. TLS with the domain's mkcert certificate │ │ 2. Host header → port, from proxyHosts.json │ │ local-dev.mylivedomain.com → 3000 │ │ (unknown host → 502) │ └───────────────────────────────────────────────┘ │ │ http://127.0.0.1:3000 ▼ Your local app

Why

Some third-party services only accept requests from an allowlist of domains (Stripe and Google Tag Manager, for example), and some APIs block localhost with CORS. Browser extensions can fake a domain for one browser. front-proxy works for the whole OS, so it also covers other browsers, CLI tools and headless Playwright runs with no extra configuration.

Requirements

• Node.js 22.12 or newer
• macOS or Linux (it edits /etc/hosts and uses sudo)
• mkcert, only for HTTPS (brew install mkcert on macOS)

Installation

npm install -g front-proxy

The front-proxy command is now available in your terminal.

If npm install -g fails with EACCES, your npm global folder is owned by root. That's common with the system Node on Linux or the official macOS installer. Use a Node installed with nvm or Homebrew, or run sudo npm install -g front-proxy.

To update:

npm update -g front-proxy

Your domains and certificates live in ~/.front-proxy (see Configuration), so updates and reinstalls keep them.

To run it from a clone instead, see Development.

Usage

front-proxy add local-dev.livedomain.com:3000   # map a domain to a local port

front-proxy # start the proxy

Then open http://local-dev.livedomain.com (or https:// once you've set up certificates).

Only starting the proxy asks for your password through sudo, because it binds ports 80/443 and edits /etc/hosts. The password isn't stored.

The domains go into a single block in /etc/hosts:

# <FRONT-PROXY-HOSTS>

> local-dev.livedomain.com < Host added by front-proxy

127.0.0.1 local-dev.livedomain.com #

Stopping the proxy (Ctrl+C) removes the block, unless you started it with --persist-hosts. If the proxy didn't stop cleanly (it crashed or was killed), the block stays until the next start. Each start replaces any block it finds with a fresh one. add and remove only change the config, so restart the proxy to apply them.

Requests for a domain that isn't configured get a 502 response.

Hosts must be valid hostnames (letters, digits, hyphens and dots, like myapp.local). IP addresses, localhost, front-proxy.localhost and ports 80/443 (the proxy's own) are rejected. Entries in proxyHosts.json that don't pass these checks are skipped with a warning.

Admin page

While the proxy runs, open http://front-proxy.localhost to manage your domains in the browser. The page:

• lists the configured domains, with a dot showing whether something is listening on each port
• adds and removes domains, and changes a domain's port
• shows which certificate each domain uses, with the generate-certs command to copy when it has none
• links to each active domain over HTTP (and HTTPS when it's on)

Changes are saved to proxyHosts.json right away, like the CLI commands. The page then shows a banner until they're active: click Apply now to reload the routes, certificates and /etc/hosts block without restarting, or restart front-proxy.

The proxy runs as root, so the page only accepts:

• requests from this machine (127.0.0.1/::1), with the front-proxy.localhost host, which blocks LAN clients and DNS rebinding
• changes sent from the page itself: its Origin, a JSON body and a random token generated each time the proxy starts

Its responses use a strict Content Security Policy and can't be framed. To turn the page off, start with front-proxy --no-admin.

For HTTPS on the admin page, the default certificate must include front-proxy.localhost. generate-certs adds it when it creates the default certificate. If yours was created by an older version, delete ~/.front-proxy/keys/_private-default-*.pem and run front-proxy generate-certs again.

MCP server

front-proxy mcp runs a Model Context Protocol server on stdio, so code assistants (Claude Code, Cursor, VS Code, Codex, Windsurf…) can manage your domains for you. For example, they can map the app they just started to a domain and check that it answers. It's listed in the MCP Registry as io.github.gutomezencio/front-proxy.

Claude Code: install the plugin, which adds the MCP server and a skill that tells Claude when front-proxy helps (allowlisted domains, CORS, cookies, local HTTPS):

claude plugin marketplace add gutomezencio/front-proxy

claude plugin install front-proxy@front-proxy

Or add only the MCP server: claude mcp add front-proxy -- npx -y front-proxy mcp.

Claude Desktop: download front-proxy.mcpb from the latest release and open it.

Codex: codex mcp add front-proxy -- npx -y front-proxy mcp.

Other clients take the same command in their MCP config:

{

"mcpServers": { "front-proxy": { "command": "npx", "args": ["-y", "front-proxy", "mcp"] } } }

If you installed front-proxy globally, front-proxy mcp works too. Both share the config in ~/.front-proxy, but the proxy itself still runs from the global install (see below).

The MCP server runs as you, without sudo, like add and remove. Its changes are saved to proxyHosts.json. To apply them, it calls the running proxy's admin API from 127.0.0.1 with the same per-run token and Origin as the admin page. Some things are left to you:

• Starting and stopping the proxy needs your password, so the assistant asks you to run front-proxy.
• apply_config needs the admin page on (the default). With --no-admin, restart the proxy to apply changes.
• generate_certs can't type your password, so run mkcert -install once in a terminal before using it.

HTTPS

HTTPS on port 443 needs locally trusted certificates, which front-proxy creates with mkcert:

front-proxy generate-certs                            # every configured domain

front-proxy generate-certs local-dev.livedomain.com # a single domain

The first run installs mkcert's local CA so browsers trust the certificates. It also creates a default certificate for localhost and front-proxy.localhost. Each domain then gets its own certificate, which the proxy serves through SNI. Domains without their own