feat(cua-sandbox): configure Fleet computer-server port

[r33drichards]

What changed

• add server_port: int = 8000 to async Sandbox.create() and Sandbox.ephemeral()
• validate integer ports from 1 through 65535, rejecting booleans
• use the selected port for the Fleet server Service, readiness probe, exposed-port deduplication, and forward_tunnel() routing
• preserve the server mapping when custom Fleet services are supplied
• leave local, legacy cloud, and existing-pool behavior unchanged
• document that custom images must run the CUA computer-server /cmd API on the selected port

Follow-up to merged #2979.

Verification

Candidate: 6c4d587c2659b52b62e2f2135f60ff86dfda09b0

cd libs/python/cua-sandbox
.venv/bin/python -m ruff check cua_sandbox tests
.venv/bin/python -m ruff format --check \
  cua_sandbox/transport/fleet_cloud.py \
  cua_sandbox/sandbox.py \
  tests/test_fleet_cloud_transport.py \
  tests/test_vm_cleanup.py
.venv/bin/python -m pytest -q \
  tests/test_fleet_cloud_transport.py \
  tests/test_vm_cleanup.py \
  -k 'server_port or custom_services'
git diff origin/main...HEAD --check

Results:

• Ruff check: passed
• changed-file Ruff format check: passed
• focused contract tests: 38 passed, 32 deselected
• diff check: passed
• full suite: 205 passed, 83 skipped, 28 failed, 19 errors, 2 warnings; origin/main has the same failure/error/warning counts, so no new broad-suite regression was observed

Live Fleet E2E

A temporary unrestricted user key (scope=[]) ran the public cua-sandbox SDK against https://run.cua.ai using:

• image: 296062593712.dkr.ecr.us-west-2.amazonaws.com/desktop-workspace-duo@sha256:5b9cb82f482834f7541901b87be956e7544d0db13fabc0b372cbc5eca5a74180
• namespace: pr-server-port-duo-e2e-20260809t211821z
• cpu=4, memory_mb=4096, server_port=8000
• time_to_start=900, request_timeout=60, telemetry_enabled=False

Observed results:

1. Fleet template and pool became available, followed by the sandbox, VMI, and pod.
2. The generated server Service targeted port 8000.
3. The generated readiness probe used tcpSocket.port = 8000.
4. sandbox.screen.size() returned 1024x768.
5. sandbox.shell.run("uname -s") succeeded and returned Linux.
6. Exiting the SDK context removed the owned namespace and all template, pool, claim, sandbox, VMI, and pod resources.
7. The temporary user key was revoked and confirmed absent; the isolated device-auth session was logged out and its credential files removed.

Lifecycle timestamps (UTC):

• template and pool: 2026-08-09T21:19:05Z
• sandbox, VMI, and pod: 2026-08-09T21:19:35Z
• claim: 2026-08-09T21:21:36Z

The live compatibility E2E therefore passes with an explicit server_port=8000. Non-default server_port=5000 propagation is covered by the focused SDK tests and generated-template assertions. The originally evaluated pinned desktop-workspace image was not suitable for a positive 5000 live check because it exposed cua-driver MCP on 3000 and did not run the computer-server /cmd API on 5000.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!