[python] port 9484 default + auto-increment; v0.7.5

Why: 9484 is the official IICP port. CLI now resolves the listen port before
NAT detection and auto-increments to the next free port, so N nodes on one
host bind 9484/9485/9486 → N pinholes, with multiple models sharing one port.
Skipped when --public-endpoint is set.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: RobLe3

README.md

@@ -135,6 +135,17 @@ async def main():
 asyncio.run(main())
 ```
 
+### Listen port — default 9484, auto-increment (v0.7.5+)
+
+The official IICP port **9484** is the default listen port (`IICP_PORT`, `--port`).
+The `iicp-node` CLI auto-increments to the next free port when 9484 is already in
+use, so you can run several nodes on one host without picking ports by hand — the
+first binds 9484, the second 9485, the third 9486, and so on. Each node gets its
+own port, hence its own NAT pinhole; multiple models served by one node share that
+single port. Auto-increment is skipped when you pass an explicit `--public-endpoint`
+(you own the port mapping in that case). `IicpNode.serve(port=…)` uses the port you
+give it as-is (no auto-increment at the library level).
+
 ---
 
 ## NAT traversal — automatic (v0.7.3+)

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iicp-client"
-version = "0.7.4"
+version = "0.7.5"
 description = "Official Python client SDK for the IICP protocol"
 readme = "README.md"
 license = {text = "Apache-2.0"}

src/iicp_client/__init__.py

@@ -49,7 +49,7 @@
     TaskResponse,
 )
 
-__version__ = "0.7.4"
+__version__ = "0.7.5"
 __all__ = [
     "IicpClient",
     "IicpError",

src/iicp_client/cli.py

@@ -26,6 +26,7 @@
 import json
 import logging
 import os
+import socket
 import subprocess
 import sys
 import urllib.parse
@@ -53,6 +54,26 @@ def _env(name: str, default: str | None = None) -> str | None:
     return os.environ.get(name, default)
 
 
+def _find_available_port(host: str, start: int, max_tries: int = 64) -> int:
+    """Return the first bindable TCP port >= ``start`` on ``host``.
+
+    The official IICP port 9484 is the starting point; when running multiple
+    nodes on one host (each model on its own port → its own pinhole) the second
+    node auto-increments to 9485, the third to 9486, and so on. Probes by
+    attempting a real bind so the chosen port is genuinely free before NAT
+    detection opens a pinhole and the directory registration advertises it.
+    """
+    bind_host = host if host not in ("", "0.0.0.0") else "0.0.0.0"
+    for candidate in range(start, start + max_tries):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+            try:
+                probe.bind((bind_host, candidate))
+                return candidate
+            except OSError:
+                continue
+    return start  # exhausted — let serve() surface the real bind error
+
+
 def _build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(
         prog="iicp-node",
@@ -128,7 +149,7 @@ def _build_parser() -> argparse.ArgumentParser:
     serve.add_argument(
         "--port",
         type=int,
-        default=int(_env("IICP_PORT", "8020") or "8020"),
+        default=int(_env("IICP_PORT", "9484") or "9484"),
         help="HTTP listen port. env: IICP_PORT",
     )
     serve.add_argument(
@@ -208,7 +229,7 @@ async def _serve(args: argparse.Namespace) -> int:
         args.node_id = args.node_id or saved.node_id
         if args.max_concurrent == 4:
             args.max_concurrent = saved.max_concurrent
-        if args.port == 8020:
+        if args.port == 9484:
             args.port = saved.port
         if args.host == "0.0.0.0":
             args.host = saved.host
@@ -225,6 +246,21 @@ async def _serve(args: argparse.Namespace) -> int:
         )
         return 2
 
+    # Resolve the actual listen port before NAT detection: start at the
+    # requested port (default 9484, the official IICP port) and auto-increment
+    # to the next free port. This keeps one port per node (multiple models on
+    # one node share it) while N nodes on one host each get a distinct port →
+    # distinct pinhole. Skipped when the operator supplies an explicit
+    # --public-endpoint (they own the port mapping in that case).
+    if not args.public_endpoint:
+        resolved_port = _find_available_port(args.host, args.port)
+        if resolved_port != args.port:
+            logger.info(
+                "Port %d in use — auto-incremented to first free port %d.",
+                args.port, resolved_port,
+            )
+        args.port = resolved_port
+
     node_id = (args.node_id or str(uuid.uuid4()))[:36]
     public_endpoint = args.public_endpoint or f"http://localhost:{args.port}"
 
@@ -467,7 +503,7 @@ def _cmd_init(args: argparse.Namespace) -> int:
     intent = _prompt("Intent URN", "urn:iicp:intent:llm:chat:v1")
     region = _prompt("Region tag", "eu-central")
     directory_url = _prompt("Directory URL", "https://iicp.network/api")
-    port_str = _prompt("Local HTTP port", "8020")
+    port_str = _prompt("Local HTTP port", "9484")
     port = int(port_str)
     public_endpoint = _prompt(
         "Public endpoint URL (leave blank if you'll use --auto-detect-nat)",

src/iicp_client/node.py

@@ -204,7 +204,7 @@ async def my_handler(task: dict) -> dict:
             max_concurrent=4,
         ))
         token = await node.register()
-        await node.serve(my_handler, port=8020, node_token=token)
+        await node.serve(my_handler, port=9484, node_token=token)
     """
 
     def __init__(self, config: NodeConfig) -> None:
@@ -468,15 +468,15 @@ async def serve(
         self,
         handler: TaskHandler,
         host: str = "0.0.0.0",
-        port: int = 8020,
+        port: int = 9484,
         node_token: str | None = None,
     ) -> None:
         """Start the task server (blocks until interrupted).
 
         Args:
             handler:    ``async def handler(task: dict) -> dict``
             host:       Bind address (default ``0.0.0.0``).
-            port:       Bind port (default 8020).
+            port:       Bind port (default 9484).
             node_token: If provided, starts a background heartbeat loop.
         """
         loop = asyncio.get_event_loop()