菜单
Design and document a port assignment strategy for local development environments. Use when setting up new projects, resolving port conflicts, or establishing team conventions for port usage across services.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
Apply idiomatic, well-structured Python development practices. Use when writing, reviewing, or refactoring Python code. Covers type annotations, package management with uv, Pydantic DTOs, Typer CLIs, pytest patterns, PEP 8 style, architecture, and type-driven design.
How to manage Python dependencies with UV — inline script metadata (PEP 723), project mode, tool running, and when to use each approach. Always use UV; never pip directly.
Use when receiving code review feedback (especially if unclear or technically questionable), when completing tasks or major features requiring review before proceeding, or before making any completion/success claims. Covers four practices — receiving feedback with technical rigor, requesting reviews via code-reviewer subagent, verification gates requiring evidence before claims, and security/API-compat awareness. Essential for subagent-driven development, pull requests, and preventing false completion claims.
Synthesize knowledge from multiple sources into Zettelkasten notes for Logseq. Use when creating wiki pages, integrating academic research, or building interconnected knowledge with [[links]] and
Survey a Google Drive's actual folder structure, apply a PARA-lite organization framework, and produce (then safely execute) a concrete reorganization plan — deduping, sweeping root-level clutter, and fixing misnested folders.
Idiomatic review for Rust — async/Tokio daemon design, ports-and-adapters trait boundaries, and thiserror/anyhow error handling. Use when reviewing or writing Rust code that defines async trait "ports" (dependency-inversion boundaries), runs a single-threaded Tokio daemon (current_thread runtime + LocalSet/spawn_local), or crosses a wire/domain type boundary. Covers async fn in traits vs async-trait, Rc/RefCell vs Arc/Mutex, tokio::select! cancel-safety, blocking calls in async context, thiserror-vs-anyhow error typing, wire/domain type separation, and common anti-patterns (clone in hot loops, overly generic port bounds). NOT for pure performance/profiling work (see rust-profiling, rust-perf-tuning, rust-memory-optimization, rust-parallel-processing) or unsafe/CLI/wasm-bindgen review (no dedicated skill yet — use the sdd:6-verify research-agent fallback for those).
| name | local-dev-port-management |
| description | Design and document a port assignment strategy for local development environments. Use when setting up new projects, resolving port conflicts, or establishing team conventions for port usage across services. |
Apply this skill when choosing, documenting, or fixing port assignments for local development services.
| Range | Numbers | Rules |
|---|---|---|
| System / Well-Known | 0–1023 | Requires root on Unix. Reserved for OS/standard protocols. Avoid entirely in dev. |
| Registered / User | 1024–49151 | Where all dev tools live. IANA-assigned defaults cluster here. |
| Dynamic / Ephemeral | 49152–65535 | OS assigns these temporarily for client connections. Linux default: 32768–60999 (readable from /proc/sys/net/ipv4/ip_local_port_range). Never hardcode services here — the OS will steal them on restart. |
| Port | Service |
|---|---|
| 3000 | Express, React (CRA), many Node tools |
| 4000 | Firebase Emulator UI |
| 5000 | Firebase Hosting emulator, Overmind/Hivemind base port, Flask (Linux) |
| 5001 | Firebase Functions emulator, Flask (macOS since 2.3+) |
| 5002 | Firebase App Hosting emulator |
| 5173 | Vite dev server |
| 5432 | PostgreSQL |
| 6379 | Redis |
| 8080 | Firebase Firestore emulator, generic HTTP alternative |
| 8085 | Firebase Pub/Sub emulator |
| 9000 | Firebase Realtime Database emulator |
| 9099 | Firebase Auth emulator |
| 9199 | Firebase Cloud Storage emulator |
| 9229 | Node.js inspector (debugger) |
| 27017 | MongoDB |
Define all ports centrally. Every service reads from that file. Zero runtime magic.
# gradle.properties (Gradle projects)
webApp.devPort=3001
firebase.emulator.firestore=9090
firebase.emulator.auth=9099
# .env (Node/general)
WEB_PORT=3001
API_PORT=3002
DB_PORT=5432
Rule: Firestore emulator should NOT be on 8080 — webpack, most HTTP servers, and Java app servers all default there. Move it to 9090.
Assign each project a 100-port block in the registered range. Document in a team wiki.
Project A: 3100–3199 (web: 3100, api: 3101, db proxy: 3102)
Project B: 3200–3299
Project C: 3300–3399
Tools like Overmind/Hivemind automate this: they assign BASE + (process_index × STEP) and inject PORT env var into each process.
Both tools read a Procfile, start each process, and assign ports sequentially:
# Procfile
web: ./gradlew :webApp:wasmJsBrowserDevelopmentRun
api: ./gradlew :cliApp:run
# Overmind — start all with base port 3000, step 100
PORT=3000 overmind start
# web gets 3000, api gets 3100
# Each process also sees OVERMIND_PROCESS_<name>_PORT for siblings
Overmind is preferred over Hivemind for projects that need process restart control (overmind restart web).
vercel-labs/portless replaces port numbers with .localhost names:
https://web.localhost instead of http://localhost:3001PORT env varport-for stores stable name→port bindings in /etc/port-for.conf:
sudo port-for add myapp # assigns and persists a stable port for "myapp"
port-for show myapp # always returns same port
Survives machine restarts. Avoids ephemeral range collisions by reading the OS range at runtime.
For services running in Kubernetes, Telepresence routes cluster traffic to your local machine. Local port and cluster port can differ:
telepresence intercept my-service --port 3001:8080
# local :3001 intercepts cluster :8080 traffic
Eliminates port management entirely for remote-dependent services.
| Situation | Strategy |
|---|---|
| Solo developer, 1–3 services | .env / gradle.properties with explicit ports |
| Team project, multiple services per dev | Per-project port ranges documented in wiki |
| Frequently starting/stopping many services | Procfile + Overmind |
| Sick of remembering port numbers | Portless (named subdomains) |
| Stable named ports needed system-wide | port-for |
| Kubernetes microservices dev | Telepresence |
The pattern: claim a sequential block of N ports from the IANA dynamic range (49152–65535), above the OS ephemeral ceiling.
Why above the ephemeral ceiling? On Linux the ephemeral range tops at 60999 by default. Ports 61000–65535 are in the IANA dynamic range but the kernel never assigns them to outbound connections — no ip_local_reserved_ports needed. On macOS (ephemeral extends to 65535) you need explicit reservation.
Algorithm for grabbing a batch:
cat /proc/sys/net/ipv4/ip_local_port_range (Linux) or sysctl net.inet.ip.portrange.last (macOS)ceiling + 1 (Linux: 61000) or reserve via ip_local_reserved_ports/sysctlss -tlnp | grep -E ':(61000|61001|...)'/etc/sysctl.d/99-project-ports.conf, macOS: LaunchDaemon plist)Reservation script (create as scripts/reserve-ports.sh):
ip_local_reserved_ports (Linux) or narrows ephemeral start (macOS)--check for dry-run, --show for port tablePicking your base: anything above your OS ephemeral ceiling works. Simple choices:
Sequential batch 64386–64395 — derived from project name, not a round number:
# gradle.properties — base 64386 = 61000 + CRC32("sortie") % 4525
webApp.devPort=64386
firebase.emulator.ui=64387
firebase.emulator.auth=64388
firebase.emulator.firestore=64389
firebase.emulator.functions=64390
firebase.emulator.hosting=64391
# 64392-64395 spare
// firebase.json emulators section
{ "auth": {"port": 61002}, "firestore": {"port": 61003},
"functions": {"port": 61004}, "hosting": {"port": 61005},
"ui": {"enabled": true, "port": 61001} }
make reserve-ports — checks batch availability, reserves on macOS if needed, shows port table.
make ports — shows the assignment table without any changes.