Portless

Replace port numbers with stable, named .localhost URLs. For humans and agents.

1 — 概要
何か

Portless は、ローカル開発で「ポート番号」の代わりに、安定した名前付き .localhost URL を割り当てる CLI。プロキシが固定ポート（デフォルト 1355）で待ち受け、各アプリは http://<名前>.localhost:1355 で一意にアクセスできる。人間が覚えやすく、AI コーディングエージェントも同じ URL を前提にできる。

1355プロキシ固定ポート
4000–4999アプリ用エフェメラル
Node 20+macOS / Linux
Vercel LabsApache-2.0

ポート競合・覚えづらい番号・タブの取り違え・モノレポでの増幅・エージェントのポート勘違い・Cookie/storage の衝突・CORS/OAuth の固定ポート問題・URL 共有の手間・履歴の混在といった「ポート依存」の問題を、名前ベースの URL に置き換えて解消する。

2 — 使い方
Quick Start

グローバルにインストールして portless run <コマンド> でプロジェクト名を自動推論し、プロキシ経由で起動する。プロキシは必要なら自動起動される。

npm install -g portless
portless run next dev
# -> http://<project>.localhost:1355

portless myapp next dev
# -> http://myapp.localhost:1355

サブドメイン・Git Worktrees

portless api.myapp pnpm start で http://api.myapp.localhost:1355 のようにサブドメインも使える。ワイルドカードで tenant1.myapp.localhost:1355 なども同じルートに流れる。

Git worktree では、リンクされた worktree にいるとブランチ名がサブドメインになる（例: fix-ui ブランチなら http://fix-ui.myapp.localhost:1355）。package.json に "dev": "portless run next dev" を 1 回書けば、main と各 worktree でそのまま使える。

package.json 
"scripts": {
  "dev": "portless run next dev"
}
3 — 仕組み
流れ
Browser (myapp.localhost:1355) → portless proxy (1355) → App (例: 4123)
  1. プロキシ起動 — portless proxy start（またはアプリ起動時に自動）でポート 1355 で待ち受け。
  2. アプリ起動 — portless <name> <cmd> が空きポート（4000–4999）を割り当て、プロキシに名前とポートを登録。子プロセスには PORT / HOST / PORTLESS_URL を注入。
  3. アクセス — http://<name>.localhost:1355 がプロキシ経由で該当アプリに転送される。

Next.js / Express / Nuxt などは PORT を読む。Vite / Astro / React Router などは portless が --port / --host を自動付与する。

4 — コマンド一覧
サブコマンド
コマンド説明
portless run <cmd> [args...]プロジェクトから名前を推論して実行
portless <name> <cmd> [args...]名前を指定して http://<name>.localhost:1355 で公開
portless alias <name> <port>静的なルート登録（Docker など）
portless listアクティブなルート一覧
portless trustローカル CA をシステム信頼に追加
portless hosts sync/etc/hosts にルートを追加（Safari 用）
portless proxy start|stopプロキシの起動・停止。--https で HTTP/2+TLS

無効化: PORTLESS=0 pnpm dev でプロキシをバイパスし、通常のデフォルトポートで実行できる。

5 — HTTPS・状態・Safari
HTTP/2 + HTTPS

portless proxy start --https で証明書を自動作成し、初回のみ sudo portless trust で CA を信頼すればブラウザ警告なし。PORTLESS_HTTPS=1 で常時 HTTPS にできる。

状態ディレクトリ

ポート < 1024（要 sudo）のときは /tmp/portless、それ以外は ~/.portless。PORTLESS_STATE_DIR で上書き可能。

Safari: .localhost サブドメインは Chrome/Firefox/Edge では自動解決されるが、Safari はシステム DNS に依存する場合がある。sudo portless hosts sync で /etc/hosts にルートを追加すると解消。PORTLESS_SYNC_HOSTS=1 で変更時に自動同期可能（proxy を sudo で起動する必要あり）。
公式・関連