withruntime 0.9.0 → 0.11.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
 
@@ -38,10 +39,13 @@ package talks only to Runtime.
   `autoDeleteInterval` minutes rounded up to whole days. `delete()` ends it.
   An `ephemeral` sandbox (or `autoDeleteInterval: 0`) ends on `stop()`.
 - **Auto-stop:** Runtime runs a sandbox on a lease of up to an hour. The lease
-  is `autoStopInterval` minutes (default 15; `0` is an hour), and every call
-  through the adapter moves it on once less than half is left, so a sandbox
-  pauses after that long without calls, as Daytona's does. `ttlMinutes` caps
-  the renewals and ends the sandbox at the deadline.
+  is `autoStopInterval` minutes (default 15), and every call through the
+  adapter moves it on once less than half is left, so a sandbox pauses after
+  that long without calls, as Daytona's does. Past an hour, or `0` (never),
+  the sandbox object also renews the lease each minute while it lives, toward
+  `autoStopInterval` after the last call; once the program ends, the sandbox
+  pauses within an hour. `ttlMinutes` caps the renewals and ends the sandbox at
+  the deadline.
 - **Funding:** left to Runtime, as `withruntime`'s own `create()` does: the free
   trial while the account has trial time, then prepaid credit. Pass
   `withruntime: { create: { funding: "trial" } }` to `new Daytona(...)` or to
@@ -54,31 +58,35 @@ package talks only to Runtime.
 
 ## Mapping
 
-| Daytona                                                                       | On Runtime                                                                                                                                                                                                    |
-| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `daytona.create()`, `create({ snapshot })`                                    | `sandboxes.create`. Daytona's own snapshots (`daytona-*`) are Runtime's stock image. Any other name is a ready Runtime image of that name, then a Runtime snapshot of that name.                              |
-| `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.                                                                                           |
-| `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.                                                                                                 |
-| `daytona.get(idOrName)`, `daytona.list({ labels, states, name })`             | `sandboxes.get`, or the newest live sandbox with that name; `sandboxes.list`. Awaiting `list()` gives the older `{ items, total }` shape.                                                                     |
-| `process.executeCommand(cmd, cwd, env, timeout)`                              | `exec` under bash with stderr joined to stdout, as Daytona's `result`, streamed so the whole output comes back. A non-zero exit is a result. Past `timeout` (seconds): `DaytonaProcessExecutionTimeoutError`. |
-| `process.codeRun(code, { argv, env })`                                        | `python3 -c`, `node -e` or `bun -e` by the sandbox's language. `artifacts.charts` is always empty.                                                                                                            |
-| `createSession`, `executeSessionCommand`, `getSessionCommandLogs`             | One bash per session, kept running: directory, variables and functions carry from one command to the next. `runAsync` returns at once; logs stream to callbacks.                                              |
-| `sendSessionCommandInput`, `getSession`, `getSessionCommand`, `deleteSession` | Input to the session's shell, which the running command reads; the commands sent through this object; killing the shell.                                                                                      |
-| `fs.uploadFile(s)`, `downloadFile(s)`, `listFiles`, `getFileDetails`          | Runtime's files API. Relative paths resolve from `/workspace`. `owner` and `group` are always `""`.                                                                                                           |
-| `fs.createFolder`, `deleteFile`, `moveFiles`, `setFilePermissions`            | `mkdir -m`, `files.remove`, `files.rename`, `chmod` and `sudo chown`.                                                                                                                                         |
-| `fs.findFiles`, `searchFiles`, `replaceInFiles`                               | `grep -rn`, a files glob, and a read and write of each file.                                                                                                                                                  |
-| `git.clone`, `status`, `add`, `commit`, `push`, `pull`, branches              | The sandbox's git. Credentials reach git through the environment, never the command line.                                                                                                                     |
-| `codeInterpreter.runCode`, contexts                                           | Runtime's Python interpreter. The sandbox's `envVars` reach code through a context made once for them.                                                                                                        |
-| `start`, `stop`, `pause`, `archive`, `delete`, `fork`, `createSnapshot`       | `wake`, `pause` (or `stop` when ephemeral), `pause`, `pause`, `stop`, Runtime's fork with memory, a Runtime snapshot with that name.                                                                          |
-| `getPreviewLink(port)`                                                        | A Runtime preview. Send its token as `x-runtime-preview-token`; Daytona's header is `x-daytona-preview-token`.                                                                                                |
-| `getUserHomeDir`, `getWorkDir`, `user`                                        | `/workspace`, and `daytona`, so `/home/daytona` (linked to `/workspace` the first time something names it) works.                                                                                             |
-| `daytona.snapshot.create`, `get`, `list`, `delete`                            | Runtime images built, found, listed and deleted by name.                                                                                                                                                      |
-| `daytona.volume.get`, `list`, `delete`                                        | Runtime volumes by name.                                                                                                                                                                                      |
-| Error classes                                                                 | Daytona's names and parents, by HTTP status. Each also carries Runtime's `code`, `hint` and `requestId`, with the original error as `cause`.                                                                  |
+| Daytona                                                                       | On Runtime                                                                                                                                                                                                                                                                 |
+| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `daytona.create()`, `create({ snapshot })`                                    | `sandboxes.create`. Daytona's own snapshots (`daytona-*`) are Runtime's stock image. Any other name is a ready Runtime image of that name, then a Runtime snapshot of that name.                                                                                           |
+| `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.                                                                                                                                                              |
+| `daytona.get(idOrName)`, `daytona.list(query)`                                | `sandboxes.get`, or the newest live sandbox with that name; `sandboxes.list` by labels and states, then Daytona's other filters (`id` and `name` prefixes, CPU, memory, disk, dates), `sort` and `order` here. Awaiting `list()` gives the older `{ items, total }` shape. |
+| `process.executeCommand(cmd, cwd, env, timeout)`                              | `exec` under bash with stderr joined to stdout, as Daytona's `result`, streamed so the whole output comes back. A non-zero exit is a result. Past `timeout` (seconds): `DaytonaProcessExecutionTimeoutError`.                                                              |
+| `process.codeRun(code, { argv, env })`                                        | `python3 -c`, `node -e` or `bun -e` by the sandbox's language. `artifacts.charts` is always empty.                                                                                                                                                                         |
+| `createSession`, `executeSessionCommand`, `getSessionCommandLogs`             | One bash per session, kept running: directory, variables and functions carry from one command to the next. `runAsync` returns at once; logs stream to callbacks.                                                                                                           |
+| `sendSessionCommandInput`, `getSession`, `getSessionCommand`, `deleteSession` | Input to the session's shell, which the running command reads; the commands sent through this object; killing the shell.                                                                                                                                                   |
+| `fs.uploadFile(s)`, `downloadFile(s)`, `listFiles`, `getFileDetails`          | Runtime's files API. Relative paths resolve from `/workspace`. `owner` and `group` are always `""`.                                                                                                                                                                        |
+| `fs.createFolder`, `deleteFile`, `moveFiles`, `setFilePermissions`            | `mkdir -m`, `files.remove`, `files.rename`, `chmod` and `sudo chown`.                                                                                                                                                                                                      |
+| `fs.findFiles`, `searchFiles`, `replaceInFiles`                               | `grep -rn`, a files glob, and a read and write of each file.                                                                                                                                                                                                               |
+| `git.clone`, `status`, `add`, `commit`, `push`, `pull`, branches              | The sandbox's git. Credentials reach git through the environment, never the command line.                                                                                                                                                                                  |
+| `codeInterpreter.runCode`, contexts                                           | Runtime's Python interpreter. The sandbox's `envVars` reach code through a context made once for them.                                                                                                                                                                     |
+| `start`, `stop`, `pause`, `archive`, `delete`, `fork`, `createSnapshot`       | `wake`, `pause` (or `stop` when ephemeral), `pause`, `pause`, `stop`, Runtime's fork with memory, a Runtime snapshot with that name.                                                                                                                                       |
+| `getPreviewLink(port)`                                                        | A Runtime preview. Send its token as `x-runtime-preview-token`; Daytona's header is `x-daytona-preview-token`.                                                                                                                                                             |
+| `getUserHomeDir`, `getWorkDir`, `user`                                        | `/workspace`, and `daytona`, so `/home/daytona` (linked to `/workspace` the first time something names it) works.                                                                                                                                                          |
+| `create({ user })` (Python `os_user`)                                         | The user must exist in the image, as on Daytona. Commands, sessions and terminals run as it through `sudo`; files written through `fs` are given to it. It joins the owner's group, so both can share `/workspace`.                                                        |
+| `process.createPty`, `connectPty`, `listPtySessions`, `resizePtySession`      | A shell started with a terminal, which outlives the connection: `disconnect()` leaves it running, `connectPty` attaches again with what it printed so far, `killPtySession` ends it.                                                                                       |
+| `computerUse.mouse`, `keyboard`, `screenshot`, `display`, `recording`         | Runtime's desktop. `start()` installs it the first time, which takes a minute or two. Key names are Daytona's or xdotool's.                                                                                                                                                |
+| `daytona.snapshot.create`, `get`, `list`, `delete`                            | Runtime images built, found, listed and deleted by name.                                                                                                                                                                                                                   |
+| `daytona.volume.get`, `list`, `delete`                                        | Runtime volumes by name.                                                                                                                                                                                                                                                   |
+| Error classes                                                                 | Daytona's names and parents, by HTTP status. Each also carries Runtime's `code`, `hint` and `requestId`, with the original error as `cause`.                                                                                                                               |
 
 ## Gaps
 
@@ -90,22 +98,26 @@ Each of these throws `NotSupportedError` before anything happens. Its
 | A snapshot name with no Runtime image or snapshot                     | `daytona.snapshot.create({ name, image })` here, or `npx withruntime image build`. This throws `DaytonaNotFoundError`.                                                                  |
 | GPUs, `spot`, `linkedSandbox`, `secrets`, `otelEndpointOverride`      | Runtime runs Linux on CPUs. For `secrets`, a Runtime secret (`npx withruntime secrets set NAME --host <host>`): the sandbox sees a placeholder. For telemetry, `runtime.otel.create()`. |
 | A `target` other than `us`, `jwtToken`                                | Runtime runs in one US region and signs in with keys.                                                                                                                                   |
-| `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.                                                                                                                               |
+| The entrypoint session, language servers                              | Sessions with `runAsync`.                                                                                                                                                               |
+| Screenshots of a region, with the cursor, scaled, or as WebP          | The whole screen as PNG or JPEG; crop and scale it yourself.                                                                                                                            |
+| `computerUse.accessibility`, the desktop's processes one by one       | Screenshots with the mouse and keyboard; `computerUse.getStatus()`, `stop()` and `start()`.                                                                                             |
+| `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.                                                                                                              |
 | `volume.create(name)`                                                 | Runtime volumes have a size: `runtime.volumes.create({ name, sizeMiB })`.                                                                                                               |
 | `secret`, `warmPool`                                                  | A Runtime secret for credentials; Runtime starts from warm templates already.                                                                                                           |
 | `runCode(code, { envs })`                                             | `envVars` at create, or `os.environ` in the code.                                                                                                                                       |
-| Listing by anything but name, labels and states                       | Filter the result yourself.                                                                                                                                                             |
+| Listing by `isPublic`, `snapshots` or `autoDestroyAt`                 | Filter by a label you set at create.                                                                                                                                                    |
+
+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.
 
@@ -20,9 +20,9 @@ from withruntime.e2b import Sandbox  # was: from e2b import Sandbox
 from withruntime.e2b.code_interpreter import Sandbox  # was: from e2b_code_interpreter import Sandbox
 ```
 
-The mapping was written against `e2b` 2.51.0 and `@e2b/code-interpreter`
-2.8.0 (Python: `e2b` 2.51.0, `e2b-code-interpreter` 2.10.0), checked
-29 September 2026. The exact package releases and artifact hashes are kept in
+The mapping was written against `e2b` 2.51.0 and checked against `e2b` 2.52.0
+and `@e2b/code-interpreter` 2.8.0 (Python: `e2b` 2.52.0, `e2b-code-interpreter`
+2.10.1) on 2 October 2026. The exact package releases and artifact hashes are kept in
 `compatibility-lock.json`.
 
 ## Keys
@@ -51,38 +51,40 @@ machine. An E2B key (`e2b_...`) is never sent anywhere. If one is passed as
 
 ## Mapping
 
-| E2B                                                                                      | On Runtime                                                                                                                                                                                                                                                  |
-| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Sandbox.create()`, `Sandbox.create(template, opts)`                                     | `sandboxes.create`. `base` and `code-interpreter-v1` are Runtime's stock image. Any other name must be a ready Runtime image with that name. A UUID is an image or a snapshot.                                                                              |
-| `timeoutMs` (Python `timeout`, seconds)                                                  | `timeoutSeconds`, rounded up. Under 60 s becomes 60 s, with a warning. Over an hour is refused.                                                                                                                                                             |
-| `metadata`                                                                               | labels (at most 32).                                                                                                                                                                                                                                        |
-| `envs`                                                                                   | Given to every command and code run through this object.                                                                                                                                                                                                    |
-| `allowInternetAccess: false`                                                             | `network: { internet: false }`.                                                                                                                                                                                                                             |
-| `lifecycle.onTimeout`                                                                    | `onLeaseEnd`: `kill` is `stop`, `pause` is `pause`.                                                                                                                                                                                                         |
-| `commands.run(cmd, { cwd, envs, timeoutMs, onStdout, onStderr })`                        | A native process with streamed output; output lost before it was read sets `truncated` and warns. The default command connection deadline is 60 s; `0` disables it. The sandbox lease still bounds the process.                                             |
-| Non-zero exit                                                                            | Throws `CommandExitError` with `exitCode`, `stdout`, `stderr` and `error` (`exit status N`). A command killed by a signal has `exitCode` -1.                                                                                                                |
-| 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.                                                                                                                                                                |
-| `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.                                                                                                                              |
-| `files.makeDir`, `exists`, `getInfo`, `rename`, `remove`                                 | `files.stat`, `mkdir`, `rename` (replacing a file that exists) and `remove` (recursive). A missing file throws `FileNotFoundError`.                                                                                                                         |
-| Relative paths                                                                           | Resolved against the home directory, `/workspace` on Runtime.                                                                                                                                                                                               |
-| `/home/user` (E2B's home)                                                                | The first time a path, `cwd` or command names it, it becomes a link to `/workspace`, unless something is already there.                                                                                                                                     |
-| `sandbox.kill()`, `Sandbox.kill(id)`                                                     | `stop`, without waiting. `false` when the sandbox was not found or had already ended.                                                                                                                                                                       |
-| `sandbox.setTimeout(ms)`, `Sandbox.setTimeout(id, ms)`                                   | `extend`: the end moves to now + ms. Moving it earlier is refused.                                                                                                                                                                                          |
-| `Sandbox.connect(id, { timeoutMs })`, `sandbox.connect()`                                | `get`. A paused sandbox is woken. A running one's end moves later, never earlier. An ended one throws `SandboxNotFoundError`.                                                                                                                               |
-| `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.                                                                                                                              |
-| `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.                                                                                             |
-| Error classes                                                                            | E2B's names and parents. Each also carries Runtime's `code`, `hint` and `requestId`, with the original error as `cause`.                                                                                                                                    |
+| E2B                                                                                      | On Runtime                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Sandbox.create()`, `Sandbox.create(template, opts)`                                     | `sandboxes.create`. `base` and `code-interpreter-v1` are Runtime's stock image. Any other name must be a ready Runtime image with that name. A UUID is an image or a snapshot.                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `timeoutMs` (Python `timeout`, seconds)                                                  | `timeoutSeconds`, rounded up. Under 60 s becomes 60 s, with a warning. Up to 24 hours, as on E2B: a Runtime lease reaches at most an hour ahead, so while this process runs the adapter extends it every five minutes, never past the end asked for. If the process ends first, the sandbox ends with its last lease, at most an hour later. Over 24 hours throws `InvalidArgumentError`.                                                                                                                                                                                                               |
+| `metadata`                                                                               | labels (at most 32).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `envs`                                                                                   | Given to every command and code run through this object.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `allowInternetAccess: false`                                                             | `network: { internet: false }`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `lifecycle.onTimeout`                                                                    | `onLeaseEnd`: `kill` is `stop`, `pause` is `pause`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `commands.run(cmd, { cwd, envs, timeoutMs, onStdout, onStderr })`                        | A native process started by a streamed exec that reads it from the first byte, so Runtime holds a fast writer back rather than drop output: the result is whole, however long. The default command connection deadline is 60 s; `0` disables it. The process lives up to 24 hours, within the sandbox lease.                                                                                                                                                                                                                                                                                            |
+| Non-zero exit                                                                            | Throws `CommandExitError` with `exitCode`, `stdout`, `stderr` and `error` (`exit status N`). A command killed by a signal has `exitCode` -1.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| 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`. Runtime keeps the last 1 MiB a process printed; anything older that was not read in time is lost, which sets `truncated` and warns. A command with `stdin: true` starts the same way.                                                                                                                                                                                                                                                             |
+| `user` (commands, PTY and files)                                                         | Runs as that Linux user through `sudo -u`; `root` needs nothing more. A user the sandbox lacks throws `InvalidArgumentError` saying how to add one; none is ever created. `user: "user"` is the sandbox's own user. Watching a directory as another user is refused.                                                                                                                                                                                                                                                                                                                                    |
+| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `files.makeDir`, `exists`, `getInfo`, `rename`, `remove`                                 | `files.stat`, `mkdir`, `rename` (replacing a file that exists) and `remove` (recursive). A missing file throws `FileNotFoundError`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Relative paths                                                                           | Resolved against the home directory, `/workspace` on Runtime.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `/home/user` (E2B's home)                                                                | The first time a path, `cwd` or command names it, it becomes a link to `/workspace`, unless something is already there.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `sandbox.kill()`, `Sandbox.kill(id)`                                                     | `stop`, without waiting. `false` when the sandbox was not found or had already ended.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `sandbox.setTimeout(ms)`, `Sandbox.setTimeout(id, ms)`                                   | `extend`: the end moves to now + ms, up to 24 hours (past an hour it is carried on as for `timeoutMs`). An earlier end is refused: Runtime cannot end a lease early.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `Sandbox.connect(id, { timeoutMs })`, `sandbox.connect()`                                | `get`. A paused sandbox is woken. A running one's end moves later, never earlier, up to 24 hours. An ended one throws `SandboxNotFoundError`.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `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()`, `nextToken`). A `template` or `startedAfter` filter, `order: "desc"` and a saved `nextToken` are applied by the adapter, which reads every match once and pages through them.                                                                                                                                                                                                                                                                                                                       |
+| `fork`, `createSnapshot`, `deleteSnapshot`                                               | Runtime's memory-preserving forks and snapshots; deleting a snapshot removes that saved capture. A fork's `count` is 1 to 20, as E2B checks it.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `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. On the free trial a shared port is private and a host alone cannot reach it, so both throw `PublicPreviewNotAllowedError` (Python: `PublicPreviewNotAllowedException`, a kind of `NotSupportedError`) at once. Use `(await sandbox.runtime.previews.create(port)).urlWithToken`, or send its token as the `x-runtime-preview-token` header. |
+| `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. `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
 
@@ -90,27 +92,23 @@ Each of these throws `NotSupportedError` (Python: `NotSupportedException`)
 before anything happens. The error's `feature` names the gap and its
 `alternative` says what to use.
 
-| E2B                                                                                          | Use instead                                                                                                         |
-| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| An E2B template name with no Runtime image of that name                                      | Build it: `npx withruntime image build --dockerfile e2b.Dockerfile --name <template>`. This throws `TemplateError`. |
-| `Template`, `waitForPort` and the other ready checks                                         | `runtime.images.build(...)`                                                                                         |
-| `timeoutMs` over one hour                                                                    | Create with up to an hour, then call `setTimeout` before it ends, as often as needed.                               |
-| `setTimeout` to an earlier time                                                              | `kill()` when the work is done.                                                                                     |
-| `keepMemory: false`                                                                          | Runtime's pause keeps memory.                                                                                       |
-| `onResume: "reboot"`                                                                         | Stop the sandbox and create a new one.                                                                              |
-| `fork({ timeoutMs })`                                                                        | Fork without it, then call `setTimeout` on each fork.                                                               |
-| `user: "root"` (commands and files)                                                          | Prefix the command with `sudo`, which needs no password.                                                            |
-| `network`, `updateNetwork`                                                                   | `runtime: { create: { network } }` and `sandbox.runtime.network.set(...)`.                                          |
-| `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`.                                                                                     |
-| `Sandbox.list` by `template` or `startedAfter`, `order: "desc"`, or from a saved `nextToken` | Filter by metadata, and keep the paginator.                                                                         |
-| `runCode(code, { envs })`                                                                    | A context made with them: `sandbox.runtime.interpreter.contexts.create({ env })`.                                   |
-| `domain`, `apiUrl`, `sandboxUrl`, `headers`, `proxy`, `debug`                                | Remove them. `RUNTIME_API_URL` sets Runtime's origin, and `HTTPS_PROXY` sets a proxy.                               |
+| E2B                                                           | Use instead                                                                                                         |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| An E2B template name with no Runtime image of that name       | Build it: `npx withruntime image build --dockerfile e2b.Dockerfile --name <template>`. This throws `TemplateError`. |
+| `Template`, `waitForPort` and the other ready checks          | `runtime.images.build(...)`                                                                                         |
+| `setTimeout` to an earlier time                               | `kill()` when the work is done.                                                                                     |
+| `keepMemory: false`                                           | Runtime's pause keeps memory.                                                                                       |
+| `onResume: "reboot"`                                          | Stop the sandbox and create a new one.                                                                              |
+| `fork({ timeoutMs })`                                         | Fork without it, then call `setTimeout` on each fork.                                                               |
+| `network`, `updateNetwork`                                    | `runtime: { create: { network } }` and `sandbox.runtime.network.set(...)`.                                          |
+| `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 }] } }`.                                          |
+| `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`.                                                                                     |
+| `runCode(code, { envs })`                                     | A context made with them: `sandbox.runtime.interpreter.contexts.create({ env })`.                                   |
+| `domain`, `apiUrl`, `sandboxUrl`, `headers`, `proxy`, `debug` | Remove them. `RUNTIME_API_URL` sets Runtime's origin, and `HTTPS_PROXY` sets a proxy.                               |
 
 Directory watches use Runtime's native watch stream. JavaScript uses
 `files.watchDir(path, onEvent, options)`. Python's synchronous `watch_dir(path)`
@@ -120,16 +118,21 @@ 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`.
-  Python file `request_timeout` bounds the request, including streamed reads. `retries`, `logger`, `secure` and `validateApiKey` are
+- 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`, `validateApiKey` and
+  `httpVersion` (Python `http_version`; `'1.1'` or `'2'`, as E2B checks it) are
   accepted without changing the native transport settings.
 - Interpreter deadlines follow the pinned packages: JavaScript defaults to
   sixty seconds and Python to five minutes; zero disables the read deadline.

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
 ```