diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index ad2c2ca..dc5544f 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -188,6 +188,8 @@ icon: "rocket"
               token: process.env.SANDBOX_TOKEN,
             });
             ```
+
+            `SandboxAgent.connect(...)` waits for `/v1/health` by default. Pass `waitForHealth: false` to disable that behavior, or `waitForHealth: { timeoutMs: 120_000 }` to cap the wait.
           </Tab>
 
           <Tab title="curl">
diff --git a/docs/sdk-overview.mdx b/docs/sdk-overview.mdx
index 7974c65..e150c4d 100644
--- a/docs/sdk-overview.mdx
+++ b/docs/sdk-overview.mdx
@@ -39,6 +39,8 @@ const sdk = await SandboxAgent.connect({
 });
 ```
 
+`SandboxAgent.connect(...)` now waits for `/v1/health` by default before other SDK requests proceed. To disable that gate, pass `waitForHealth: false`. To keep the default gate but fail after a bounded wait, pass `waitForHealth: { timeoutMs: 120_000 }`.
+
 With a custom fetch handler (for example, proxying requests inside Workers):
 
 ```ts
@@ -170,6 +172,7 @@ Parameters:
 - `token` (optional): Bearer token for authenticated servers
 - `headers` (optional): Additional request headers
 - `fetch` (optional): Custom fetch implementation used by SDK HTTP and ACP calls
+- `waitForHealth` (optional, defaults to enabled): waits for `/v1/health` before HTTP helpers and ACP session setup proceed; pass `false` to disable or `{ timeoutMs }` to bound the wait
 
 ## Types