front-proxy

front-proxy

localhost:3000 のようなローカルポート上のアプリに、local-dev.mylivedomain.com のような実際のドメインに見えるドメインを使って、HTTP または HTTPS 経由でアクセスできます。

実行中は、front-proxy がドメインを /etc/hosts に追加して 127.0.0.1 を割り当て、ポート 80 と 443 でリバースプロキシを実行します。停止すると、追加したドメインを削除します。プロキシは各リクエストの Host ヘッダーを読み取り、そのドメインに割り当てられたポートに転送します。HTTPS では、mkcert のローカルで信頼される証明書を使用します。マッピングは OS に保存されるため、特定のブラウザーだけでなく、マシン上のすべてのブラウザーとツールで利用できます。

  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

理由

一部のサードパーティサービスは許可リストに登録されたドメインからのリクエストのみを受け付けます（Stripe や Google Tag Manager など）。また、一部の API は CORS によって localhost をブロックします。ブラウザー拡張機能を使えば、1 つのブラウザーでドメインを偽装できます。front-proxy は OS 全体で動作するため、追加設定なしで他のブラウザー、CLI ツール、ヘッドレスの Playwright 実行にも対応します。

必要条件

• Node.js 22.12 以降
• macOS または Linux（/etc/hosts を編集し、sudo を使用します）
• mkcert。HTTPS を使う場合のみ必要です（macOS では brew install mkcert）

インストール

npm install -g front-proxy

これで、ターミナルから front-proxy コマンドを使用できます。

npm install -g が EACCES で失敗する場合、npm のグローバルフォルダーの所有者が root になっています。Linux のシステム Node や、macOS 公式インストーラーを使用している場合によく起こります。nvm または Homebrew でインストールした Node を使うか、sudo npm install -g front-proxy を実行してください。

更新するには：

npm update -g front-proxy

ドメインと証明書は ~/.front-proxy に保存されます（設定を参照）。そのため、更新や再インストール後も保持されます。

クローンから実行する方法については、開発を参照してください。

使用方法

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

次に、http://local-dev.livedomain.com を開きます（証明書を設定すると、https:// も利用できます）。

コマンド	説明	sudo が必要
front-proxy	ポート 80 と 443 でプロキシを起動し、停止するまでドメインを /etc/hosts に追加します	はい
front-proxy --persist-hosts	同じ処理を行いますが、プロキシの停止後もドメインを /etc/hosts に残します（短縮形は -p）	はい
front-proxy --no-admin	管理ページを使わずに起動します	はい
front-proxy add <host:port>	プロキシ設定にドメインを追加します	いいえ
front-proxy remove <host>	プロキシ設定からドメインを削除します	いいえ
front-proxy list	設定済みのドメインを一覧表示します	いいえ
front-proxy generate-certs [host]	mkcert で、1 つまたはすべてのドメインの HTTPS 証明書を作成します	いいえ
front-proxy mcp	コードアシスタント用の MCP サーバーを stdio で実行します	いいえ
front-proxy --help	ヘルプを表示します	いいえ

プロキシの起動時のみ、ポート 80／443 のバインドと /etc/hosts の編集のために、sudo 経由でパスワードを求められます。パスワードは保存されません。

ドメインは /etc/hosts 内の 1 つのブロックに追加されます。

# <FRONT-PROXY-HOSTS>
# > local-dev.livedomain.com < Host added by front-proxy
127.0.0.1 local-dev.livedomain.com
# </FRONT-PROXY-HOSTS>

プロキシを停止すると（Ctrl+C）、--persist-hosts を指定して起動した場合を除き、このブロックは削除されます。プロキシが正常に停止しなかった場合（クラッシュした、または強制終了された場合）、次回の起動までブロックは残ります。起動するたびに、見つかったブロックは新しいものに置き換えられます。add と remove は設定を変更するだけなので、反映するにはプロキシを再起動してください。

設定されていないドメインへのリクエストには、502 が返されます。

ホストは有効なホスト名（myapp.local のように、英字、数字、ハイフン、ドットを含むもの）である必要があります。IP アドレス、localhost、front-proxy.localhost、およびポート 80／443（プロキシ自体が使用するポート）は拒否されます。これらのチェックに通らない proxyHosts.json のエントリは、警告とともにスキップされます。

管理ページ

プロキシの実行中に http://front-proxy.localhost を開くと、ブラウザーでドメインを管理できます。このページでは、次の操作ができます。

• 設定済みのドメインを一覧表示します。各ポートで何かが待ち受けているかどうかは、ドットで示されます
• ドメインの追加と削除、およびドメインのポートの変更を行います
• 各ドメインが使用している証明書を表示します。証明書がない場合は、コピーして使える generate-certs コマンドも表示します
• 各アクティブドメインへの HTTP リンク（HTTPS が有効な場合は HTTPS リンクも）を表示します

CLI コマンドと同様に、変更はすぐに proxyHosts.json に保存されます。その後、変更が有効になるまでページにバナーが表示されます。Apply now をクリックすると、再起動せずにルート、証明書、/etc/hosts のブロックを再読み込みできます。または、front-proxy を再起動してください。

プロキシは root として実行されるため、ページで受け付けるのは次のものだけです。

• このマシン（127.0.0.1／::1）からのリクエストで、ホストが front-proxy.localhost のもの。これにより、LAN クライアントと DNS リバインディングがブロックされます
• ページ自体から送信された変更。具体的には、その Origin、JSON ボディ、プロキシの起動ごとに生成されるランダムトークンを含むもの

レスポンスには厳格な Content Security Policy が適用され、フレーム内に表示することはできません。ページを無効にするには、front-proxy --no-admin を指定して起動してください。

管理ページで HTTPS を使うには、デフォルトの証明書に front-proxy.localhost が含まれている必要があります。generate-certs は、デフォルトの証明書を作成するときにこのドメインを追加します。古いバージョンで作成した証明書の場合は、~/.front-proxy/keys/_private-default-*.pem を削除してから、front-proxy generate-certs を再実行してください。

MCP サーバー

front-proxy mcp は Model Context Protocol サーバーを stdio で実行するため、コーディングアシスタント（Claude Code、Cursor、VS Code、Codex、Windsurf など）がドメインを管理できます。たとえば、起動したばかりのアプリをドメインに割り当て、応答があることを確認できます。MCP Registry の MCP Registry に io.github.gutomezencio/front-proxy として登録されています。

Claude Code：MCP サーバーと、front-proxy が役立つ状況（許可リスト登録済みドメイン、CORS、Cookie、ローカル HTTPS）を Claude に伝えるスキルを追加するプラグインをインストールします。

claude plugin marketplace add gutomezencio/front-proxy
claude plugin install front-proxy@front-proxy

または、MCP サーバーのみを追加します：claude mcp add front-proxy -- npx -y front-proxy mcp。

Claude Desktop：最新リリースから front-proxy.mcpb をダウンロードして開きます。

Codex：codex mcp add front-proxy -- npx -y front-proxy mcp。

その他のクライアントでは、MCP 設定に同じコマンドを指定します。

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

front-proxy をグローバルにインストールしている場合は、front-proxy mcp も使用できます。どちらも ~/.front-proxy の設定を共有しますが、プロキシ自体は引き続きグローバルインストールから実行されます（下記参照）。

ツール	機能
list_hosts	設定済みのドメイン、そのポート、証明書の状態を一覧表示します
add_host	ドメインをローカルポートに割り当てます（front-proxy add と同じチェックを行います）
update_host	ドメインの接続先ポートを変更します
remove_host	ドメインを削除します
generate_certs	mkcert で、1 つまたはすべてのドメインの HTTPS 証明書を作成します
proxy_status	プロキシの実行状況、HTTPS の有効状況、適用待ちの変更の有無、リッスン中のアプリを確認します
apply_config	管理ページの 今すぐ適用 と同様に、保存済みの設定を実行中のプロキシに読み込みます

MCP サーバーは、add や remove と同様に、sudo を使わずにユーザー権限で実行されます。変更は proxyHosts.json に保存されます。変更を適用するには、実行中のプロキシの管理 API を 127.0.0.1 から呼び出します。その際、管理ページと同じ実行ごとのトークンおよび Origin を使用します。いくつかの操作はユーザー自身が行う必要があります。

• プロキシの起動と停止にはパスワードが必要なため、アシスタントから front-proxy の実行を求められます。
• apply_config を使うには、管理ページを有効にしておく必要があります（デフォルト）。--no-admin を指定している場合は、変更を適用するためにプロキシを再起動してください。
• generate_certs はパスワードを入力できないため、使用前にターミナルで mkcert -install を一度実行してください。

HTTPS

ポート 443 の HTTPS には、ローカルで信頼された証明書が必要です。front-proxy は mkcert を使って証明書を作成します。

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

初回実行時に mkcert のローカル CA がインストールされ、ブラウザーが証明書を信頼するようになります。また、localhost と front-proxy.localhost 用のデフォルト証明書も作成されます。各ドメインにはそれぞれ専用の証明書が作成され、プロキシは SNI を通じて証明書を提供します。専用の証明書がないドメインには、デフォルト証明書が使用されます。デフォルト証明書がない場合、プロキシは HTTP のみで起動します。

証明書が作成され適用された後も、Chrome でドメインが「保護されていない通信」と表示される場合は、Chrome を完全に終了（macOS では Cmd+Q）してから再度開いてください。Chrome は、以前に検出した証明書エラーや、ユーザーが続行した証明書エラーを再起動するまで記憶します。Firefox が mkcert の CA を信頼するのは、generate-certs の実行前に nss がインストールされている場合のみです（brew install nss）。

HTTPS のレスポンスには HSTS ヘッダー（includeSubDomains、preload）が含まれるため、ブラウザーは対象ドメインで HTTPS を使用するよう記憶します。

カスタム証明書

独自の証明書（ワイルドカード証明書など）を使用するには、~/.front-proxy/keys/ に _private-<name>-cert.pem と _private-<name>-key.pem という名前で保存し、その証明書を使用する各ドメインに "cert": "<name>" を設定します。

mkcert \
  -cert-file ~/.front-proxy/keys/_private-mydomain-cert.pem \
  -key-file  ~/.front-proxy/keys/_private-mydomain-key.pem \
  "*.mydomain.com"

設定

ドメインは ~/.front-proxy/proxyHosts.json に、証明書は ~/.front-proxy/keys/ に保存されます。このフォルダーは初回実行時に作成されます。別の場所に保存するには、FRONT_PROXY_HOME 環境変数を設定してください。

上記のコマンドで設定を管理できますが、手動で編集することもできます。

{
  "local-dev.livedomain.com": {
    "port": 3000,
    "cert": "local-dev.livedomain.com"
  }
}

キー	説明
port	127.0.0.1 上でドメインのプロキシ先となるローカルポート
cert	任意。~/.front-proxy/keys/_private-<cert>-{cert,key}.pem を指定します。複数のドメインで同じ証明書を共有できます

$ で始まるキー（CLI が書き込む $comment など）は無視されます。

アンインストール

まずプロキシを停止（Ctrl+C）し、/etc/hosts からプロキシのブロックを削除します。--persist-hosts を使用した場合、または以前のバージョンがドメインを追加した場合は、フラグを付けずにプロキシを一度起動してから停止し、削除してください。

front-proxy                        # then Ctrl+C
npm uninstall -g front-proxy
rm -rf ~/.front-proxy              # config and certificates
mkcert -uninstall                  # optional: remove mkcert's local CA

開発

クローンから front-proxy を使う場合や、開発に取り組む場合は、次の手順に従ってください。

git clone [email protected]:gutomezencio/front-proxy.git
cd front-proxy
npm install
npm run build   # compile src/ (TypeScript) to dist/
npm link        # point the global `front-proxy` command at this clone

npm パッケージを以前にインストールしたことがある場合は、競合を避けるため、まず npm uninstall -g front-proxy を実行してください。npm link はグローバルコマンドをクローンの dist/ にリンクするため、フォルダーはそのまま残し、更新するには git pull と npm run build を実行してください。npm unlink -g front-proxy でリンクを削除できます。クローンは npm パッケージと同じ ~/.front-proxy 設定を使用します。

npm run build                # compile src/ to dist/ and copy the admin page's static files
npm start                    # build, then run the proxy from dist/, without the sudo wrapper
npm run dev                  # same, rebuilding and restarting on file changes
npm run start:root -- list   # build, then run through the sudo wrapper, like the installed CLI
npm run typecheck            # type-check src/ and test/
npm test                     # run the tests (Jest with ts-jest, straight from src/)
npm run test:coverage        # same, with coverage (fails below the thresholds in package.json)
npm pack --dry-run           # list the files that get published to npm
npm run build:mcpb           # build front-proxy.mcpb, the Claude Desktop bundle

コードは TypeScript（strict、ネイティブ ES モジュール）で書かれており、検証するすべての項目に zod スキーマを使用しています。tsc が dist/ にコンパイルし、npm pack／npm publish は実行前にビルドします（prepack スクリプト）。公開されるのは dist/、README.md、LICENSE、package.json のみです（package.json の files フィールド）。

ライセンス

MIT