Portless

ポート番号を安定した名前付きの .localhost URL に置き換えます。人間とエージェント向け。

portless を使う理由

• ポート競合: 2つのプロジェクトが同じポートにデフォルト設定されている場合の EADDRINUSE エラー
• ポート番号の暗記: どのアプリが 3001 で、どれが 8080 か？
• リフレッシュが違うアプリを表示: サーバーを停止して別のサーバーを同じポートで起動すると、古いタブに違う内容が表示される
• Monorepo の複数化: 各問題がリポジトリ内の各サービスでスケールする
• エージェントが間違ったポートをテスト: AI エージェントが間違ったポートを推測またはハードコードする
• Cookie/ストレージの衝突: localhost 上の Cookie がアプリ間で漏洩; ポート変更時にローカルストレージが失われる
• 設定にハードコードされたポート: CORS 許可リスト、OAuth リダイレクト、.env ファイルがポート変更時に破損する
• チームメートとの URL 共有: 「それはどのポートで実行されているの？」という質問が Slack で生じる
• ブラウザ履歴は無用: localhost:3000 の履歴は関連のないプロジェクトが混在している

インストール

グローバルにインストールするか、プロジェクト開発依存関係としてインストールしてください。一度限りの実行に npx または pnpm dlx を使用しないでください。

# グローバル（どこでも利用可能）
npm install -g portless

# または、プロジェクト開発依存関係として
npm install -D portless

プロジェクトごとにインストールする場合は、package.json スクリプトまたは npx portless を通じて呼び出してください（パッケージがローカルなので、npx は何もダウンロードしません）。

クイックスタート

# グローバルにインストール（またはプロジェクトに -D を追加）
npm install -g portless

# アプリを実行（HTTPS プロキシをポート 443 で自動起動）
portless run next dev
# -> https://<project>.localhost

# または明示的な名前で
portless myapp next dev
# -> https://myapp.localhost

アプリを実行するとプロキシが自動起動します。portless proxy start で明示的に開始することもできます。自動起動は最後のプロキシ実行の設定（ポート、TLS、TLD）を再利用するため、再起動またはリブート時にサイレントにデフォルトに戻りません。明示的な環境変数は常に優先されます。

非インタラクティブ環境（TTY なし、または CI=1）では、portless はプロンプトではなく説明的なエラーで終了します。turborepo のようなタスクランナーはプロキシを事前に開始する必要があります。

統合パターン

ゼロ設定（推奨）

ベアの portless はすぐに使えます。プロキシを通じて package.json の "dev" スクリプトを実行し、パッケージ名、git ルート、またはディレクトリからアプリ名を推測します:

portless        # -> "dev" スクリプトを実行、https://<project>.localhost
pnpm dev        # -> portless なしで動作、プレーンな "next dev"

オプションの portless.json で デフォルト（名前、スクリプト、ポート）を上書きしてください:

{ "name": "myapp" }

portless        # -> "dev" スクリプトを実行、https://myapp.localhost

Monorepo

リポジトリルートに 1 つの portless.json。Portless は pnpm-workspace.yaml から、または package.json の "workspaces" フィールド（npm、yarn、bun）からパッケージを検出します:

{
  "apps": {
    "apps/web": { "name": "myapp" },
    "apps/api": { "name": "api.myapp" }
  }
}

portless                  # リポジトリルートから: "dev" スクリプトを持つすべてのパッケージを開始
cd apps/web && portless   # 1 つのパッケージのみ開始
portless --script start   # "dev" の代わりに "start" を実行

apps マップはオプションで、名前上書きのみを提供します。リストされていないパッケージは推測された名前で自動検出されます。

apps マップがない場合、ホスト名は <package>.<project>.localhost に従います。プロジェクト名は最も一般的な npm スコープ（例えば @myorg/web と @myorg/api が myorg を生成）から、またはワークスペースルートディレクトリ名にフォールバックします。パッケージの短名がプロジェクト名と一致する場合、ベアな <project>.localhost を使用します。

Turborepo

turborepo プロジェクトの場合、実際のコマンドを別のスクリプトで portless を dev スクリプトとして使用します:

{
  "scripts": { "dev": "portless", "dev:app": "next dev" },
  "portless": { "name": "myapp", "script": "dev:app" }
}

pnpm dev は turbo を実行し、各パッケージで portless を実行します。Portless はパッケージマネージャーを検出し、pnpm run dev:app をプロキシを通じて実行します。

package.json スクリプト

引き続き portless をスクリプトで直接使用できます:

{
  "scripts": {
    "dev": "portless run next dev"
  }
}

アプリを実行するとプロキシが自動起動します。または明示的に開始: portless proxy start。

サブドメインを使用したマルチアプリセットアップ

portless myapp next dev          # https://myapp.localhost
portless api.myapp pnpm start    # https://api.myapp.localhost
portless docs.myapp next dev     # https://docs.myapp.localhost

デフォルトでは、明示的に登録されたサブドメインのみがルーティングされます（厳密モード）。プロキシを --wildcard で起動して、登録されたルートの任意のサブドメインがそのアプリにフォールバックすることを許可します（例えば、tenant1.myapp.localhost は myapp アプリにルーティングされます）。完全一致は常にワイルドカードより優先されます。

Git worktrees

portless run は自動的に git worktrees を検出します。リンクされた worktree では、ブランチ名がサブドメインプレフィックスとして前に付加され、各 worktree が一意の URL を取得します:

# メイン worktree（プレフィックスなし）
portless run next dev   # -> https://myapp.localhost

# "fix-ui" ブランチ上のリンクされた worktree
portless run next dev   # -> https://fix-ui.myapp.localhost

設定変更は不要です。portless run を package.json に一度入れると、すべての worktrees で動作します。

portless をバイパスする

PORTLESS=0 を設定して、プロキシなしでコマンドを直接実行します:

PORTLESS=0 pnpm dev   # プロキシをバイパス、デフォルトポートを使用

動作方法

1. portless proxy start はバックグラウンドデーモンとしてポート 443 で HTTPS リバースプロキシを開始します。macOS/Linux で sudo を自動実行; sudo が利用できない場合はポート 1355 にフォールバック。プレーン HTTP 用に --no-tls を使用します（ポート 80）。-p / --port または PORTLESS_PORT 環境変数で設定可能。アプリを実行するとプロキシも自動起動します。
2. portless <name> <cmd> は PORT 環境変数を通じてランダムな空きポート（4000-4999）を割り当て、アプリをプロキシに登録します
3. ブラウザが https://<name>.localhost にヒット; プロキシがアプリの割り当てられたポートに転送します

.localhost ドメインは Chrome、Firefox、および Edge でネイティブに 127.0.0.1 に解決されます。Safari はシステム DNS リゾルバーに依存し、すべての設定で .localhost サブドメインを処理しない場合があります。必要に応じて /etc/hosts にエントリを追加するために portless hosts sync を実行します。

ほとんどのフレームワーク（Next.js、Express、Nuxt など）は PORT 環境変数を自動的に尊重します。PORT を無視するフレームワーク（Vite、VitePlus、Astro、React Router、Angular、Expo、React Native）の場合、portless は正しい --port フラグを自動注入し、必要に応じてマッチング --host CLI フラグも注入します。

状態ディレクトリ

Portless はその状態（ルート、PID ファイル、ポートファイル）を ~/.portless に保存します。PORTLESS_STATE_DIR 環境変数で上書きしてください。

環境変数

変数	説明
PORTLESS_PORT	デフォルトプロキシポートを上書き（デフォルト: HTTPS 443、なし 80）
PORTLESS_APP_PORT	アプリに固定ポートを使用（自動割り当てをスキップ）
PORTLESS_HTTPS	デフォルトで HTTPS オン; 無効化するには 0 に設定（--no-tls と同じ）
PORTLESS_LAN	LAN モードを常に有効にするには 1 に設定（LAN IP 自動検出）
PORTLESS_TLD	localhost の代わりにカスタム TLD を使用（例：test）
PORTLESS_WILDCARD	登録されていないサブドメインが親にフォールバックするには 1 に設定
PORTLESS_SYNC_HOSTS	/etc/hosts の自動同期を無効化するには 0 に設定（デフォルト オン）
PORTLESS_TAILSCALE	Tailscale ネットワーク上でアプリを共有するには 1 に設定（--tailscale と同じ）
PORTLESS_FUNNEL	Tailscale Funnel 経由でアプリを公開共有するには 1 に設定（--funnel と同じ）
PORTLESS_STATE_DIR	状態ディレクトリを上書き
PORTLESS=0	プロキシをバイパス、コマンドを直接実行

HTTP/2 + HTTPS

HTTPS と HTTP/2 はデフォルトで有効です（多くのファイルを持つ開発サーバー用の高速ページ読み込み）。初回実行時にローカル CA を生成し、システムトラストストアに追加します。その後、プロンプトなしでブラウザ警告なし。

portless proxy start --cert ./c.pem --key ./k.pem  # カスタム証明書を使用
portless proxy start --no-tls                       # HTTPS を無効化（プレーン HTTP）
portless trust                                      # 後で CA をトラストストアに追加

Linux では、portless trust は Debian/Ubuntu、Arch、Fedora/RHEL/CentOS、および openSUSE をサポートします（update-ca-certificates または update-ca-trust 経由）。Windows では、certutil を使用してシステムトラストストアに CA を追加します。

LAN モード

portless proxy start --lan
portless proxy start --lan --https
portless proxy start --lan --ip 192.168.1.42

--lan は <name>.local ホスト名を mDNS 経由で広告し、同じ Wi-Fi 上の任意のデバイスがアプリに到達できます。Portless は LAN IP を自動検出し、ネットワーク変更に自動的に従いますが、--ip <address> または PORTLESS_LAN_IP 環境変数で特定のアドレスをピン留めできます。LAN モードをデフォルトにするには、プロキシ起動時に PORTLESS_LAN=1 を設定します。

Portless は LAN モードを proxy.lan を通じて記憶するため、LAN プロキシを停止して再開するとき、LAN モードのままになります。すべてのプロキシ設定（ポート、TLS、TLD、LAN）は永続化され、明示的なフラグまたは環境変数でオーバーライドされない限り自動起動時に再利用されます。1 つの起動に PORTLESS_LAN=0 を使用してして .localhost モードに戻します。異なる明示的な LAN/TLS/TLD 設定でプロキシが既に実行されている場合、portless は警告を出し、最初にそれを停止するよう求めます。

LAN モードは portless が起動するシステム mDNS ヘルパーに依存します: macOS は dns-sd を含み、Linux は avahi-utils の avahi-publish-address を使用します（sudo apt install avahi-utils またはディストロのツール経由でインストール）。

• Next.js: .local ホスト名を allowedDevOrigins に追加:

  // next.config.js
  module.exports = {
    allowedDevOrigins: ["myapp.local", "*.myapp.local"],
  };
  

• Expo / React Native: portless は常に --port を注入します。React Native は --host 127.0.0.1 も取得します。Expo は LAN モード外で --host localhost を取得しますが、LAN モードでは portless は Metro をデフォルト LAN ホスト動作のままにし、--host または HOST を強制しません。

Tailscale 共有

--tailscale を使用して Tailscale ネットワーク上のチームメートと開発サーバーを共有するか、--funnel でパブリックインターネットに公開します:

portless myapp --tailscale next dev
# -> https://myapp.localhost           (ローカル)
# -> https://devbox.yourteam.ts.net    (tailnet)

portless myapp --funnel next dev
# -> https://myapp.localhost           (ローカル)
# -> https://devbox.yourteam.ts.net    (パブリックインターネット)

Tailscale HTTPS 証明書は、--tailscale または --funnel が HTTPS URL を登録する前に有効にする必要があります。Funnel も --funnel がパブリック URL を登録する前に、tailnet とノード用に有効にする必要があります。いずれかの設定が欠落している場合、portless は子プロセスを開始する前に終了します。

各 --tailscale アプリは独自の Tailscale HTTPS ポート（443、その後 8443、8444 など）にルートマウントされるため、フレームワーク basePath 設定は不要です。デフォルトですべてのアプリを共有するには、PORTLESS_TAILSCALE=1 を設定します。portless list はローカルと tailnet URL の両方を表示します。Tailscale serve 登録は、アプリが終了したときにクリーンアップされます。tailscale CLI がインストールされ接続済みで、Tailscale HTTPS 証明書が有効である必要があります。

OS スタートアップサービス

ユーザーがリブート後にプロキシを自動起動したい場合は、service コマンドを使用します:

portless service install
portless service status
portless service uninstall

サービスはデフォルトのクリーン URL 動作を使用します: ポート 443 で HTTPS、.localhost 名。macOS と Linux はルート所有のサービスをインストールし、ポート 443 をブート時にバインドできます。Windows はシステムとして実行される Task Scheduler スタートアップタスクをインストールします。インストールと削除は管理者権限が必要な場合があります。portless clean は自動的にサービスを削除します。

CLI リファレンス

コマンド	説明
portless	dev スクリプトをプロキシを通じて実行
portless	Monorepo ルートから: すべてのワークスペースパッケージを実行
portless --script <name>	特定の package.json スクリプトを実行（デフォルト: dev）
portless run [cmd] [args...]	プロジェクト名を推測、プロキシを通じて実行（自動起動）
portless run --name <name> <cmd>	推測されたベース名をオーバーライド（worktree プレフィックスはまだ適用）
portless <name> <cmd> [args...]	https://<name>.localhost でアプリを実行（プロキシ自動起動）
portless get <name>	サービスの URL を出力（クロスサービス接続用）
portless get <name> --no-worktree	worktree プレフィックスなしで URL を出力
portless list	アクティブなルートを表示
portless trust	ローカル CA をシステムトラストストアに追加（HTTPS 用）
portless clean	状態、CA トラストエントリ、および /etc/hosts ブロックを削除
portless prune	クラッシュしたセッションから孤立した開発サーバーを強制終了
portless prune --force	SIGTERM の代わりに SIGKILL で孤立したものを強制終了
portless proxy start	バックグラウンドデーモンとして HTTPS プロキシを開始（ポート 443、自動実行）
portless proxy start --no-tls	HTTPS なしで開始（プレーン HTTP、ポート 80）
portless proxy start --lan	LAN モードで開始（mDNS .local、LAN IP 変更を自動追跡）
portless proxy start -p <number>	カスタムポートでプロキシを開始
portless proxy start --tld test	.localhost の代わりに .test を使用
portless proxy start --foreground	フォアグラウンドでプロキシを開始（デバッグ用）
portless proxy start --wildcard	登録されていないサブドメインが親ルートにフォールバックすることを許可
portless proxy stop	プロキシを停止
portless service install	OS が起動するときに HTTPS プロキシを開始
portless service status	サービスとプロキシのステータスを表示
portless service uninstall	スタートアップサービスを削除
portless alias <name> <port>	静的ルートを登録（例：Docker コンテナ用）
portless alias <name> <port> --force	既存のルートを上書き
portless alias --remove <name>	静的ルートを削除
portless hosts sync	ルートを /etc/hosts に追加（Safari を修正）
portless hosts clean	portless エントリを /etc/hosts から削除
portless <name> --app-port <n> <cmd>	自動割り当ての代わりにアプリに固定ポートを使用
portless <name> --tailscale <cmd>	Tailscale ネットワーク上でアプリを共有（tailnet）
portless <name> --funnel <cmd>	Tailscale Funnel 経由でアプリを公開共有
portless <name> --force <cmd>	既存プロセスを強制終了し、そのルートを引き継ぎ
portless --name <name> <cmd>	<name> をアプリ名として強制（サブコマンドディスパッチをバイパス）
portless <name> -- <cmd> [args...]	フラグ解析を停止; -- 後のすべてが子に渡される
portless --help / -h	ヘルプを表示
portless run --help	サブコマンドのヘルプを表示（また: alias、hosts、clean）
portless --version / -v	バージョンを表示

予約名: run、get、alias、hosts、list、trust、clean、prune、proxy、および service はサブコマンドで、直接アプリ名として使用できません。portless run <cmd> を使用して名前を推測するか、portless --name <name> <cmd> で予約名を含むあらゆる名前を強制します。

portless.json

オプション設定ファイル。Portless は現在のディレクトリでこれを探します。

フィールド	型	デフォルト	説明
name	string	package.json から推測	ベースアプリ名（worktree プレフィックスはまだ適用）
script	string	"dev"	実行する package.json スクリプトの名前
appPort	number	自動割り当て	子プロセスの固定ポート
proxy	boolean	自動検出	プロキシを通じてルーティングするかどうか（タスク用 false）
apps	object		ワークスペースパッケージのオーバーライド、相対パスでキー化
turbo	boolean	true	false に設定して turborepo の代わりに直接スポーン

各 apps エントリは同じ形状を持ちます（name、script、appPort、proxy）。apps が存在するとき、トップレベルフィールドはシングルアプリモードでのみ適用されます。

package.json "portless" キー

別の portless.json の代わりに、package.json に "portless" キーを追加できます。文字列値は名前の設定の短縮形です:

{ "portless": "myapp" }

オブジェクトはすべてのアプリごとフィールドをサポート（name、script、appPort、proxy）:

{ "portless": { "name": "myapp", "script": "dev:app" } }

優先順位（最も近いが勝ち）: CLI フラグ > package.json "portless" キー > portless.json アプリエントリ > デフォルト。

トラブルシューティング

プロキシが実行されていない

プロキシは portless <name> <cmd> でアプリを実行するときに自動起動します。起動しない場合（例：ポート競合）、手動で開始してください:

portless proxy start

ポートが既に使用中

別のプロセスがプロキシポートにバインドされています。最初にそれを停止するか、別のポートを使用してください:

portless proxy start -p 8080

フレームワークが PORT を尊重していない

Portless は、PORT 環境変数を無視するフレームワークに対して、正しい --port フラグを自動注入し、必要に応じてマッチング --host フラグも自動注入します: Vite、VitePlus（vp）、Astro、React Router、Angular、Expo、および React Native。SvelteKit は内部的に Vite を使用し、自動的に処理されます。

ポート PORT を読み込まない他のフレームワークの場合、ポートを手動で渡します:

• Webpack Dev Server: --port $PORT を使用
• カスタムサーバー: process.env.PORT を読み込み、それをリッスン

パーミッションエラー

デフォルトポート（HTTP 用 80、HTTPS 用 443）は macOS と Linux では sudo が必要です。Portless は必要なときに sudo で自動実行します。sudo が利用できない場合、ポート 1355 にフォールバック（sudo 不要）。Windows では実行権限は不要です。

portless proxy start --https           # ポート 443 用 sudo で自動実行
portless proxy start -p 1355 --https   # sudo は不要（URL はポート :1355 を含む）
portless proxy stop                    # 停止（sudo で開始した場合は sudo を使用）

Safari が .localhost URL を見つけられない

Safari はシステム DNS リゾルバーに .localhost サブドメインを依存し、すべての macOS 設定で解決しない場合があります。Chrome、Firefox、および Edge はビルトイン処理があります。

修正:

portless hosts sync    # 現在のルートを /etc/hosts に追加
portless hosts clean   # 後で エントリを削除

デフォルトではルートホスト名の /etc/hosts を自動同期します。無効化するには、PORTLESS_SYNC_HOSTS=0 を設定します。

ブラウザが --https で証明書警告を表示

ローカル CA がまだ信頼されていない可能性があります。実行:

portless trust

これにより、portless ローカル CA をシステムトラストストアに追加します。その後、ブラウザを再起動します。

マシンから portless を削除

portless clean

必要に応じてプロキシを停止し、portless CA をトラストストア から削除（portless が追加した場合）、状態ディレクトリ下の既知ファイルを削除、および portless /etc/hosts ブロックを削除します。macOS/Linux では sudo が必要な場合があります。

プロキシループ（508 Loop Detected）

開発サーバーが別の portless アプリにリクエストをプロキシする場合（例：Vite が /api を api.myapp.localhost にプロキシ）、プロキシは Host ヘッダーを書き直す必要があります。なしで、portless は要求を元のアプリにルーティングし、無限ループが生成されます。

修正: プロキシ設定で changeOrigin: true を設定（Vite、webpack-dev-server など）:

// vite.config.ts
proxy: {
  "/api": {
    target: "https://api.myapp.localhost",
    changeOrigin: true,
    ws: true,
  },
}

Portless は自動的に子プロセスで NODE_EXTRA_CA_CERTS を設定し、Node.js が portless CA を信頼するようにします。portless の外側で別の Node.js プロセスを実行する場合、CA を手動でポイント: NODE_EXTRA_CA_CERTS=~/.portless/ca.pem。または、--no-tls でプレーン HTTP を使用します。

Tailscale が機能していない

--tailscale または --funnel が失敗する場合:

tailscale status     # 接続を確認
tailscale up         # tailnet に接続

Tailscale CLI がインストール（https://tailscale.com/download）され PATH にある必要があります。

要件

• Node.js 20+
• macOS、Linux、または Windows
• openssl（--https 証明書生成用; macOS および ほとんどの Linux ディストリビューションに搭載; Windows では、winget install -e --id ShiningLight.OpenSSL.Dev 経由でインストールするか、Git for Windows に搭載されているコピーを使用）
• tailscale CLI（オプション、--tailscale および --funnel 用）