portless

Portless 連携

ローカル開発用の名前付き .localhost URL。localhost:3000 を https://myapp.localhost に置き換えます。

CLI の完全なリファレンス：コマンドの詳細については、Read("references/upstream.md") を読み込んでください。

2026-04 → 2026-07 の新機能（portless 0.10.x → 0.15.0）

• portless doctor（0.15.0） — Node.js、状態ディレクトリ、プロキシの稼働状況、ルートエントリ、ホスト名の解決、HTTPS CA の信頼設定、LAN の前提条件を読み取り専用で診断し、推奨される修正方法を表示します。問題を報告する前や、.localhost URL が解決されない場合に実行してください。
• HTTP/2 Host 転送の修正（0.15.0） — プロキシが HTTP/2 の :authority を HTTP/1.1 バックエンドに Host として転送するようになりました。これにより、Host を読み取るアプリがブラウザーのトラフィックで 127.0.0.1 を受け取っていた問題が修正されます。--force による引き継ぎ時のクリーンアップでは、終了するプロセスがまだ所有しているルートだけを削除するようになり、強制的に引き継いだ新しい所有者のルートが登録解除されなくなりました。
• --ngrok フラグ（0.14.0） — ローカルアクセスでは .localhost URL を維持しながら、ngrok 経由でアプリを公開できます。名前付きサブドメインを使った開発環境を維持したまま公開 URL が必要な場合は、既存の Tailscale／Funnel オプションと組み合わせてください。
• Node.js 24 以降が必須（0.13.1、破壊的変更） — プロキシと CLI では Node.js 24 以降が必須になりました。古いランタイムはサポートされません。このリリースでは、起動サービスの永続化も強化され、.localhost URL が再起動後も確実に維持されるようになりました。
• 状態ディレクトリを ~/.portless に移動（0.11、破壊的変更） — 状態を分散していた一時的な場所から ~/.portless に移動しました。PORTLESS_STATE_DIR で変更できます。0.11 より前のインストールで使われていた古い状態は自動的に移行されません。
• OS の起動サービス（0.13.0） — portless service install ／ service status ／ service uninstall を実行すると、macOS の launchd、Linux の systemd、Windows のタスク スケジューラを使って HTTPS プロキシのネイティブ起動サービスを登録できます。手動で portless proxy start を実行しなくても、.localhost URL は再起動後も維持されます。portless clean は CA と hosts のクリーンアップとともにサービスを削除します。
• Tailscale の準備状況の事前チェック（0.13.0） — --tailscale と --funnel は、子プロセスを起動する前に Tailscale HTTPS と Funnel の前提条件を検証します。登録中に処理が停止する代わりに、対処可能なエラーが表示されます。
• Tailscale 連携（0.12.0） — --tailscale はポート 443 で HTTPS を自動設定し、tailnet 経由でアプリを共有します。--funnel は Tailscale Funnel 経由でアプリを公開します。アプリには PORTLESS_TAILSCALE_URL が渡されるため、自身の公開アドレスを参照できます。portless list に tailnet の URL が表示されるようになりました。
• ゼロ設定モード（0.11.0） — 引数なしの portless は package.json から開発スクリプトを自動検出します。複数のアプリがあるモノレポではサブドメインが自動的に割り当てられます。Turborepo のタスクグラフ連携も組み込まれています。portless.json 設定ファイルに対応しました。--script でデフォルトの「dev」スクリプトを上書きできます。
• portless prune — 孤立した開発サーバーと古い Tailscale 登録を削除します。
• portless clean（機能拡張） — CA と hosts のクリーンアップとともに、Tailscale 登録も解除するようになりました。
• Rsbuild + VitePlus のポート自動注入 — Vite／Next と同様に自動連携します。
• 状態ディレクトリ を ~/.portless に移動しました（以前は分散していました）。
• デフォルトでポート 443 の HTTPS（0.9.x の http:1355 からの破壊的変更）。有効な証明書が使用され、設定は不要です。--no-tls で元に戻せます。
• NODE_EXTRA_CA_CERTS を自動注入（0.10.2） — 子プロセスに注入されるため、Node.js の HTTPS 呼び出しは設定なしで portless CA を信頼します。
• --wildcard サブドメイン — マルチテナント／プレビューのルーティングに https://*.myapp.localhost を使用できます。
• portless alias <name> <port> — 長時間稼働する run プロセスを使わずに、docker-compose のポートやエミュレートされたポートを名前付き URL に割り当てます。
• portless clean — 完全なクリーンアップを行います。プロキシを停止し、CA を削除し、状態を消去して、/etc/hosts をクリーンアップします。
• --lan モード — ルーターの設定なしで、mDNS の .local ホスト名を Wi-Fi 経由で利用可能にします（スマートフォン、タブレット、ほかのマシンからアクセスできます）。
• アプリの固定ポート — 既知のポートが必要なツール（デバッガー、docker）向けに、--app-port 3000 ／ PORTLESS_APP_PORT を指定できます。
• Safari との互換性のため、hosts-sync はデフォルトで有効です（PORTLESS_SYNC_HOSTS=0 で無効化できます）。
• Vite／VitePlus／Next.js 開発環境向けの HTTP/2 HMR 修正 — h2 使用時に WebSocket のアップグレードが失敗しなくなりました。
• Expo／React Native に対応 — portless run expo start を実行すると、Metro に安定した URL が割り当てられ、デバイス用 QR コードで利用できます。

使用する場面

• エージェントやブラウザーテストの接続先となる開発サーバーを起動する場合
• 複数のサービス（API＋フロントエンド＋ドキュメント）をローカルで実行する場合
• Git ワークツリーで作業する場合（ブランチ名のサブドメインを使用）
• ローカルの OAuth フローを行う場合（安定したコールバック URL を使用）
• emulate API モックを名前付き URL に接続する場合

クイックスタート

# Instead of: npm run dev (random port)
portless run npm run dev
# → https://myapp.localhost (stable, named, HTTPS on 443 — default in 0.10+)

# Multi-service
portless run --name api npm run dev:api
portless run --name web npm run dev:web
# → https://api.localhost, https://web.localhost

# LAN mode (0.10.0) — reachable from phone/tablet via mDNS
portless proxy start --lan
portless run npm run dev
# → https://myapp.local (resolves across the local network, no router config)

# Full teardown (0.10.1) — stops proxy, removes CA, wipes state, cleans /etc/hosts
portless clean

# Boot persistence (0.13.0) — install native startup service (launchd / systemd / Task Scheduler)
portless service install
portless service status
# Removed automatically by `portless clean`, or explicitly:
portless service uninstall

0.10.x の破壊的変更： デフォルトがポート 443 の https://app.localhost に変更されました。元に戻すには --no-tls を使用してください。NODE_EXTRA_CA_CERTS は子プロセスに自動的に注入されます（0.10.2）— 証明書を手動で設定する必要はありません。Safari 用の /etc/hosts は自動的に同期されます。無効にするには PORTLESS_SYNC_HOSTS=0 を設定してください。

フレームワーク別のセットアップ

フレームワーク別の手順全体については、Read("references/framework-integration.md") を読み込んでください。

ほとんどのフレームワーク（Next.js、Vite、Express）は portless run <cmd> で動作します。明示的なフラグが必要なものもあります。

フレームワーク	自動検出	追加で必要なフラグ
Next.js	はい	なし
Vite / Astro	はい	なし
Express / Fastify / Hono	はい	なし（PORT 環境変数を読み取ります）
Ruby on Rails	はい	なし
FastAPI / uvicorn	いいえ	--port $PORT --host $HOST
Django	いいえ	$HOST:$PORT 位置引数

.localhost を使う理由

機能	.localhost（RFC 6761）	127.0.0.1:PORT	/etc/hosts の回避策
/etc/hosts の編集不要	はい	はい	いいえ
有効な証明書で HTTPS を利用可能	はい	いいえ	手動
ワイルドカードサブドメイン	はい	いいえ	いいえ
すべてのブラウザーで動作	はい	はい	異なります
サービスごとの Cookie 分離	はい	いいえ	はい
ポートの競合なし	はい	いいえ	はい

主な環境変数

portless がコマンドを実行すると、次の値が注入されます。

変数	値	エージェントでの用途
PORT	割り当てられた一時ポート（4000-4999）	内部のみ
HOST	127.0.0.1	内部のみ
PORTLESS_URL	https://myapp.localhost	エージェントのプロンプトではこれを使用してください
NODE_EXTRA_CA_CERTS	portless CA へのパス (0.10.2 で自動注入)	子の Node プロセスは設定なしで portless の証明書を信頼します

環境変数の切り替え

変数	効果
PORTLESS=0	portless を完全にバイパスします（CI）
PORTLESS_SYNC_HOSTS=0	/etc/hosts の自動同期を無効にします（デフォルト：0.10.1 以降は有効）
PORTLESS_STATE_DIR	状態ディレクトリを上書きします（デフォルト：~/.portless、特権ポートの場合は /tmp/portless）

OrchestKit の統合パターン

1. エージェントからアクセス可能な開発サーバー

# Start with portless, then agents can target PORTLESS_URL
portless run npm run dev

# In ork:expect or agent-browser:
agent-browser open $PORTLESS_URL

2. Emulate ＋ Portless（名前付き API モック）

# Register emulate ports as named aliases
portless alias github-api 4001
portless alias vercel-api 4000
portless alias google-api 4002

# Now agents can target:
#   https://github-api.localhost — GitHub emulator
#   https://vercel-api.localhost — Vercel emulator

3. Git ワークツリーでの開発

# In worktree for feature/auth-flow:
portless run npm run dev
# → https://auth-flow.myapp.localhost (auto branch prefix)

4. CI でのバイパス

# Disable portless in CI — direct port access
PORTLESS=0 npm run dev

アンチパターン

してはいけないこと	代わりにすること
テストで localhost:3000 をハードコードする	PORTLESS_URL または process.env.PORTLESS_URL を使用する
CI で portless を実行する	CI 環境で PORTLESS=0 を設定する
AGENTS.md で数値のポートを使う	portless の URL を記載する

参考資料

ファイル	内容
references/upstream.md	portless CLI の完全なリファレンス（Vercel と同期）
references/upstream-oauth.md	安定した URL を使用する OAuth コールバックのパターン
references/framework-integration.md	フレームワーク別の手順（FastAPI、Django、Docker、注意事項）
checklists/new-project-setup.md	手順：新しいプロジェクトに portless を追加する