feat: add support for per-sandbox idle timeout option

[mishamilovidov]

Description

• Add idle_timeout option to sandbox-creation payload
• Route Sandbox.get() through the optional management_endpoint so status checks reach the correct host on production clusters
• Update README.md to document sandbox lifetime model

Related Issue

• RUNNER-9437
• ACNA-4695

Motivation and Context

The sandbox-creation API now support clients setting a per-sandbox idle timeout alongside the max lifetime option. This change exposes that capability to clients in the SDK.

How Has This Been Tested?

• Add five new unit tests to cover the addition of the new option
• Use local version of SDK via test_idle_timeout_sdk.py.zip to test usage of the new option (expand details below to see output)

Local shell session running test script...

cd /Users/milovido/Projects/adobe/ghos/adobe/aio-lib-sandbox-python && uv run python /Users/milovido/Downloads/test_idle_timeout_sdk.py -e prd -a $AIO_RUNTIME_AUTH_TMP
Using CPython 3.11.11
Creating virtual environment at: .venv
Installed 9 packages in 15ms
[2026-06-10T16:45:30.844944+00:00] [setup] SDK idle-timeout smoke — prd
[2026-06-10T16:45:30.845160+00:00] [setup]   APIHOST = https://next-adobeioruntime.net
[2026-06-10T16:45:30.845165+00:00] [setup]   NS      = bladerunner-test
[2026-06-10T16:45:30.845168+00:00] [test_create_echo] Sandbox.create(idle_timeout=600) — expect instance.idle_timeout == 600...
[2026-06-10T16:45:37.565703+00:00] [test_create_echo]   instance.idle_timeout = 600 ✓
[2026-06-10T16:45:37.565846+00:00] [test_create_default] Sandbox.create() with no idle_timeout — expect instance.idle_timeout == 900 (SDK default)...
[2026-06-10T16:45:42.546545+00:00] [test_create_default] ERROR: Could not connect sandbox 'sb-d7ce6200c5275685': [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: Hostname mismatch, certificate is not valid for 'sb-d7ce6200c5275685-va6-1-ppgbxk1ky_e.sandbox-adobeioruntime.net'. (_ssl.c:1006)
[2026-06-10T16:45:42.546688+00:00] [test_get_echo] Sandbox.get(sb-bb7d0c8842eedbd6) — expect idle_timeout == 600 in get response...
[2026-06-10T16:45:42.999076+00:00] [test_get_echo]   get response idle_timeout = 600 ✓
[2026-06-10T16:45:42.999200+00:00] [test_idle_cap_rejection] Sandbox.create(idle_timeout=10801) — expect SandboxClientError (backend 400)...
[2026-06-10T16:45:43.392663+00:00] [test_idle_cap_rejection]   rejected with SandboxClientError ✓ — Could not create sandbox: 400 {"error":"idleTimeout must be 0 (use cluster default) or between 1 and 10800 seconds (3h); received 10801: idleTimeout out of range"}
[2026-06-10T16:45:43.392733+00:00] [test_max_create_echo] Sandbox.create(max_lifetime=7200) — expect instance.max_lifetime == 7200...
[2026-06-10T16:45:48.856304+00:00] [test_max_create_echo]   instance.max_lifetime = 7200 ✓
[2026-06-10T16:45:48.856400+00:00] [test_max_create_default] Checking max_lifetime on test_create_default sandbox — expect 3600 (SDK default)...
[2026-06-10T16:45:48.856433+00:00] [test_max_create_default] ERROR: Expected 3600 (SDK default sent to backend), got 7200
[2026-06-10T16:45:48.856469+00:00] [test_max_get_echo] Sandbox.get(sb-e9d0fcb2faff317c) — expect max_lifetime == 7200 in get response...
[2026-06-10T16:45:49.290535+00:00] [test_max_get_echo]   get response max_lifetime = 7200 ✓
[2026-06-10T16:45:49.290584+00:00] [test_max_cap_rejection] Sandbox.create(max_lifetime=10801) — expect SandboxClientError (backend 400)...
[2026-06-10T16:45:49.683952+00:00] [test_max_cap_rejection]   rejected with SandboxClientError ✓ — Could not create sandbox: 400 {"error":"maxLifetime must be 0 (use cluster default) or between 1 and 10800 seconds (3h); received 10801: maxLifetime out of range"}
[2026-06-10T16:45:49.684094+00:00] [test_idle_expiry] Creating sandbox with idle_timeout=30s, max_lifetime=300s...
[2026-06-10T16:45:57.238710+00:00] [test_idle_expiry]   sandboxId = sb-37128c67a88ae706. WS closed, going dark for 30s...
[2026-06-10T16:46:27.239887+00:00] [test_idle_expiry]   Polling for SandboxNotFoundError (up to 60s)...
[2026-06-10T16:46:27.656843+00:00] [test_idle_expiry]   sandbox expired after 30s idle ✓
[2026-06-10T16:46:27.656895+00:00] [test_activity_reset] Creating sandbox with idle_timeout=30s, max_lifetime=300s...
[2026-06-10T16:46:32.537698+00:00] [test_activity_reset] ERROR: Could not connect sandbox 'sb-532d45c6807bed99': [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: Hostname mismatch, certificate is not valid for 'sb-532d45c6807bed99-va6-1-_tkdu5dyrf8.sandbox-adobeioruntime.net'. (_ssl.c:1006)
[2026-06-10T16:46:32.537802+00:00] [test_max_expiry] Creating sandbox with max_lifetime=30s, idle_timeout=300s...
[2026-06-10T16:46:38.085125+00:00] [test_max_expiry] ERROR: Could not connect sandbox 'sb-7cf1a4d40fc6aa42': [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: Hostname mismatch, certificate is not valid for 'sb-7cf1a4d40fc6aa42-va6-1-3l_ibp-rvbc.sandbox-adobeioruntime.net'. (_ssl.c:1006)
[2026-06-10T16:46:38.085188+00:00] [cleanup] Destroying tracked sandboxes...

══════════════════════════════════
  SDK idle-timeout smoke: prd
══════════════════════════════════
  test_create_echo         ✓  PASS
  test_create_default      ✗  FAIL
  test_get_echo            ✓  PASS
  test_idle_cap_rejection  ✓  PASS
  test_max_create_echo     ✓  PASS
  test_max_create_default  ✗  FAIL
  test_max_get_echo        ✓  PASS
  test_max_cap_rejection   ✓  PASS
  test_idle_expiry         ✓  PASS
  test_activity_reset      ✗  FAIL
  test_max_expiry          ✗  FAIL
──────────────────────────────────
  Result: FAIL
══════════════════════════════════

Screenshots (if appropriate):

N/A

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• I have signed the Adobe Open Source CLA.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!