withruntime 0.9.0 → 0.10.0

package/BLAXEL.md

@@ -10,8 +10,8 @@ load it.
 import { SandboxInstance } from "withruntime/blaxel"; // was: from "@blaxel/core"
 ```
 
-The mapping was written against `@blaxel/core` 0.3.23 and Blaxel's sandbox API
-source, checked 27 September 2026. Every name `@blaxel/core` exports can be
+The mapping was written against `@blaxel/core` 0.3.24 and Blaxel's sandbox API
+source, checked 30 September 2026. Every name `@blaxel/core` exports can be
 imported: code that only mentions an agent, model or MCP helper still loads.
 
 ## Keys
@@ -100,7 +100,7 @@ name, or through `getByExternalId`, use the same Runtime key.
 | `process.exec` without `waitForCompletion`                                            | One Runtime process, answered running. Its Blaxel name is kept in its command line, so `get("name")` finds it from any client.                                                                                                                                                                                                                                                                   |
 | `process.exec({ waitForCompletion: true })`                                           | One streamed call, answered with `status`, `exitCode`, `stdout`, `stderr` and `logs`. Past `timeout` the wait ends with a 422 and the process runs on.                                                                                                                                                                                                                                           |
 | `onLog`, `onStdout`, `onStderr`, `streamLogs`                                         | The process's output as it comes; `streamLogs` gives whole lines, as Blaxel's does.                                                                                                                                                                                                                                                                                                              |
-| `process.get`, `wait`, `list`, `logs`, `stop`, `kill`, `writeStdin`, `closeStdin`     | Runtime processes by id or name. `wait` follows the output instead of polling. `stop` is SIGTERM, `kill` SIGKILL.                                                                                                                                                                                                                                                                                |
+| `process.get`, `wait`, `list`, `logs`, `stop`, `kill`, `writeStdin`, `closeStdin`     | Runtime processes by id or name. `wait` follows output with one deadline covering lookup and output. Cancellation leaves the process running. `stop` is SIGTERM, `kill` SIGKILL.                                                                                                                                                                                                                 |
 | `keepAlive`, `timeout`                                                                | The sandbox does not pause for idleness while the process may run (its `timeout`, 600 s by default, 0 for as long as a lease allows); once no `keepAlive` process runs, it gets its idle pause back.                                                                                                                                                                                             |
 | `restartOnFailure`, `maxRestarts`, `waitForPorts`, `workingDir`, `env`, `stdin`       | A restart loop in the same process, with Blaxel's note in the output (`restartCount` counts the notes); a wait in the sandbox for the ports; as in Blaxel.                                                                                                                                                                                                                                       |
 | `fs.read`, `write`, `readBinary`, `writeBinary`, `writeTree`, `mkdir`, `rm`, `cp`     | Runtime's files API, or one command. A path only root may read or write (outside `/workspace`, or made by a root process) goes through sudo, as Blaxel's root-owned API could.                                                                                                                                                                                                                   |
@@ -208,7 +208,7 @@ leaves those names alone.
 
 `bun run test` in `packages/cloud-sdk` runs the unit tests against a fake of
 Runtime's SDK: `tests/blaxel`, including a check that every name
-`@blaxel/core` 0.3.23 exports is exported here.
+`@blaxel/core` 0.3.24 exports is exported here.
 
 The end-to-end test runs Blaxel's guides, unmodified but for the import,
 against the real API: `tests/fixtures/blaxel-quickstart.mjs` (create, processes,

package/DAYTONA.md

@@ -1,7 +1,7 @@
 # Code written for Daytona, on Runtime
 
-Run code written for [Daytona](https://www.daytona.io)'s SDK on Runtime Cloud
-by changing one import. It is part of Runtime's SDK (`withruntime`), built on
+Supported sandbox calls from [Daytona](https://www.daytona.io)'s SDK keep
+their call shapes on Runtime Cloud after changing the import. It is part of Runtime's SDK (`withruntime`), built on
 the same client, so it gets that SDK's retries, idempotency keys and errors.
 Importing `withruntime` alone does not load it.
 
@@ -16,8 +16,9 @@ from withruntime.daytona import Daytona  # was: from daytona import Daytona
 from withruntime.daytona import AsyncDaytona  # was: from daytona import AsyncDaytona
 ```
 
-The mapping was written against `@daytona/sdk` 0.216.1 and `daytona` 0.216.1
-on PyPI, checked 23 September 2026.
+The mapping was written against `@daytona/sdk` 0.220.0 and `daytona` 0.220.0
+on PyPI, checked 29 September 2026. The exact releases and artifact hashes
+are kept in `compatibility-lock.json`.
 
 ## Keys
 
@@ -60,6 +61,7 @@ package talks only to Runtime.
 | `create({ image: "python:3.12" })`                                            | Built once as a Runtime image from the registry reference (named after it), then reused. `onSnapshotCreateLogs` receives the build log.                                                                       |
 | `create({ image: Image.debianSlim(...).pipInstall(...)... })`                 | The Dockerfile Daytona's `Image` stands for, with its local files, built as a Runtime image named after its content and reused.                                                                               |
 | `resources`, `envVars`, `labels`, `name`, `volumes`                           | `vcpu`, `memoryMiB`, `diskMiB`; environment given to every command; labels; name; Runtime volumes by id or by name.                                                                                           |
+| `setLabels` (Python `set_labels`)                                             | Replaces customer labels while preserving the language and Runtime compatibility labels; reconnects retain the language.                                                                                      |
 | `networkBlockAll`, `networkAllowList`, `domainAllowList`, `outboundProxyUrl`  | Runtime network rules (`internet: false`, or an `allow` list); the proxy as `HTTP_PROXY` and `HTTPS_PROXY` for commands.                                                                                      |
 | `public: true`                                                                | `getPreviewLink(port)` shares the port publicly; without it, privately with a token.                                                                                                                          |
 | `language`                                                                    | The language of `codeRun`, kept in Daytona's `code-toolbox-language` label so a sandbox found later keeps it.                                                                                                 |
@@ -93,7 +95,7 @@ Each of these throws `NotSupportedError` before anything happens. Its
 | `user` other than `daytona`                                           | Commands run as the sandbox owner with passwordless `sudo`.                                                                                                                             |
 | PTY sessions, the entrypoint session, language servers                | `sandbox.withruntime.terminal(...)`, and sessions with `runAsync`.                                                                                                                      |
 | `computerUse`                                                         | Runtime's desktop, `sandbox.withruntime.desktop`.                                                                                                                                       |
-| `setLabels`, `resize`, `recover`                                      | Set labels and resources at create; create a new sandbox.                                                                                                                               |
+| `resize`, `recover`                                                   | Set labels and resources at create; create a new sandbox.                                                                                                                               |
 | Signed preview URLs, signed upload and download URLs, SSH access      | `getPreviewLink`, `fs.uploadFile` and `downloadFile`, `npx withruntime sandbox ssh <id>`.                                                                                               |
 | `getMetrics`                                                          | `sandbox.withruntime.metrics()`: its CPU and memory over time.                                                                                                                          |
 | `Image.pipInstallFromPyproject`, snapshot `resources` or `entrypoint` | `pipInstallFromRequirements`; resources at create; a session after create.                                                                                                              |
@@ -102,10 +104,14 @@ Each of these throws `NotSupportedError` before anything happens. Its
 | `runCode(code, { envs })`                                             | `envVars` at create, or `os.environ` in the code.                                                                                                                                       |
 | Listing by anything but name, labels and states                       | Filter the result yourself.                                                                                                                                                             |
 
+File download timeouts are seconds, including buffer and local-path overloads
+and batches. A batch shares one deadline and stops starting later files once
+it expires. JavaScript `downloadFileStream(path, { timeout, signal })` also
+bounds and cancels the stream. An incomplete local download is never published
+as the completed file.
+
 Some differences are not refusals:
 
-- Sandbox `envVars` live in the object that created the sandbox;
-  `daytona.get(id)` from another process does not know them.
 - A session runs one command at a time. A command sent while another runs
   waits for it, as it would typed into a shell. Sessions made by another
   client are found by name, but only their output from then on is known.

package/E2B.md

@@ -1,7 +1,7 @@
 # Code written for E2B, on Runtime
 
-Run code written for [E2B](https://e2b.dev)'s SDK on Runtime Cloud by changing
-one import. It is part of Runtime's SDK (`withruntime`), built on the same
+Supported sandbox calls from [E2B](https://e2b.dev)'s SDK keep their call
+shapes on Runtime Cloud after changing the import. It is part of Runtime's SDK (`withruntime`), built on the same
 client, so it gets that SDK's retries, idempotency keys and errors. Importing
 `withruntime` alone does not load it.
 
@@ -64,6 +64,7 @@ machine. An E2B key (`e2b_...`) is never sent anywhere. If one is passed as
 | Command past its timeout                                                                 | Disconnects with `TimeoutError` (Python: `TimeoutException`) without killing the command; reconnect by pid to keep reading.                                                                                                                                 |
 | `commands.run(cmd, { background: true })`                                                | `spawn`. Returns a `CommandHandle` with `pid`, `wait()`, `kill()` (SIGKILL), `sendStdin`, `closeStdin`, `disconnect`, `stdout`, `stderr`, `exitCode`.                                                                                                       |
 | `commands.list`, `kill(pid)`, `sendStdin(pid)`, `closeStdin(pid)`, `connect(pid)`        | Runtime's processes. A pid is a number derived from Runtime's process id, not the Linux pid.                                                                                                                                                                |
+| `pty.create`, `connect`, `sendInput`, `resize`, `kill` (Python snake_case)               | Native PTY processes with lossless byte callbacks. A reader timeout or disconnect detaches without killing the process; reconnect resumes reading.                                                                                                          |
 | `files.read(path, { format })`                                                           | `files.read`. `text`, `bytes`, `blob` and `stream` (Python: `text`, `bytes`, `stream`).                                                                                                                                                                     |
 | `files.write(path, data)`, `write([...])`, `writeFiles`                                  | `files.write`. Parent directories are made, and a file that exists is replaced.                                                                                                                                                                             |
 | `files.list(path, { depth })`                                                            | `files.list`, hidden files included. `owner` and `group` come from native metadata, with `""` for older guests that omit them.                                                                                                                              |
@@ -76,12 +77,12 @@ machine. An E2B key (`e2b_...`) is never sent anywhere. If one is passed as
 | `sandbox.pause()`, `betaPause`, `Sandbox.pause(id)`                                      | `pause`, keeping memory and files. `false` when it was already paused.                                                                                                                                                                                      |
 | `getInfo`, `isRunning`                                                                   | `get`. `templateId` is `base` or the image or snapshot id. `envdVersion` is `runtime`.                                                                                                                                                                      |
 | `Sandbox.list({ query: { metadata, state }, limit })`                                    | `sandboxes.list` by labels and state, oldest first, with E2B's paginator (`hasNext`, `nextItems()`).                                                                                                                                                        |
-| `fork`, `createSnapshot`, `deleteSnapshot`                                               | Runtime's forks and snapshots. While Runtime has them switched off, they throw `NotSupportedError` with Runtime's own message.                                                                                                                              |
+| `fork`, `createSnapshot`, `deleteSnapshot`                                               | Runtime's memory-preserving forks and snapshots; deleting a snapshot removes that saved capture.                                                                                                                                                            |
 | `getHost(port)`                                                                          | `<port>-<id>.runtimehost.com` at once, as E2B answers it, and the port is shared as a public Runtime preview beside the caller (the sync Python sandbox shares it before returning). `await sandbox.getPublicHost(port)` returns once the share has landed. |
 | `runCode(code, { language, context, onStdout, onStderr, onResult, onError, timeoutMs })` | Runtime's interpreter: Python, JavaScript, TypeScript, R, Java and Bash, plus Go. The sandbox's `envs` reach code through a context made once for them. `onResult` streams each result and waits for asynchronous callbacks.                                |
 | `Execution`, `Result`, `Logs`, `ExecutionError`, `OutputMessage`                         | The same shapes. Results that are too large to send inline are fetched and inlined. `logs.stdout` has one entry per line.                                                                                                                                   |
 | `createCodeContext`, `listCodeContexts`, `restartCodeContext`, `removeCodeContext`       | Runtime's interpreter contexts.                                                                                                                                                                                                                             |
-| `getMetrics({ start, end })`, `Sandbox.getMetrics(id)`                                   | Runtime's measured CPU and memory, one entry per host reading (every minute by default). `diskUsed` is null: Runtime does not read disk use inside the sandbox.                                                                                             |
+| `getMetrics({ start, end })`, `Sandbox.getMetrics(id)`                                   | Runtime's measured CPU and memory, one entry per host reading. `diskUsed` is null: Runtime does not read disk use inside the sandbox.                                                                                                                       |
 | Error classes                                                                            | E2B's names and parents. Each also carries Runtime's `code`, `hint` and `requestId`, with the original error as `cause`.                                                                                                                                    |
 
 ## Gaps
@@ -104,7 +105,6 @@ before anything happens. The error's `feature` names the gap and its
 | `mcp`, `getMcpUrl`, `getMcpToken`                                                            | Runtime's own MCP server, `npx withruntime mcp`.                                                                    |
 | `iam`, `Secret`                                                                              | A Runtime secret (`npx withruntime secrets set NAME --host <host>`): the sandbox sees a placeholder.                |
 | `volumeMounts`, `Volume`                                                                     | Runtime volumes: `runtime: { create: { volumes: [{ volumeId, path }] } }`.                                          |
-| `pty`                                                                                        | `sandbox.runtime.terminal(...)`.                                                                                    |
 | `git`                                                                                        | `commands.run("git ...")`. E2B has deprecated its git module too.                                                   |
 | File `metadata`                                                                              | Keep it in a file beside the data.                                                                                  |
 | `uploadUrl`, `downloadUrl`                                                                   | `files.write` and `files.read`.                                                                                     |
@@ -120,15 +120,19 @@ a callback. Stream failures and lost events are reported, never treated as a
 successful empty watch. A positive watch timeout bounds the client subscription and stops its owned watch;
 zero leaves the subscription unlimited. The sandbox lease still applies. Both languages refuse watching network mounts.
 
+PTY `timeoutMs` (Python `timeout`, seconds) defaults to sixty seconds, including
+the opening handshake; zero leaves the reader unlimited. Callbacks receive raw
+bytes while the handle's `stdout` and `stderr` stay empty. PTYs made before
+lossless output support cannot reconnect through this adapter; create a new one.
+The sandbox lease still applies.
+
 Some differences are not refusals, so code that depends on them should check:
 
-- Sandbox-level `envs` live in the object that created the sandbox.
-  `Sandbox.connect(id)` from another process does not know them.
 - Runtime's stock image is Ubuntu 24.04 with Python 3.12, Node.js 24 and Bun.
   The current stock image includes NumPy, pandas and matplotlib; build an image
   for additional dependencies. Results never carry `chart`. A DataFrame arrives in
   `extra` under `application/vnd.runtime.table+json`, not in E2B's `data`.
-- JavaScript file operations and command creation honor `requestTimeoutMs`.
+- JavaScript file operations, command creation and reads, stdin/EOF, lookup, kill and reconnect honor `requestTimeoutMs` and `signal`.
   Python file `request_timeout` bounds the request, including streamed reads. `retries`, `logger`, `secure` and `validateApiKey` are
   accepted without changing the native transport settings.
 - Interpreter deadlines follow the pinned packages: JavaScript defaults to

package/README.md

@@ -12,7 +12,7 @@ The client uses `RUNTIME_API_KEY` when it is set, and otherwise the connection
 this machine saved when the CLI connected it (one browser approval, no key to
 copy). On a server or a CI runner, set `RUNTIME_API_KEY` from your secret
 manager: `npx withruntime keys create` prints a new key once after an account
-owner approves it in the browser, or create one at
+owner, admin or developer approves it in the browser, or create one at
 https://withruntime.com/account/keys. Never put a key in browser code, a URL or
 a command-line argument.
 
@@ -20,7 +20,8 @@ a command-line argument.
 import { Sandbox } from "withruntime";
 
 await using sbx = await Sandbox.create();
-const result = await sbx.exec("python3 -c 'print(6 * 7)'");
+await sbx.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
+const result = await sbx.exec("python3 /workspace/invoice.py");
 console.log(result.exitCode, result.stdout);
 ```
 
@@ -30,6 +31,8 @@ Node 22 call `await sbx.stop()`). With no arguments you get the free
 trial while it lasts (100 free hours, up to eight sandboxes running at once), 2 vCPU, 4 GiB of
 memory and a 4 GiB disk. The current default image includes NumPy, pandas and
 matplotlib; see the [sandbox environment](https://withruntime.com/docs/sandbox-environment).
+Omitting `funding` can use prepaid credit after the trial is exhausted. Use
+`Sandbox.create({ funding: "trial" })` for free use only; it never falls back to paid.
 
 The sandbox object does the rest:
 
@@ -57,7 +60,9 @@ no compute; `idlePauseSeconds` sets 10 to 86,400, or 0 for never.
 `Sandbox.getOrCreate(name)` returns the sandbox with that name, woken if it is
 paused, or creates it.
 
-The client has `sandboxes`, `images`, `volumes`, `snapshots`, `jobs`, `secrets`,
+`runtime.sandbox`, `snapshot`, `image`, `volume`, `job`, `domain`, `port` and
+`address` name the products as the CLI does. Their existing plural names
+remain aliases of the same product clients. The client has `sandboxes`, `images`, `volumes`, `snapshots`, `jobs`, `secrets`,
 `limits`, `feedback` and `support`; `webhooks`, `events`, `otel` and `audit`
 to watch the account; `domains`, `ports`, `addresses`, `tunnel` and `network`
 to connect sandboxes to your own world (paid accounts); and `mcp`, `sso`,
@@ -65,6 +70,8 @@ to connect sandboxes to your own world (paid accounts); and `mcp`, `sso`,
 the key is read-only and what its agent may still spend today. Every write carries an idempotency key, made for you, so the SDK's
 own retries (timeouts, 429, 503) never do anything twice. Errors are typed and
 carry a `code`, a `hint` and a `requestId`.
+`runtime.usageRequests("7d")` reads the account's API call counts and error rates;
+counts are exact decimal strings, and an empty window has a null `errorPercent`.
 
 ## Behind a proxy
 
@@ -87,7 +94,7 @@ Runtime improves fast because agents tell us what they run into: reports go stra
 
 ## Code written for E2B
 
-`withruntime/e2b` runs code written for E2B's SDK on Runtime. Change the
+`withruntime/e2b` translates supported E2B sandbox calls to Runtime. Change the
 import and set `RUNTIME_API_KEY`. The
 [switch guide](https://withruntime.com/docs/migrate) covers the other providers
 and how to work out what you save:
@@ -121,7 +128,7 @@ package list every mapping and gap.
 
 ## Code written for Blaxel
 
-`withruntime/blaxel` runs code written for Blaxel's sandbox SDK. Change the
+`withruntime/blaxel` translates supported Blaxel sandbox calls. Change the
 import:
 
 ```ts no-run
@@ -132,7 +139,7 @@ Sandboxes get Blaxel's default of 4096 MB, with one vCPU for every 2048 MB.
 Standby becomes Runtime's pause: after 60 seconds without a call a sandbox
 pauses with its memory and processes, and the next call wakes it. Envs,
 processes by name, files, previews, snapshots, forks and the code interpreter
-work as they do on Blaxel, and so do sessions: `sandbox.sessions` makes a
+are supported by the adapter, along with sessions: `sandbox.sessions` makes a
 Runtime sandbox session and `SandboxInstance.fromSession` drives the sandbox
 with its token. A Blaxel key is never sent anywhere. Drives, codegen, schedules and Blaxel's agent, model and MCP hosting throw
 `NotSupportedError` before anything happens, naming what to use instead.
@@ -152,7 +159,8 @@ https://withruntime.com/docs/frameworks.
 ## CLI
 
 ```bash no-run
-npx withruntime sandbox run -- python3 -c 'print(6 * 7)'   # connects on first use
+printf '%s\n' 'print(sum([125, 250, 375]))' > invoice.py
+npx withruntime sandbox run -- python3 - < invoice.py   # connects on first use
 npx withruntime sandbox create
 npx withruntime help
 ```

package/README.src.md

@@ -14,7 +14,7 @@ The client uses `RUNTIME_API_KEY` when it is set, and otherwise the connection
 this machine saved when the CLI connected it (one browser approval, no key to
 copy). On a server or a CI runner, set `RUNTIME_API_KEY` from your secret
 manager: `npx withruntime keys create` prints a new key once after an account
-owner approves it in the browser, or create one at
+owner, admin or developer approves it in the browser, or create one at
 https://withruntime.com/account/keys. Never put a key in browser code, a URL or
 a command-line argument.
 
@@ -22,7 +22,8 @@ a command-line argument.
 import { Sandbox } from "withruntime";
 
 await using sbx = await Sandbox.create();
-const result = await sbx.exec("python3 -c 'print(6 * 7)'");
+await sbx.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
+const result = await sbx.exec("python3 /workspace/invoice.py");
 console.log(result.exitCode, result.stdout);
 ```
 
@@ -32,6 +33,8 @@ Node 22 call `await sbx.stop()`). With no arguments you get the free
 trial while it lasts ({{trial-hours}} free hours, up to {{trial-sandboxes}} sandboxes running at once), 2 vCPU, 4 GiB of
 memory and a 4 GiB disk. The current default image includes NumPy, pandas and
 matplotlib; see the [sandbox environment](https://withruntime.com/docs/sandbox-environment).
+Omitting `funding` can use prepaid credit after the trial is exhausted. Use
+`Sandbox.create({ funding: "trial" })` for free use only; it never falls back to paid.
 
 The sandbox object does the rest:
 
@@ -59,7 +62,9 @@ no compute; `idlePauseSeconds` sets {{idle-pause-min}} to {{idle-pause-max}}, or
 `Sandbox.getOrCreate(name)` returns the sandbox with that name, woken if it is
 paused, or creates it.
 
-The client has `sandboxes`, `images`, `volumes`, `snapshots`, `jobs`, `secrets`,
+`runtime.sandbox`, `snapshot`, `image`, `volume`, `job`, `domain`, `port` and
+`address` name the products as the CLI does. Their existing plural names
+remain aliases of the same product clients. The client has `sandboxes`, `images`, `volumes`, `snapshots`, `jobs`, `secrets`,
 `limits`, `feedback` and `support`; `webhooks`, `events`, `otel` and `audit`
 to watch the account; `domains`, `ports`, `addresses`, `tunnel` and `network`
 to connect sandboxes to your own world (paid accounts); and `mcp`, `sso`,
@@ -67,6 +72,8 @@ to connect sandboxes to your own world (paid accounts); and `mcp`, `sso`,
 the key is read-only and what its agent may still spend today. Every write carries an idempotency key, made for you, so the SDK's
 own retries (timeouts, 429, 503) never do anything twice. Errors are typed and
 carry a `code`, a `hint` and a `requestId`.
+`runtime.usageRequests("7d")` reads the account's API call counts and error rates;
+counts are exact decimal strings, and an empty window has a null `errorPercent`.
 
 ## Behind a proxy
 
@@ -89,7 +96,7 @@ Runtime improves fast because agents tell us what they run into: reports go stra
 
 ## Code written for E2B
 
-`withruntime/e2b` runs code written for E2B's SDK on Runtime. Change the
+`withruntime/e2b` translates supported E2B sandbox calls to Runtime. Change the
 import and set `RUNTIME_API_KEY`. The
 [switch guide](https://withruntime.com/docs/migrate) covers the other providers
 and how to work out what you save:
@@ -123,7 +130,7 @@ package list every mapping and gap.
 
 ## Code written for Blaxel
 
-`withruntime/blaxel` runs code written for Blaxel's sandbox SDK. Change the
+`withruntime/blaxel` translates supported Blaxel sandbox calls. Change the
 import:
 
 ```ts no-run
@@ -134,7 +141,7 @@ Sandboxes get Blaxel's default of 4096 MB, with one vCPU for every 2048 MB.
 Standby becomes Runtime's pause: after 60 seconds without a call a sandbox
 pauses with its memory and processes, and the next call wakes it. Envs,
 processes by name, files, previews, snapshots, forks and the code interpreter
-work as they do on Blaxel, and so do sessions: `sandbox.sessions` makes a
+are supported by the adapter, along with sessions: `sandbox.sessions` makes a
 Runtime sandbox session and `SandboxInstance.fromSession` drives the sandbox
 with its token. A Blaxel key is never sent anywhere. Drives, codegen, schedules and Blaxel's agent, model and MCP hosting throw
 `NotSupportedError` before anything happens, naming what to use instead.
@@ -154,7 +161,8 @@ https://withruntime.com/docs/frameworks.
 ## CLI
 
 ```bash no-run
-npx withruntime sandbox run -- python3 -c 'print(6 * 7)'   # connects on first use
+printf '%s\n' 'print(sum([125, 250, 375]))' > invoice.py
+npx withruntime sandbox run -- python3 - < invoice.py   # connects on first use
 npx withruntime sandbox create
 npx withruntime help
 ```

package/VERCEL.md

@@ -16,9 +16,9 @@ from withruntime.vercel import sandbox  # was: from vercel import sandbox
 from withruntime.vercel.sandbox import sync as sandbox  # was: from vercel.sandbox import sync as sandbox
 ```
 
-The mapping was written against `@vercel/sandbox` 3.5.0 and `vercel-sandbox`
+The mapping was written against `@vercel/sandbox` 3.5.1 and `vercel-sandbox`
 0.7.0 on PyPI (the `vercel.sandbox` module of `vercel` 0.11.4), checked
-23 September 2026.
+30 September 2026.
 
 ## Keys
 
@@ -73,7 +73,7 @@ are ignored.
 | `domain(port)`, `update({ ports })`                                   | The public preview of that port; ports added or removed.                                                                                    |
 | `stop()`, `delete()`, `extendTimeout(ms)`                             | `pause` (persistent) or `stop`; `stop`; `extend`.                                                                                           |
 | `update({ timeout, networkPolicy, snapshotExpiration })`              | `extend` (later only), network rules, retention.                                                                                            |
-| `snapshot()`, `Snapshot.get`, `Snapshot.list`, `snapshot.delete()`    | A Runtime snapshot (files, memory and processes), then the sandbox stops, as in Vercel; `snapshots.get`, `list`, `delete`.                  |
+| `snapshot()`, `Snapshot.get`, `Snapshot.list`, `snapshot.delete()`    | A verified disk-only capture, then the source stops; restored snapshots start fresh processes; `snapshots.get`, `list`, `delete`.           |
 | Error classes                                                         | `APIError` with a `response` whose status is Runtime's and `json` of `{ error: { code, message } }`; also `code`, `hint` and `requestId`.   |
 | Python: `create_sandbox`, `run_process`, `create_process`, `box.fs`   | The same mapping; operations await or work as context managers, which stop and by default destroy the sandbox; readers iterate by line.     |
 
@@ -98,6 +98,16 @@ Each of these throws `NotSupportedError` before anything happens. Its
 | `Drive`, `SandboxUser`, `defineSandboxProxy`               | Runtime volumes; `sudo`; `sandbox.withruntime.previews`.                                                    |
 | Listing by time, prefix or cursor (JavaScript)             | List them all and filter the result yourself. (Python applies a name prefix and newest-first order itself.) |
 
+Explicit snapshots require the released native disk-capture capability; a server
+that does not confirm disk-only capture is refused. If capture succeeds but the
+source cannot finish stopping, the error retains `snapshotId` and
+`sourceSandboxId` so the saved filesystem remains recoverable. JavaScript exposes
+them in `error.json.error.details` for API errors and directly on other errors;
+Python exposes them in `error.data` for API errors and directly on other errors.
+`snapshot_source_stop_timeout` means the source is still stopping after its wait;
+a failed stop request keeps its original error code. These contracts remain
+partial; controlled package comparisons do not prove hosted restoration.
+
 Some differences are not refusals:
 
 - A persistent sandbox keeps its memory and processes as well as its files

package/compatibility-lock.json

@@ -12,6 +12,29 @@
           "version": "2.51.0",
           "artifacts": {
             "2.51.0": "sha512-P+50lx1nOYpgCFyE1xuz6JVN/TqJivMUiH7v+RW0CUSfb4+NCu8IkC5KruT2sNPgp6aexddQQ77+OZKGpZZJ+Q=="
+          },
+          "latestReview": {
+            "version": "2.52.0",
+            "artifacts": {
+              "2.52.0": "sha512-TmUZlAvQq8BbguodpA+BBdawR/x5uILMQtHcLkdaLUqevsDjDdh46IYYU8ZRYKsQ4OhWr4xhsFIPSg1kgf+O0w=="
+            },
+            "reviewedAt": "2026-10-01",
+            "disposition": "held-for-sdk-qualification",
+            "evidence": {
+              "sourceUrls": [
+                "https://registry.npmjs.org/e2b/2.52.0",
+                "https://registry.npmjs.org/e2b/-/e2b-2.52.0.tgz"
+              ],
+              "artifactSha256": {
+                "2.52.0": "facbc53fa42757d94aa2be3433d779c7ab6b0afc780d4821a12a6d6815848c8e"
+              },
+              "changes": [
+                "dist/index.d.ts/index.mjs: HTTP1.1/2 selection, E2B_HTTP_VERSION, retry502/503 and connection failures, fork integer count 1..20, Dockerignore matching/precedence and invalid-pattern behavior changed. package.json changes protobuf/chalk/openapi-fetch floors. Installed transport/retry/fork/filesystem consumers not qualified; supported 2.51.0 unchanged.",
+                "Source digest dist/index.d.ts: 304acc9c8bbec8aeb69296719eb34986f987256e758aa7e220b551b9a7dcbd30 -> fa2e6eb09b6c6d3489056ee948248812e8879a23b6865561e5152f243bf6ca40.",
+                "Source digest dist/index.mjs: b75feeedb6543fee003533270b0f07fc1a9eb40315dfc0c44510e2dd8854b896 -> 343a41249ea8d48fe0a70fc986066d3ef97b6da2b71267211d21f77036efafea.",
+                "Source digest package.json: a2c759c4681b91b824aea7919f4661e498ec0e0b68d6cc333f4967f7b2b63f7b -> c5b699f80831b621178c83ea477d096bc1167e0083b6ba7a51d17f564207255f."
+              ]
+            }
           }
         },
         {
@@ -29,6 +52,34 @@
           "artifacts": {
             "e2b-2.51.0-py3-none-any.whl": "sha256-951d0fd069f017e760b338a435bdb83589b4bfb9574fc5203a7f777e9cb994c2",
             "e2b-2.51.0.tar.gz": "sha256-902ee861b30c8ec3e46e7f84db8c993f30695872c7b4490efaad1627ec6e08ba"
+          },
+          "latestReview": {
+            "version": "2.52.0",
+            "artifacts": {
+              "e2b-2.52.0-py3-none-any.whl": "sha256-6f4b5084b09986db43e99c7405bae6b14dc56984a69bbb1dc0687f1c71515cfb",
+              "e2b-2.52.0.tar.gz": "sha256-58c0042609513799341d4c1837e2581a4a5e73d3d62c9f1c57495c5e23eedee2"
+            },
+            "reviewedAt": "2026-10-01",
+            "disposition": "held-for-sdk-qualification",
+            "evidence": {
+              "sourceUrls": [
+                "https://pypi.org/pypi/e2b/2.52.0/json",
+                "https://files.pythonhosted.org/packages/53/71/1a01b7e4486b5962eaade7dba7026876a1b4569e49b464e82912d8801e38/e2b-2.52.0-py3-none-any.whl",
+                "https://files.pythonhosted.org/packages/3c/c4/560e7de54cece3573086f09d304e595729964aa18593b437125d9f8bd926/e2b-2.52.0.tar.gz"
+              ],
+              "artifactSha256": {
+                "e2b-2.52.0-py3-none-any.whl": "6f4b5084b09986db43e99c7405bae6b14dc56984a69bbb1dc0687f1c71515cfb",
+                "e2b-2.52.0.tar.gz": "58c0042609513799341d4c1837e2581a4a5e73d3d62c9f1c57495c5e23eedee2"
+              },
+              "changes": [
+                "e2b/connection_config.py/retry.py: HTTP1.1/2 selection and E2B_HTTP_VERSION; retries 502/503 and eligible network failures, excluding unsafe resource-creating replay. e2b/api clients replace pool shards with bounded least-in-flight shared pools, defaults 100 streams / 200 connections.",
+                "Fork count validation1..20 and template/dockerignore/fileIgnorePatterns matching/precedence changed. Installed sync/async transport/cleanup/retry/fork/filesystem consumers not qualified; supported 2.51.0 unchanged.",
+                "Source digest e2b/api/__init__.py: 00b09a79f25d01594c4b1ec5f14d3d0cc3ccc319958a2e1ca34ba91cdbf114b3 -> 640233a615a3c68752a2f2cecb1af919aebfc5e895bd4f09003aee61da38c7c0.",
+                "Source digest e2b/connection_config.py: 284aa3e7cc319432ca9147ddb7d9ab8cd315cf35283da7699eebe877375758a4 -> c165948133a2f174b5a490afa9502301d038d8097f91203b2c2174f451accf83.",
+                "Source digest e2b/retry.py: aa54aa8873fd44027a9c3ff790594d4583d2f415c0d3bd858566d2f0e15fa71f -> 40b1d7ea0732a721d77b31483e54f9f190e444cb798c54fc141856f52685e208.",
+                "Source digest e2b/template/dockerignore.py: None -> cba4ff9d7efa5ae987c4c0114770c114b5aefe2c18847e55d2bd811b9a1a088c."
+              ]
+            }
           }
         },
         {
@@ -38,6 +89,31 @@
           "artifacts": {
             "e2b_code_interpreter-2.10.0-py3-none-any.whl": "sha256-6ba776122086261875bc6033ef2dc42ac6b6e22cefdffdfd19d30e93bb09786f",
             "e2b_code_interpreter-2.10.0.tar.gz": "sha256-57fb7f9b9ad99ebbdf407619786fdb84e31537c2fbc8358c394aa0f0cbc1af28"
+          },
+          "latestReview": {
+            "version": "2.10.1",
+            "artifacts": {
+              "e2b_code_interpreter-2.10.1-py3-none-any.whl": "sha256-f4c9732699ee4b1c289acedac8bff66fccecc6ab374bf0b4ef88d5ad063e333d",
+              "e2b_code_interpreter-2.10.1.tar.gz": "sha256-94e504667788c6cbb175e5deaf1f68e8df474b670343fe1d72e2496b49d5a666"
+            },
+            "reviewedAt": "2026-10-01",
+            "disposition": "held-for-sdk-qualification",
+            "evidence": {
+              "sourceUrls": [
+                "https://pypi.org/pypi/e2b-code-interpreter/2.10.1/json",
+                "https://files.pythonhosted.org/packages/27/1f/0f9a4c4d9669afd5389e91bd96099a8eb1d1a32f9c67871cc56c4a8556b7/e2b_code_interpreter-2.10.1-py3-none-any.whl",
+                "https://files.pythonhosted.org/packages/38/e6/b01e60524e7e4d2e8ce634b3be6d00fe09c606f3d24a448b4a5c087d3bda/e2b_code_interpreter-2.10.1.tar.gz"
+              ],
+              "artifactSha256": {
+                "e2b_code_interpreter-2.10.1-py3-none-any.whl": "f4c9732699ee4b1c289acedac8bff66fccecc6ab374bf0b4ef88d5ad063e333d",
+                "e2b_code_interpreter-2.10.1.tar.gz": "94e504667788c6cbb175e5deaf1f68e8df474b670343fe1d72e2496b49d5a666"
+              },
+              "changes": [
+                "code_interpreter_{sync,async}.py: Jupyter get_transport argument changes from http2=False to http_version=\"1.1\". pyproject.toml and PKG-INFO raise e2b floor to 2.52.0,<3.0.0. Installed Jupyter cancellation/base SDK consumers not qualified; supported 2.10.0 unchanged.",
+                "Source digest e2b_code_interpreter/code_interpreter_sync.py: 298d832fe93e488300ac3174f2de590cc16d3563bdcc4ec31439d28265b66426 -> a88ff6a0df5163bceea545d077be090dbc78c96e48354e304677b02799eec17e.",
+                "Source digest pyproject.toml: 6c395fdf75ddc89acabb94fd0e419fc31317e6f3fa297894cbe7e766f090322c -> ef2b569a82f2e6edf722939ab27ca476a292886655c2af8f9e75eb9cae287941."
+              ]
+            }
           }
         }
       ]
@@ -128,18 +204,18 @@
         {
           "registry": "npm",
           "name": "@blaxel/core",
-          "version": "0.3.24",
+          "version": "0.3.25",
           "artifacts": {
-            "0.3.24": "sha512-zF1S7vx+mYHDbK9F4FQbdobz3N+YIlNqHCyOC7R7QpbQ4nP9laeCuQRaN1OTfJVZcRwFvFQ5Nx1lh0su+esd7g=="
+            "0.3.25": "sha512-K6aGUyIpgrPnkpwMOI/U/gbZwveOMu1Am04pkawZQjkp7NUa/roG0HC6NJPBp3AVVJY3CQtkGSWpAJ2DV4ZKpw=="
           }
         },
         {
           "registry": "pypi",
           "name": "blaxel",
-          "version": "0.4.12",
+          "version": "0.4.13",
           "artifacts": {
-            "blaxel-0.4.12-py3-none-any.whl": "sha256-9ca08aa0c1c5aaac87055f684eae002365c55010eaa008d5dc36c552e153210a",
-            "blaxel-0.4.12.tar.gz": "sha256-58dc5c9aea5b21aa65538f811c7de0b24e8e7a411bdf64e374a295eb1b9cb15e"
+            "blaxel-0.4.13-py3-none-any.whl": "sha256-b8817718ca63a2b31a5026f98c7191d5ed8f2f4c1aafc2d4aa57491a560a2146",
+            "blaxel-0.4.13.tar.gz": "sha256-a036256792e85238724b8bce38fb7c0b4f661fe4c3ac576258a8be1736ac8483"
           }
         }
       ]
@@ -225,10 +301,10 @@
         {
           "registry": "pypi",
           "name": "prime-sandboxes",
-          "version": "0.4.0",
+          "version": "0.4.1",
           "artifacts": {
-            "prime_sandboxes-0.4.0-py3-none-any.whl": "sha256-2a15263a30f3a3a27307c83701b92317af83ec8df0968e910100ccdb557cbb6b",
-            "prime_sandboxes-0.4.0.tar.gz": "sha256-a6934a5f5fce8342dbe9ade9816242e893ebf23b83a4fa5fda5b0ddbce651f27"
+            "prime_sandboxes-0.4.1-py3-none-any.whl": "sha256-1a1bb96afacc66d690815be82c0b7af180ea141421b7d180b4a0adbada4f38f0",
+            "prime_sandboxes-0.4.1.tar.gz": "sha256-53f7577dc9070e3b8e30db360f9e3cce3bcc35f8765b26f24f64dbc3c7763b06"
           }
         }
       ]

package/dist/blaxel/errors.js

@@ -95,7 +95,7 @@ const BLAXEL_HINTS = {
     sandbox_paused: "Call sandbox.unarchive(), then try again.",
     not_running: "The sandbox is not running: call sandbox.unarchive() if it was archived, or make a new one with SandboxInstance.create if it was deleted.",
     trial_busy: "The trial's sandboxes are all in use: delete one you no longer need (sandbox.delete()) or archive it (sandbox.archive()), then try again. Moving to paid credit is the account owner's decision.",
-    public_preview_not_allowed: "On the trial, share the port privately: sandbox.previews.create({ metadata: { name }, spec: { port, public: false } }) and a token from preview.tokens.create(expiresAt). A public preview needs a paid sandbox, which is the account owner's decision.",
+    public_preview_not_allowed: "On the trial, share the port privately: sandbox.previews.create({ metadata: { name }, spec: { port, public: false } }) and a token from preview.tokens.create(expiresAt) on a server supporting absolute preview deadlines. A public preview needs a paid sandbox, which is the account owner's decision.",
     busy: AGAIN,
     guest_busy: AGAIN,
     rate_limited: AGAIN,

package/dist/blaxel/lookup.d.ts

@@ -32,6 +32,7 @@ export declare function findSandbox(client: Runtime, name: string): Promise<Runt
 export declare function findByExternalId(client: Runtime, externalId: string): Promise<RuntimeSandbox>;
 /** Runs a create or fork that names a sandbox. When the name is still held
  * by a sandbox that is stopping (deleted a moment ago, by this client or
- * another), waits for it to stop, up to 30 seconds, and runs it once more, as
- * Blaxel's createIfNotExists waits out a sandbox being deleted. */
+ * another), waits for it to stop, up to 30 seconds, and runs it once more.
+ * This reconciles Runtime's stopping-name conflicts. Blaxel 0.3.25 delegates
+ * createIfNotExists reconciliation to its control plane without client polling. */
 export declare function whenNameFree<T>(client: Runtime, work: () => Promise<T>): Promise<T>;

package/dist/blaxel/lookup.js

@@ -54,8 +54,9 @@ export async function findByExternalId(client, externalId) {
 }
 /** Runs a create or fork that names a sandbox. When the name is still held
  * by a sandbox that is stopping (deleted a moment ago, by this client or
- * another), waits for it to stop, up to 30 seconds, and runs it once more, as
- * Blaxel's createIfNotExists waits out a sandbox being deleted. */
+ * another), waits for it to stop, up to 30 seconds, and runs it once more.
+ * This reconciles Runtime's stopping-name conflicts. Blaxel 0.3.25 delegates
+ * createIfNotExists reconciliation to its control plane without client polling. */
 export async function whenNameFree(client, work) {
     try {
         return await work();

package/dist/blaxel/pagination.d.ts

@@ -28,7 +28,7 @@ export type PaginatedList<T, TQuery extends CursorPaginationQuery = CursorPagina
 /** Blaxel's own helper: the items of a list answer in any of its shapes. */
 export declare function unwrapListData<T>(response: ListResponse<T>): T[];
 /** Blaxel's own helper, for a list fetched by `fetchPage`. */
-export declare function createPaginatedList<TRaw, TItem, TQuery extends CursorPaginationQuery>({ response, fetchPage, mapItem, query, }: {
+export declare function createPaginatedList<TRaw, TItem, TQuery extends CursorPaginationQuery>({ response, fetchPage, mapItem, query, seenCursors, }: {
     response: ListResponse<TRaw>;
     fetchPage: (query?: TQuery) => Promise<ListResponse<TRaw>>;
     mapItem: (item: TRaw) => TItem | Promise<TItem>;
@@ -36,4 +36,4 @@ export declare function createPaginatedList<TRaw, TItem, TQuery extends CursorPa
     seenCursors?: Set<string>;
 }): Promise<PaginatedList<TItem, TQuery>>;
 /** A Runtime page, each item mapped, as Blaxel's paginated list. */
-export declare function paginate<TRaw, TItem>(page: Page<TRaw>, map: (item: TRaw) => TItem): PaginatedList<TItem>;
+export declare function paginate<TRaw, TItem>(page: Page<TRaw>, map: (item: TRaw) => TItem, seenCursors?: Set<string>): PaginatedList<TItem>;