fix: Port contention issues between Ray/vLLM/Gym and sandbox workers

docs/cluster.md

@@ -152,36 +152,38 @@ sbatch ray.sub \
   - Number of GPUs each Ray worker node claims. To determine this, run `nvidia-smi` on a worker node.
 * - `BASE_LOG_DIR=$SLURM_SUBMIT_DIR`
   - Base directory for storing Ray logs. Defaults to the Slurm submission directory ([SLURM_SUBMIT_DIR](https://slurm.schedmd.com/sbatch.html#OPT_SLURM_SUBMIT_DIR)).
-* - `NODE_MANAGER_PORT=53001`
+* - `NODE_MANAGER_PORT=1301`
   - Port for the Ray node manager on worker nodes.
-* - `OBJECT_MANAGER_PORT=53003`
+* - `OBJECT_MANAGER_PORT=1303`
   - Port for the Ray object manager on worker nodes.
-* - `RUNTIME_ENV_AGENT_PORT=53005`
+* - `RUNTIME_ENV_AGENT_PORT=1305`
   - Port for the Ray runtime environment agent on worker nodes.
-* - `DASHBOARD_AGENT_GRPC_PORT=53007`
+* - `DASHBOARD_AGENT_GRPC_PORT=1307`
   - gRPC port for the Ray dashboard agent on worker nodes.
-* - `METRICS_EXPORT_PORT=53009`
+* - `METRICS_EXPORT_PORT=1309`
   - Port for exporting metrics from worker nodes.
-* - `PORT=6379`
+* - `PORT=1200`
   - Main port for the Ray head node.
-* - `RAY_CLIENT_SERVER_PORT=10001`
+* - `RAY_CLIENT_SERVER_PORT=1201`
   - Port for the Ray client server on the head node.
 * - `DASHBOARD_GRPC_PORT=52367`
   - gRPC port for the Ray dashboard on the head node.
 * - `DASHBOARD_PORT=8265`
   - Port for the Ray dashboard UI on the head node. This is also the port
     used by the Ray distributed debugger.
-* - `DASHBOARD_AGENT_LISTEN_PORT=52365`
+* - `DASHBOARD_AGENT_LISTEN_PORT=1311`
   - Listening port for the dashboard agent on the head node.
-* - `MIN_WORKER_PORT=54001`
+* - `MIN_WORKER_PORT=2000`
   - Minimum port in the range for Ray worker processes.
-* - `MAX_WORKER_PORT=54257`
+* - `MAX_WORKER_PORT=2999`
   - Maximum port in the range for Ray worker processes.
 ``````
 
 > [!NOTE]
 > For the most part, you will not need to change ports unless these
 > are already taken by some other service backgrounded on your cluster.
+> The defaults above are the source-of-truth port layout defined in `ray.sub`;
+> keep this table in sync with that block if the defaults ever change.
 
 ### Topology-Aware Placement for MoE (avoiding cross-rack stalls)
 

examples/configs/distillation_math.yaml

@@ -190,8 +190,8 @@ policy: &POLICY_BASE
     generation:
         # Port range for vLLM HTTP servers, kept below the OS ephemeral range.
         # See ray.sub for the full port layout.
-        port_range_low: 11001
-        port_range_high: 15000
+        port_range_low: 3000
+        port_range_high: 4999
         backend: "vllm"
         max_new_tokens: ${..max_total_sequence_length} # refer to local policy/teacher config
         temperature: 1.0
@@ -280,6 +280,6 @@ logger:
 cluster:
     gpus_per_node: 8
     num_nodes: 1
-    master_port_range_low: 25000
-    master_port_range_high: 28000
+    master_port_range_low: 1400
+    master_port_range_high: 1999
     segment_size: null  # Nodes per NVLink domain segment for topology-aware alignment; null to disable

examples/configs/grpo_math_1B.yaml

@@ -327,8 +327,8 @@ policy:
   generation:
     # Port range for vLLM HTTP servers, kept below the OS ephemeral range.
     # See ray.sub for the full port layout.
-    port_range_low: 11001
-    port_range_high: 15000
+    port_range_low: 3000
+    port_range_high: 4999
     backend: "vllm"
     max_new_tokens: ${policy.max_total_sequence_length}
     temperature: 1.0
@@ -461,8 +461,8 @@ cluster:
   # Port range for the distributed master address (TCPStore / NCCL rendezvous)
   # and per-worker available ports.  Kept below the OS ephemeral range
   # (32768-60999 on stock Linux).  See ray.sub for the full port layout.
-  master_port_range_low: 25000
-  master_port_range_high: 28000
+  master_port_range_low: 1400
+  master_port_range_high: 1999
   segment_size: null  # Nodes per NVLink domain segment for topology-aware alignment; null to disable
 
 # TransferQueue-mediated data plane for sync GRPO.

examples/nemo_gym/distillation_qwen3_0_6b.yaml

@@ -94,8 +94,8 @@ env:
   should_use_nemo_gym: true
   should_log_nemo_gym_responses: false
   nemo_gym:
-    port_range_low: 15001
-    port_range_high: 20000
+    port_range_low: 5000
+    port_range_high: 5999
     config_paths:
       - responses_api_models/vllm_model/configs/vllm_model_for_training.yaml
       - resources_servers/example_multi_step/configs/example_multi_step.yaml

examples/nemo_gym/grpo_nanov3.yaml

@@ -195,8 +195,8 @@ policy:
   generation:
     # Port range for vLLM HTTP servers, kept below the OS ephemeral range.
     # See ray.sub for the full port layout.
-    port_range_low: 11001
-    port_range_high: 15000
+    port_range_low: 3000
+    port_range_high: 4999
     backend: "vllm"
     max_new_tokens: ${policy.max_total_sequence_length}
     temperature: 1.0
@@ -304,10 +304,10 @@ env:
   should_log_nemo_gym_responses: true
   nemo_gym:
     # Port range for Gym HTTP servers, kept below the OS ephemeral range
-    # (32768-60999) and non-overlapping with NeMo RL (11001-15000) or
-    # vLLM (20001+). See ray.sub for the full port layout.
-    port_range_low: 15001
-    port_range_high: 20000
+    # (below the 9000 ephemeral floor on some GB200 nodes) and non-overlapping with NeMo
+    # RL (3000-4999) or vLLM (7000-8999). See ray.sub for the full port layout.
+    port_range_low: 5000
+    port_range_high: 5999
     # Optional substrings/tags used to flag malformed assistant turns for advantage
     # penalties (see grpo.invalid_tool_call_advantage / malformed_thinking_advantage).
     # Omit to use the built-in defaults (DEFAULT_INVALID_TOOL_CALL_PATTERNS / DEFAULT_THINKING_TAGS).
@@ -363,5 +363,5 @@ logger:
 cluster:
   gpus_per_node: 8
   num_nodes: 32
-  master_port_range_low: 25000
-  master_port_range_high: 28000
+  master_port_range_low: 1400
+  master_port_range_high: 1999

examples/nemo_gym/grpo_qwen3_30ba3b_thinking_swe1.yaml

@@ -90,8 +90,8 @@ policy:
       fp8_param: false
   make_sequence_length_divisible_by: 16
   generation:
-    port_range_low: 11001
-    port_range_high: 15000
+    port_range_low: 3000
+    port_range_high: 4999
     max_new_tokens: ${policy.max_total_sequence_length}
     vllm_cfg:
       enable_prefix_caching: true
@@ -219,8 +219,8 @@ env:
   should_log_nemo_gym_responses: false
   nemo_gym:
     skip_venv_if_present: true
-    port_range_low: 15001
-    port_range_high: 20000
+    port_range_low: 5000
+    port_range_high: 5999
     config_paths:
     - responses_api_models/vllm_model/configs/vllm_model_for_training.yaml
     - resources_servers/single_step_tool_use_with_argument_comparison/configs/swe_pivot_single_step_tool_use_with_argument_comparison.yaml

examples/nemo_gym/grpo_qwen3_30ba3b_thinking_swe2.yaml

@@ -89,8 +89,8 @@ policy:
       fp8_param: false
   make_sequence_length_divisible_by: 32
   generation:
-    port_range_low: 11001
-    port_range_high: 15000
+    port_range_low: 3000
+    port_range_high: 4999
     max_new_tokens: ${policy.max_total_sequence_length}
     vllm_cfg:
       enable_prefix_caching: true
@@ -218,8 +218,8 @@ env:
   should_log_nemo_gym_responses: false
   nemo_gym:
     skip_venv_if_present: true
-    port_range_low: 15001
-    port_range_high: 20000
+    port_range_low: 5000
+    port_range_high: 5999
     config_paths:
     - responses_api_models/vllm_model/configs/vllm_model_for_training.yaml
     - responses_api_agents/swe_agents/configs/swebench_openhands_training.yaml

examples/nemo_gym/grpo_workplace_assistant_nemotron_nano_v2_9b.yaml

@@ -291,10 +291,10 @@ env:
   should_log_nemo_gym_responses: true
   nemo_gym:  # This is passed into NeMo-Gym as the initial_global_config_dict
     # Port range for Gym HTTP servers, kept below the OS ephemeral range
-    # (32768-60999) and non-overlapping with NeMo RL (11001-15000) or
-    # vLLM (20001+). See ray.sub for the full port layout.
-    port_range_low: 15001
-    port_range_high: 20000
+    # (below the 9000 ephemeral floor on some GB200 nodes) and non-overlapping with NeMo
+    # RL (3000-4999) or vLLM (7000-8999). See ray.sub for the full port layout.
+    port_range_low: 5000
+    port_range_high: 5999
     rollout_max_attempts_to_avoid_lp_nan: 1
     is_trajectory_collection: false  # Set this to true to enable trajectory collection (no training). You may also want to increase `policy.generation.vllm_cfg.gpu_memory_utilization`
     config_paths:

examples/nemo_gym/nemotron-3-super/stage1_rlvr.yaml

@@ -214,8 +214,8 @@ policy:
   scheduler: null
 
   generation:
-    port_range_low: 11001
-    port_range_high: 15000
+    port_range_low: 3000
+    port_range_high: 4999
     backend: "vllm"
     max_new_tokens: ${policy.max_total_sequence_length}
     temperature: 1.0
@@ -284,8 +284,8 @@ env:
     uv_venv_dir: "${oc.env:PERSISTENT_CACHE}/gym_venvs"
     skip_venv_if_present: true
     num_gpu_nodes: 7
-    port_range_low: 15001
-    port_range_high: 20000
+    port_range_low: 5000
+    port_range_high: 5999
     invalid_tool_call_patterns:
       - "<tool_call>"
       - "</tool_call>"

examples/nemo_gym/nemotron-3-super/stage2_swe1.yaml

@@ -214,8 +214,8 @@ policy:
   scheduler: null
 
   generation:
-    port_range_low: 11001
-    port_range_high: 15000
+    port_range_low: 3000
+    port_range_high: 4999
     backend: "vllm"
     max_new_tokens: ${policy.max_total_sequence_length}
     temperature: 1.0
@@ -293,8 +293,8 @@ env:
     thinking_tags:
       - "<think>"
       - "</think>"
-    port_range_low: 15001
-    port_range_high: 20000
+    port_range_low: 5000
+    port_range_high: 5999
     config_paths:
     - responses_api_models/vllm_model/configs/vllm_model_for_training.yaml
     - resources_servers/single_step_tool_use_with_argument_comparison/configs/swe_pivot_single_step_tool_use_with_argument_comparison.yaml

examples/nemo_gym/nemotron-3-super/stage2_swe2.yaml

@@ -207,8 +207,8 @@ policy:
   scheduler: null
 
   generation:
-    port_range_low: 11001
-    port_range_high: 15000
+    port_range_low: 3000
+    port_range_high: 4999
     backend: "vllm"
     max_new_tokens: ${policy.max_total_sequence_length}
     temperature: 1.0
@@ -289,8 +289,8 @@ env:
     thinking_tags:
       - "<think>"
       - "</think>"
-    port_range_low: 15001
-    port_range_high: 20000
+    port_range_low: 5000
+    port_range_high: 5999
     config_paths:
     - responses_api_models/vllm_model/configs/vllm_model_for_training.yaml
     - responses_api_agents/swe_agents/configs/swebench_openhands_training.yaml

examples/nemo_gym/nemotron-3-super/stage3_rlhf.yaml

@@ -214,8 +214,8 @@ policy:
   scheduler: null
 
   generation:
-    port_range_low: 11001
-    port_range_high: 15000
+    port_range_low: 3000
+    port_range_high: 4999
     backend: "vllm"
     max_new_tokens: ${policy.max_total_sequence_length}
     temperature: 1.0
@@ -285,8 +285,8 @@ env:
     uv_venv_dir: "${oc.env:PERSISTENT_CACHE}/gym_venvs"  # overridden by super_launch.sh to $GYM_VENV_DIR
     skip_venv_if_present: true
     num_gpu_nodes: 4
-    port_range_low: 15001
-    port_range_high: 20000
+    port_range_low: 5000
+    port_range_high: 5999
     invalid_tool_call_patterns:
       - "<tool_call>"
       - "</tool_call>"

examples/nemo_gym/prefetch_super_all_envs.yaml

@@ -8,8 +8,8 @@ env:
   should_use_nemo_gym: true
   nemo_gym:
     skip_venv_if_present: true
-    port_range_low: 15001
-    port_range_high: 20000
+    port_range_low: 5000
+    port_range_high: 5999
 
     # Dummy interpolation values for the bundled configs (unused in the dry run).
     policy_model_name: dummy-model

nemo_rl/distributed/virtual_cluster.py

@@ -39,7 +39,7 @@ class ClusterConfig(TypedDict):
     # kept below the OS ephemeral range (32768-60999 on stock Linux) to avoid
     # TOCTOU collisions with kernel-assigned source ports.  When absent,
     # RayVirtualCluster falls back to DEFAULT_MASTER_PORT_RANGE_LOW/HIGH
-    # (25000-28000).  See ray.sub for the full port layout.
+    # (1400-1999).  See ray.sub for the full port layout.
     master_port_range_low: NotRequired[int]
     master_port_range_high: NotRequired[int]
     segment_size: NotRequired[
@@ -77,27 +77,27 @@ class PY_EXECUTABLES:
     SGLANG = f"uv run --locked --extra sglang --directory {git_root}"
 
 
-# Default port ranges — kept below the OS ephemeral range (32768-60999 on
-# stock Linux) to avoid TOCTOU collisions.  See ray.sub for the full layout
-# including Ray's own GCS / worker gRPC ports.
+# Default port ranges — kept below the OS ephemeral range.  On some DGX/GB200
+# nodes the ephemeral floor is as low as 9000 (32768 on stock Linux), so every
+# service port is pinned below 9000 to avoid TOCTOU collisions.  See ray.sub for
+# the full layout including Ray's own GCS / worker gRPC ports.
 #
-#   11001-15000  vLLM / SGLang HTTP servers  (policy.generation.port_range_low/high)
-#   15001-20000  NeMo Gym HTTP servers       (env.nemo_gym.port_range_low/high)
-#   20001+       vLLM TP/DP rendezvous       (VLLM_PORT env var, 100-port spacing)
-#   25000-28000  Master address / TCPStore    (cluster.master_port_range_low/high)
-DEFAULT_GENERATION_PORT_RANGE_LOW = 11001
-DEFAULT_GENERATION_PORT_RANGE_HIGH = 15000
-DEFAULT_GYM_PORT_RANGE_LOW = 15001
-DEFAULT_GYM_PORT_RANGE_HIGH = 20000
-# vLLM TP/DP rendezvous ports.  Each engine gets PORTS_PER_ENGINE ports
-# starting at LOW + engine_index * PORTS_PER_ENGINE.  The effective upper
-# bound is LOW + max_engines_per_node * PORTS_PER_ENGINE.  With 8 GPUs and
-# TP=1 (8 engines): 20001 + 8*100 = 20801.  There is no fixed ceiling —
-# ensure the range does not overlap with MASTER (25000+) on very large nodes.
-DEFAULT_VLLM_PORT_RANGE_LOW = 20001
+#   1400-1999    Master address / TCPStore       (cluster.master_port_range_low/high)
+#   3000-4999    NeMo RL generation HTTP servers (policy.generation.port_range_low/high)
+#   5000-5999    NeMo Gym HTTP servers           (env.nemo_gym.port_range_low/high)
+#   7000-8999    vLLM / SGLang engine rendezvous (VLLM_PORT env var / SGLang base_port)
+DEFAULT_GENERATION_PORT_RANGE_LOW = 3000
+DEFAULT_GENERATION_PORT_RANGE_HIGH = 4999
+DEFAULT_GYM_PORT_RANGE_LOW = 5000
+DEFAULT_GYM_PORT_RANGE_HIGH = 5999
+# vLLM TP/DP rendezvous ports.  Each engine gets PORTS_PER_ENGINE ports starting
+# at LOW + engine_index * PORTS_PER_ENGINE.  With 8 GPUs and TP=1 (8 engines):
+# 7000 + 8*100 = 7800, still below the 9000 ephemeral floor.
+DEFAULT_VLLM_PORT_RANGE_LOW = 7000
 DEFAULT_VLLM_PORTS_PER_ENGINE = 100
-DEFAULT_MASTER_PORT_RANGE_LOW = 25000
-DEFAULT_MASTER_PORT_RANGE_HIGH = 28000
+# Master address / TCPStore range, tucked below the Ray worker-gRPC band (2000+).
+DEFAULT_MASTER_PORT_RANGE_LOW = 1400
+DEFAULT_MASTER_PORT_RANGE_HIGH = 1999
 
 # ---------------------------------------------------------------------------
 # Topology resource keys

nemo_rl/environments/nemo_gym.py

@@ -67,7 +67,7 @@ class NemoGymConfig(TypedDict):
     base_urls: List[str]
     initial_global_config_dict: Dict[str, Any]
     # Port range for Gym HTTP servers (head server + subprocess servers).
-    # Defaults to DEFAULT_GYM_PORT_RANGE_LOW/HIGH (15001-20000) from
+    # Defaults to DEFAULT_GYM_PORT_RANGE_LOW/HIGH (5000-5999) from
     # nemo_rl.distributed.virtual_cluster.  See the port layout there.
     port_range_low: NotRequired[int]
     port_range_high: NotRequired[int]

nemo_rl/models/generation/sglang/sglang_generation.py

@@ -249,7 +249,9 @@ def _start_engines(
         if len(local_all_engines) == 0:
             return [], port_cursors
 
-        base_port = max(port_cursors.values()) if port_cursors else 15000
+        # SGLang engine ports live in the below-ephemeral-floor engine band
+        # (7000-8999), shared with vLLM; see virtual_cluster.py port layout.
+        base_port = max(port_cursors.values()) if port_cursors else 7000
         addr_and_ports, port_cursors = _allocate_rollout_engine_addr_and_ports_normal(
             gpus_per_node=self.num_gpus_per_node,
             sglang_cfg=self.sglang_cfg,

nemo_rl/models/generation/sglang/sglang_worker.py

@@ -162,7 +162,7 @@ def _make_request(self, endpoint: str, payload: dict | None = None):
         return response.json()
 
     @staticmethod
-    def _get_current_node_ip_and_free_port(start_port=10000, consecutive=1):
+    def _get_current_node_ip_and_free_port(start_port=7000, consecutive=1):
         return get_current_node_ip(), get_free_port(
             start_port=start_port, consecutive=consecutive
         )