front-proxy

<h1><img src="src/admin/favicon.svg" alt="" width="32" height="32"> front-proxy</h1>

[![npm](https://img.shields.io/npm/v/front-proxy)](https://www.npmjs.com/package/front-proxy)
[![coverage](https://codecov.io/gh/gutomezencio/front-proxy/graph/badge.svg)](https://codecov.io/gh/gutomezencio/front-proxy)
[![audit](https://github.com/gutomezencio/front-proxy/actions/workflows/audit.yml/badge.svg)](https://github.com/gutomezencio/front-proxy/actions/workflows/audit.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/gutomezencio/front-proxy/badge)](https://scorecard.dev/viewer/?uri=github.com/gutomezencio/front-proxy)
[![Socket Badge](https://badge.socket.dev/npm/package/front-proxy/0.8.2)](https://badge.socket.dev/npm/package/front-proxy/0.8.2)

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](https://github.com/FiloSottile/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](https://github.com/FiloSottile/mkcert), only for HTTPS (`brew install mkcert` on macOS)

## Installation

```bash
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](https://github.com/nvm-sh/nvm) or Homebrew, or run `sudo npm install -g front-proxy`.

To update:

```bash
npm update -g front-proxy
```

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

To run it from a clone instead, see [Development](#development).

## Usage

```bash
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](#https)).

| Command                             | Description                                                          | Needs sudo |
| ----------------------------------- | -------------------------------------------------------------------- | ---------- |
| `front-proxy`                       | Start the proxy on ports `80` and `443`, adding your domains to `/etc/hosts` until it stops | Yes |
| `front-proxy --persist-hosts`       | Same, but keep the domains in `/etc/hosts` after the proxy stops (`-p` for short)          | Yes |
| `front-proxy --no-admin`            | Start without the [admin page](#admin-page)                          | Yes        |
| `front-proxy add <host:port>`       | Add a domain to the proxy config                                     | No         |
| `front-proxy remove <host>`         | Remove a domain from the proxy config                                | No         |
| `front-proxy list`                  | List the configured domains                                          | No         |
| `front-proxy generate-certs [host]` | Create HTTPS certificates with mkcert, for one domain or all of them | No         |
| `front-proxy mcp`                   | Run the [MCP server](#mcp-server) for code assistants, on stdio      | No         |
| `front-proxy --help`                | Show the help                                                        | No         |

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
# </FRONT-PROXY-HOSTS>
```

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](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](https://modelcontextprotocol.io) 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](https://registry.modelcontextprotocol.io) as `io.github.gutomezencio/front-proxy`.

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=front-proxy&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImZyb250LXByb3h5IiwibWNwIl19)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_server-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522front-proxy%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522front-proxy%2522%252C%2522mcp%2522%255D%257D)
[![Download for Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Download_.mcpb-D97757?logo=claude&logoColor=white)](https://github.com/gutomezencio/front-proxy/releases/latest/download/front-proxy.mcpb)

**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):

```bash
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`](https://github.com/gutomezencio/front-proxy/releases/latest/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:

```json
{
  "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).

| Tool             | What it does                                                                                         |
| ---------------- | ---------------------------------------------------------------------------------------------------- |
| `