Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

docs(sdk-python): describe the wake retry on streaming requests

Maohaobf27f649cbbf
diff --git a/docs/sdks/python.md b/docs/sdks/python.md
index 942f6138e..87ecc6550 100644
--- a/docs/sdks/python.md
+++ b/docs/sdks/python.md
@@ -190,7 +190,7 @@ sandbox = await Sandbox.create(
### Wake retry
-A request to a paused sandbox may arrive while its restore is still in progress. The gateway answers `503` with the `OpenSandbox-Wake: expired` marker; the SDK recognizes it and resends the original request after the `Retry-After` delay (safe for any method — the marker proves the request was never forwarded). The wake budget defaults to 5 attempts / 60 seconds across all wake cycles; when it is exhausted the SDK raises `SandboxWakeTimeoutException` (carrying `attempts` and `waited`) while the server-side restore continues in the background. Bare `503` responses follow the existing retry rules untouched. Streaming (SSE) calls bypass wake retry.
+A request to a paused sandbox may arrive while its restore is still in progress. The gateway answers `503` with the `OpenSandbox-Wake: expired` marker; the SDK recognizes it and resends the original request after the `Retry-After` delay (safe for any method — the marker proves the request was never forwarded). The wake budget defaults to 5 attempts / 60 seconds across all wake cycles; when it is exhausted the SDK raises `SandboxWakeTimeoutException` (carrying `attempts` and `waited`) while the server-side restore continues in the background. Bare `503` responses follow the existing retry rules untouched. Streaming (SSE) calls such as `commands.run` and `codes.run` get the wake retry too, for the request that starts the stream; an established stream is never resent.
## Usage Examples
@@ -527,7 +527,7 @@ The `ConnectionConfig` class manages API server connection settings.
| `follow_redirects` | Follow HTTP redirects for SDK requests | `False` | - |
| `event_hooks` | Additional httpx hooks for adapter clients | Empty | - |
| `transport` | Shared httpx transport (pool/proxy/retry); custom transports must honor request timeouts | SDK-created per instance | - |
-| `retry_policy` | Automatic retry policy for non-streaming requests (see [Automatic retries](#_2-automatic-retries)) | Enabled (`RetryPolicy()`) | - |
+| `retry_policy` | Automatic retry policy; streaming requests only get its wake retry (see [Automatic retries](#_2-automatic-retries)) | Enabled (`RetryPolicy()`) | - |
| `use_server_proxy` | Use sandbox server as proxy for execd/endpoint requests (e.g. when client cannot reach the sandbox directly) | `False` | - |
| `disable_metrics` | Disable SDK create-latency telemetry (see [SDK Telemetry](/sdks/observability#creation-metrics)) | `False` | `OPENSANDBOX_DISABLE_METRICS` |
| `enable_tracing` | Enable OpenTelemetry tracing for pool warmup (see [SDK Tracing](/sdks/observability#pool-warmup-tracing)) | `False` | - |
@@ -584,7 +584,7 @@ Default behavior:
- **Enabled by default.** Idempotent methods (`GET/HEAD/PUT/DELETE/OPTIONS`) are retried on `429`, `502`, `503`, and on pre-send transport failures (DNS, TCP connect, TLS handshake, fresh-connection reset).
- **`POST`/`PATCH` are never retried on a status code by default**, since the request may already have been applied server-side. Pre-send transport failures (before any byte is written) are still retried for these methods.
- Up to `3` retries with decorrelated-jitter exponential backoff, honoring a server `Retry-After` header (capped at 60s).
-- **SSE / streaming requests bypass retry** entirely (bodies are not replayable).
+- **SSE / streaming requests are not retried** on status codes or transport errors, since they may already have started a command. Only the [wake retry](#wake-retry) applies to the request that starts the stream.
::: warning Behavior change
Retries are on by default. This can increase the number of HTTP attempts and tail latency compared to earlier SDK versions. If you rely on fast-fail semantics, opt out explicitly with `RetryPolicy.disabled()`.
diff --git a/sdks/sandbox/python/src/opensandbox/config/connection.py b/sdks/sandbox/python/src/opensandbox/config/connection.py
index 7600c6367..ec2a9ed95 100644
--- a/sdks/sandbox/python/src/opensandbox/config/connection.py
+++ b/sdks/sandbox/python/src/opensandbox/config/connection.py
@@ -101,8 +101,9 @@ class ConnectionConfig(BaseModel):
retry_policy: RetryPolicy = Field(
default_factory=RetryPolicy,
description=(
- "Retry policy applied to non-streaming requests going through "
- "the shared transport. Pass RetryPolicy.disabled() for fast-fail."
+ "Retry policy applied to requests going through the shared "
+ "transport. Streaming (SSE) requests only get its wake-timeout "
+ "retry. Pass RetryPolicy.disabled() for fast-fail."
),
)
use_server_proxy: bool = Field(
diff --git a/sdks/sandbox/python/src/opensandbox/config/connection_sync.py b/sdks/sandbox/python/src/opensandbox/config/connection_sync.py
index fcd1d785a..ea775e2b3 100644
--- a/sdks/sandbox/python/src/opensandbox/config/connection_sync.py
+++ b/sdks/sandbox/python/src/opensandbox/config/connection_sync.py
@@ -92,8 +92,9 @@ class ConnectionConfigSync(BaseModel):
retry_policy: RetryPolicy = Field(
default_factory=RetryPolicy,
description=(
- "Retry policy applied to non-streaming requests going through "
- "the shared transport. Pass RetryPolicy.disabled() for fast-fail."
+ "Retry policy applied to requests going through the shared "
+ "transport. Streaming (SSE) requests only get its wake-timeout "
+ "retry. Pass RetryPolicy.disabled() for fast-fail."
),
)
use_server_proxy: bool = Field(