[JeffPengCoder]

What does this PR do?

This splits the sandbox-provider changes out of #3591, as suggested in its review, so they can land first.

Main already uses fields that only these changes define. #3592 added them to the OSWorld configs, but the provider configs reject them, so neither provider can be built from those configs today:

Config on main	Field	Error on main (968e069c5)
responses_api_agents/osworld_agent/configs/osworld_agent.yaml (Docker)	create.transport_retries, create.transport_retry_delay_s	TypeError: DockerCreateConfig.__init__() got an unexpected keyword argument 'transport_retries'
benchmarks/osworld/configs/osworld_agentenv.yaml (E2B)	connection.port_routing	ValueError: Unknown E2BConnectionConfig keys: port_routing

Changes:

• Docker. A remote Docker transport can lose the docker run response after the daemon has created the container. create.transport_retries (default 2) and create.transport_retry_delay_s retry with the same fixed name. After a timeout, a transport error or a same-name conflict, the provider inspects that exact name and reuses the container only when both the sandbox ownership label and the requested image match. An unrelated container is never removed.
• E2B endpoints. endpoint() resolves a declared service port. connection.port_routing selects hostname routing (one DNS name per port) or gateway routing (one origin, with the SDK's per-sandbox headers plus E2b-Sandbox-Port); auto selects gateway when a sandbox URL is configured. Gateway routing needs ConnectionConfig.sandbox_headers, so the SDK range becomes e2b>=2.46.0,<3.0.0 in the dependency, the installation hint, the README and the example. A test checks that they agree.
• E2B transport. The provider borrows Gym's aiohttp pool only when the process already has Gym's global config. Otherwise it keeps the SDK's own transport, so a Ray worker never reaches Hydra's argument parser before creating a sandbox.
• OpenSandbox. endpoint() reports an actionable error for SDKs without Sandbox.get_endpoint and tolerates responses without endpoint headers.

These changes come from #3591's head (6055f9ea3). #3591 merged without them (8af4df7ef), so main still lacks them. On main 92407083b the two configs above still set fields that the providers do not define, and the E2B provider still has no endpoint(). There is no separate issue: this is a split of #3591.

Waiting on this PR: #4897 (Nano Omni recipe docs) should merge after it. The draft #4896 carries a copy of the same files.

Validation

October 22: rebased on main 92407083b.

• The only conflict was in nemo_gym/sandbox/providers/docker/provider.py. feat(harbor): Dockerfile builds, the third image mode (RFC M20) #4566 added _user_flag at the place where this PR adds _is_create_transport_failure and _is_name_conflict; both are kept.
• Otherwise this PR's diff is unchanged: git range-diff shows only that context line.

These checks used macOS ARM64, Python 3.13.14, and the dev and sandbox dependencies from the lockfile (E2B SDK 2.46.0):

• The 15 test files that exercise the sandbox providers: 741 passed, 6 skipped, 8 failed. The files are:
  • tests/unit_tests/telemetry/test_sandbox_create_retry.py;
  • test_docker_provider.py and test_tb4_harbor_sandbox_overlay.py;
  • test_e2b_build.py, test_e2b_endpoint.py, test_e2b_provider.py and test_e2b_sdk_transport_fallback.py;
  • test_opensandbox_cleanup.py, test_opensandbox_compose.py, test_opensandbox_http_transport.py, test_opensandbox_provider.py, test_opensandbox_pty.py and test_opensandbox_snapshots.py;
  • test_sandbox_stop_retry.py and test_sandbox.py.
• The same 8 tests also fail on unmodified main and are specific to this macOS machine:
  • test_script_help_runs_by_direct_path in test_opensandbox_cleanup.py;
  • test_script_help_runs_by_direct_path in test_opensandbox_snapshots.py;
  • the six test_slurm_eval_preserves_output_paths_and_explicit_resume cases.
• pre-commit run on the changed files and uv lock --check: passed.

Original head 726a4746e on main 968e069c5. On macOS ARM64 with Python 3.13.14 and the dev and sandbox dependencies (aiohttp 3.14.4, FastAPI 0.135.2, real E2B SDK 2.46.0):

• Provider tests (tests/unit_tests/test_docker_provider.py, test_e2b_endpoint.py, test_e2b_provider.py, test_e2b_sdk_transport_fallback.py, test_opensandbox_provider.py): 327 passed.
• The core unit suite plus the vLLM, simple-agent, compaction-agent and OSWorld tests, run on this branch and on its base, main 968e069c5: 10,913 passed here against 10,884 on main; the 31 new tests all pass. The remaining 27 failures are identical on main and are specific to this macOS machine. Two timing-sensitive tests, the test_checkpoint_agent restart seed and the test_cli_eval_submit invalid config, each failed once under the 8-worker run and passed when rerun alone (8/8 and 3/3). Neither imports the provider code.
• Both OSWorld configs above now build their provider configs, checked with the providers' own parsers after OmegaConf resolution. They fail on main as shown.
• pre-commit run on the changed files and uv lock --check --offline: passed.

Rollouts

The E2B changes ran end to end in the October 20 OSWorld score reproduction on #3591, whose head contains these exact files. That run covered 361 tasks, with Nemotron-3-Nano-Omni served by vLLM and desktops behind an AgentEnv gateway using port_routing: auto. It scored 48.13% raw and 166/361 binary, with no degradation; details are in #3591. The Docker reconciliation and the OpenSandbox change are covered by unit tests only.

Compatibility and benchmark impact

• With the default transport_retries: 2, an ambiguous Docker create (timeout, transport error or same-name conflict) is reconciled and retried up to twice instead of failing at once. Other docker run failures still fail immediately.
• The sandbox extra raises the E2B SDK lower bound from 2.36.0 to 2.46.0.
• New config fields have defaults. Benchmark impact: none expected; the reproduction above showed no degradation.

Checklist

• I have read the contributing guidelines.
• The change is focused; unrelated "drive-by" edits are tracked as separate issues/PRs.
• Tests added or updated and pass locally, or N/A for docs-only / non-code changes (so CI unit/server checks pass when applicable).
• Documentation added or updated, or N/A with justification. (E2B provider README.)
• Pre-commit checks pass locally (pre-commit run --all-files) (so CI lint/format checks pass).
• New source files include the required Apache-2.0 SPDX header.
• All commits have DCO sign-off (git commit -s) (so the DCO check passes).

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[marcromeyn]

/ok to test bb7d9d3

[yaoyu-33]

LGTM. Reviewed the Docker creation reconciliation and E2B endpoint wiring; no new blocking issues found.

[yaoyu-33]

/ok to test 5c6e5d1

[github-actions]

🔄 Merge queue validation started! You can track the progress here: https://github.com/NVIDIA-NeMo/Gym/actions/runs/40415660184