[DamianB-BitFlipper]

What

Adds CLI and SDK support for sandbox localhost forwards (platform: PrimeIntellect-ai/platform#7138). A forward makes a VM sandbox's own 127.0.0.1:PORT / [::1]:PORT reach the same port on a LAN peer. Docker Compose services that share one network namespace (network_mode: "service:X", localhost URLs) can then run as separate sandboxes.

The forwards live in sandboxd, inside the sandbox. The SDK calls GET/POST {gateway}/{user_ns}/{job_id}/network/local-forwards through sandbox-gateway, the same way read_file and upload_file already work. There's no control-plane endpoint, and changes apply before the call returns.

CLI

prime sandbox network localhost APP_ID 5432:DB_ID   # inside APP_ID, localhost:5432 reaches DB_ID's port 5432
prime sandbox network localhost APP_ID              # show
prime sandbox network localhost APP_ID --clear      # remove all

Each call replaces the whole set; pass several PORT:PEER arguments to forward several ports. Both sandboxes must share a LAN network whose rules allow the port; otherwise connections are reset. -o json is supported.

SDK (SandboxClient and AsyncSandboxClient)

• get_localhost_forwards(sandbox_id) -> List[LocalhostForward]
• set_localhost_forwards(sandbox_id, forwards) -> List[LocalhostForward]

Errors:

• 400 (invalid set) and 409 (a port is already bound in the sandbox) raise APIError with sandboxd's message.
• 404 means the sandbox predates the feature, so the user is told to recreate it.
• 401 re-authenticates once and retries.

Merge order

Merge after platform#7138's sandboxd is deployed. Until then, sandboxes answer 404.

Tests

• prime-sandboxes tests/test_egress_policy.py passes (51). The tests mock the gateway: they check the sync POST payload, 409 and 404 errors, async GET, and the port range.
• The full prime-sandboxes suite passes (409, 33 skipped).
• prime tests/test_sandbox_network_lan.py tests/test_sandbox_cli.py passes (64).
• ruff and ty are clean.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes sandbox networking behavior via in-VM forwards and gateway calls; misconfiguration could break app connectivity, but scope is additive with explicit replace semantics and depends on deployed sandboxd.

Overview
Adds localhost forwards so a VM sandbox can treat its own loopback ports as tunnels to the same port on a LAN peer (PEER.sandbox.internal), enabling multi-sandbox setups that behave like shared-network Compose stacks.

The SDK introduces LocalhostForward plus get_localhost_forwards / set_localhost_forwards on sync and async clients. Updates go through sandbox-gateway to sandboxd (GET/POST …/network/local-forwards), with full replace semantics, 401 retry, and clear errors when the sandbox is too old (404) or the request fails.

The CLI adds prime sandbox network localhost to show, replace (PORT:PEER, repeatable), or --clear forwards, with table/json output and validation (malformed specs, duplicate ports). Docs in examples/README.md document the workflow and LAN rule requirement.

Tests cover gateway wiring, error mapping, model validation, and CLI parsing/invocation.

^{Reviewed by Cursor Bugbot for commit 65bd3fc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-28T22:48:10.782492Z	58c900f	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.