withruntime 0.11.2 → 0.14.0

package/BLAXEL.md

@@ -42,7 +42,7 @@ name, or through `getByExternalId`, use the same Runtime key.
   `sudo enable-docker`). Any other image `ns/name:tag` is the ready Runtime
   image named `ns-name` (every `/` becomes `-`, as Runtime names hold none) at
   tag `tag` (`latest` when none is given). Build it once with
-  `npx withruntime image build --dockerfile Dockerfile --name ns-name -t ns-name:tag`,
+  `npx withruntime images build --dockerfile Dockerfile --name ns-name -t ns-name:tag`,
   and the code keeps `image: "ns/name:tag"` as it is.
 - **Standby and lifetime:** a Blaxel sandbox goes to standby when unused and
   resumes on the next call. On Runtime it pauses after 60 seconds without a
@@ -121,7 +121,7 @@ names the gap and its `alternative` says what to use.
 
 | Blaxel                                                                                                                   | Use instead                                                                                                                             |
 | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| An `image` with no ready Runtime image of the name it maps to (Blaxel's other templates too)                             | Build it: `npx withruntime image build --dockerfile Dockerfile --name ns-name -t ns-name:tag`; the error gives the exact command.       |
+| An `image` with no ready Runtime image of the name it maps to (Blaxel's other templates too)                             | Build it: `npx withruntime images build --dockerfile Dockerfile --name ns-name -t ns-name:tag`; the error gives the exact command.      |
 | A region outside the US                                                                                                  | Runtime runs in one US region.                                                                                                          |
 | `extraArgs` other than `iptables`; network `egress`, `firewall`, `subnet`, and a `proxy` with more than its domain lists | Remove them; `allowedDomains` and `forbiddenDomains` (on the network or its proxy); Runtime secrets.                                    |
 | Read-only and ephemeral volumes; a volume with no Runtime volume of that name                                            | Mount read-write; write scratch files under `/workspace`; `runtime.volumes.create`.                                                     |

package/COMPATIBILITY.md

@@ -18,14 +18,79 @@ published 30 September 2026, is a different package: it removes `getSandbox`, th
 pin stays 0.12.10; `compatibility-lock.json` records 1.0.0 as reviewed and
 unsupported, and `bun run compat:upstream` flags any other release.
 
-| Provider    | Published package inspected             | Runtime import            | Implemented sandbox surface                                                                                                                                                                                                                                                                             |
-| ----------- | --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Runloop     | `@runloop/api-client` 1.32.0            | `withruntime/runloop`     | `Runloop`, devbox create/get/list/suspend/resume/shutdown, disk snapshots; synchronous and asynchronous commands, resident named shells with variables, functions, aliases, options and working directory, execution completion/output/stdin/signals, text files                                        |
-| CodeSandbox | `@codesandbox/sdk` 2.4.2                | `withruntime/codesandbox` | `CodeSandbox`, `VMTier`, create/fork/resume/shutdown/restart/hibernate/delete/list/get; connected command and file clients; output/status subscriptions and same-client command restart; configured tasks and setup steps; public preview ports and readiness checks                                    |
-| Fly Sprites | `@fly/sprites` 0.2.3                    | `withruntime/sprites`     | `SpritesClient`, create/lookup/list/delete/restart; `exec`, `execFile`, Node streams and event-based `spawn`; attachable native processes; binary/text/JSON files, directory traversal, append, chmod; preview access settings                                                                          |
-| Freestyle   | `freestyle` 0.2.16                      | `withruntime/freestyle`   | `Freestyle`, VM create/ref/get/list/start/pause/delete/update; command execution, binary/text files and streams, filesystem metadata; native snapshots; explicit deny-all or outbound-public firewall intent                                                                                            |
-| Modal       | `modal` 0.11.0                          | `withruntime/modal`       | `ModalClient`, app-name grouping, registry images and Dockerfile layers, CPU sandbox create/get/list/name lookup, text/binary process streams and stdin, command completion, filesystem transfer and metadata, tags, encrypted public previews, outbound allowlists, memory snapshot capture            |
-| Cloudflare  | `@cloudflare/sandbox` 0.12.10 (0.x API) | `withruntime/cloudflare`  | `getSandbox`, named Runtime sandboxes, explicit execution sessions, text exec and SSE output, background processes, logs/signals/waits, binary/text files, recursive listings, environment updates, signed Runtime previews, conditional Worker Durable Object entry, Worker preview proxy, destruction |
+| Provider    | Published package inspected             | Runtime import            | Implemented sandbox surface                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------- | --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Runloop     | `@runloop/api-client` 2.0.0             | `withruntime/runloop`     | `Runloop`, basic `RunloopSDK` command handles, devbox create/get/list/suspend/resume/shutdown, disk snapshots; synchronous and asynchronous commands, resident named shells with variables, functions, aliases, options and working directory, execution completion/output/stdin/signals, text files                                                                                                                     |
+| CodeSandbox | `@codesandbox/sdk` 2.4.2                | `withruntime/codesandbox` | `CodeSandbox`, `VMTier`, create/fork/resume/shutdown/restart/hibernate/delete/list/get; connected command and file clients; output/status subscriptions and same-client command restart; configured tasks and setup steps; public preview ports and readiness checks                                                                                                                                                     |
+| Fly Sprites | `@fly/sprites` 0.2.3                    | `withruntime/sprites`     | `SpritesClient`, create/lookup/list/delete/restart; `exec`, `execFile`, Node streams and event-based `spawn`; attachable native processes; binary/text/JSON files, directory traversal, append, chmod, chown and `asRoot` through sudo, file watches; preview access settings; checkpoints as disk snapshots; domain network policy; session kill; port watcher and port proxy; `APIError` with the vendor's limit codes |
+| Freestyle   | `freestyle` 0.2.17                      | `withruntime/freestyle`   | `Freestyle`, VM create/ref/get/list/start/pause/delete/update; command execution, binary/text files and streams, filesystem metadata; native snapshots; explicit deny-all or outbound-public firewall intent                                                                                                                                                                                                             |
+| Modal       | `modal` 0.11.0                          | `withruntime/modal`       | `ModalClient`, app-name grouping, registry images and Dockerfile layers, CPU sandbox create/get/list/name lookup, text/binary process streams and stdin, command completion, filesystem transfer and metadata, tags, encrypted public previews, outbound allowlists, memory snapshot capture                                                                                                                             |
+| Cloudflare  | `@cloudflare/sandbox` 0.12.10 (0.x API) | `withruntime/cloudflare`  | `getSandbox`, named Runtime sandboxes, explicit execution sessions, text exec and SSE output, background processes, logs/signals/waits, binary/text files, recursive listings, environment updates, signed Runtime previews, conditional Worker Durable Object entry, Worker preview proxy, destruction                                                                                                                  |
+
+### Freestyle 0.2.17 review (11 October 2026)
+
+The pin advances from 0.2.16; support remains partial. The exact npm tarballs
+were compared without installing or executing them.
+
+- New `FreestyleTransportError` (a `TypeError` with `errors` and `toJSON`) for a
+  fetch that got no HTTP response. The adapter throws it, with the native
+  `ConnectionError` as `cause`, where it used to throw `FreestyleApiError`.
+- `exec` accepts `timeoutMs` up to 24 hours on guest agents with native
+  resumable exec, else 5 minutes (`AGENT_UNSUPPORTED`). Runtime passes the
+  value to its native exec unchanged; no adapter change.
+- `ListObjects` joins the S3 operations of the TLS edge (refused here with the
+  rest of `tls`). Identity-token clients now background execs; identity tokens
+  are refused here. Docs-only changes elsewhere.
+
+### Runloop 2.0.0 review (8 October 2026)
+
+Both `@runloop/api-client` and Python `runloop-api-client` 2.0.0 retain the
+covered sandbox API. Both pins advance; support remains partial. The exact npm
+tarballs and every PyPI wheel/source archive for 1.32.0 and 2.0.0 were compared
+without installing or executing them. Python wheel and source package contents
+match. The upstream checker needs no new record type: this is a sandbox adapter
+update, not a refusal of the major release or deferred source qualification.
+
+- Both releases remove benchmark jobs/runs, scenarios, scorers, their types and
+  pagination, shared `RunProfile`, benchmark/scenario key scopes, and the
+  `scenario`/`scoring_validation` devbox initiators. Python also removes
+  `InputContextPreview`. None was implemented by these sandbox adapters.
+- JavaScript execution `sendStdIn` now requires a body; the options-only overload
+  is removed. Both languages require exactly one nonempty text value or signal.
+  The adapters validate before lookup and map text, EOF and INTERRUPT to native
+  process input, EOF and SIGINT. Python's new synchronous/asynchronous
+  `Execution.send_std_in` and `close_std_in` helpers are implemented with scoped
+  request timeouts. JavaScript adds `RunloopSDK.devbox.create`/`fromId`,
+  `cmd.exec`/`execAsync`, and execution handles with `sendStdIn`/`closeStdIn`,
+  state, kill and result/output methods. The handle calls the same validated
+  low-level input path and throws `RunloopError` on an unsuccessful reply.
+  This is a basic command facade, not the full upstream high-level SDK:
+  callback streaming and extra polling options refuse with native alternatives;
+  file, shell, snapshot and list workflows still use the low-level adapter.
+- New `SecretById`/`AsyncSecretById` handles and retrieve/update/delete-by-ID calls
+  select exact secret rows. Name reads/updates instead select the greatest ID;
+  deletion removes all selected same-name rows nonatomically. Runloop's duplicate
+  secret rows and injected environment-secret semantics are not Runtime's
+  host-scoped secret API. Access to the secret namespace refuses explicitly and
+  names that native alternative.
+- Objects add `upload_headers`; upload helpers preserve those headers, isolate
+  API credentials, refuse redirects/retries and redact upload errors. Python's
+  storage wrappers accept optional headers and clear them on completion. The
+  adapter refuses Runloop storage objects and points to Runtime sandbox files.
+- Axons add `deleted_at_ms` and retain readable deleted registry entries while
+  refusing updates; gateway/MCP/network-policy names become reusable labels, and
+  devbox gateway/MCP names bind the newest configuration. Those provider service
+  namespaces refuse explicitly, naming Runtime events, secrets or sandbox egress
+  settings as the alternative; these are not equivalent Runloop services.
+- Tunnel documentation clarifies that omitted authentication means open/public.
+  Runloop tunnels remain outside the covered surface; use Runtime signed
+  previews. Python custom CPU annotations change from integer to float, allowing
+  0.5 cores upstream; the adapters still refuse fractional CPU before allocation
+  and direct callers to Runtime whole cores.
+
+The focused tests use simulated native processes/transports and guest state.
+They do not execute the downloaded SDKs or prove live Runloop behavior,
+Linux isolation, durability, host recovery, or a competitor performance margin.
 
 ## Authentication and resources
 
@@ -128,7 +193,7 @@ Remaining implementation work is tracked only in the repository `WORKLIST.md`.
 | All six     | Default sandboxes use Runtime's environment. Explicit vendor image/template/snapshot IDs require migration to Runtime; arbitrary foreign IDs are not substituted with a stock image. Provider credential formats, wire protocols, error hierarchies and every optional transport hook are not interchangeable. Retained process output is bounded. Binary process mode requires the native byte-output capability (`outputEncoding`); an API or guest without it refuses before execution. This capability has only local release evidence here.                                                                                                                                                                                                                                                                                                                                                      |
 | Runloop     | Blueprints name Runtime image IDs/names; snapshots name Runtime snapshots. No provider blueprint builds, mounts, secret gateways, MCP grants, lifecycle hooks or ARM placement. `X_SMALL`/fractional CPU shapes are refused. Named shells use a resident Bash process. Interactive stdin in named shells is explicitly refused. `snapshotDisk` takes a blocking disk-only native snapshot; `snapshotDiskAsync` is refused, a memory snapshot is refused as a disk snapshot, and snapshot metadata beyond Runtime's label bounds is refused. `diskSnapshots` lists, updates, polls and deletes them. Devbox and snapshot lists return cursor pages that can be awaited or iterated across pages; the generated `APIPromise` wrapper and its response helpers are not reproduced.                                                                                                                       |
 | CodeSandbox | No browser editor/Pitcher protocol, browser-session tokens, interpreters, live VM resizing, fork tier changes, read-only or global editor sessions, or private host-token emulation. Configured tasks run under a guest supervisor and setup steps under a guest runner, both started by the adapter and surviving client disconnects; a task's port must be configured with `task.preview.port`, because automatic task-to-port discovery is refused. Private host-only preview requests fail explicitly; native signed preview URLs remain available. Public port discovery lists registered previews, not all listening sockets. Default workspace is prepared at `/project/sandbox`. Command restart preserves the originating client's captured argv, environment and working directory; a command discovered by another client refuses restart because its private spawn recipe is unavailable. |
-| Sprites     | No control-mode WebSocket protocol, managed services, provider health/upgrade, port watchers, URL role policy, filesystem checkpoint restoration in place, or full network/privilege/resource policy surfaces. Checkpoint operations fail explicitly because native snapshots also include memory. Session handles use native process IDs, not tmux. The sprite URL maps port 8080. File bytes and process byte streams preserve binary data.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Sprites     | No control-mode WebSocket protocol, managed services, in-place checkpoint restore (start a new sandbox from the snapshot), checkpoint history filters, network presets (`include`), an allow rule inside a denied wildcard (Runtime's deny always wins), privilege or resource policies, `maxRunAfterDisconnect`, Fly token exchange or Sprite list streaming; each is refused by name. A checkpoint is a Runtime disk snapshot (files, not running processes); the Sprite pauses for the moment it takes. An allow rule makes an allowlist, as Sprites' DNS allowlist does. The port watcher polls `ss` once a second. Session handles use native process IDs, not tmux. The sprite URL maps port 8080. File bytes and process byte streams preserve binary data.                                                                                                                                    |
 | Freestyle   | Provider catalog snapshot slugs are not Runtime snapshots and are refused. Firewall support is limited to an explicit empty rule set or the exact allow-public-outbound shape; arbitrary rule selectors, TLS policies and private networks are refused. No automatic-restart guarantee, retention scheduler, placement constraints, live resize, Linux-user switching, PTY namespace, public IPv6 or account-owned egress address emulation. Native snapshot retention is positive whole days.                                                                                                                                                                                                                                                                                                                                                                                                        |
 | Modal       | CPU sandboxes only; different resource reservation/limit values, fractional CPU, GPU and foreign placement are refused. Named Apps group Runtime sandboxes; they do not deploy Functions. Registry authentication uses Runtime's registry configuration. No Functions/Cls, volumes/bucket mounts, GPU image steps, readiness probes, sidecars, directory mounts, filesystem-only images from snapshots, or snapshot restoration API. Entry-point completion stops the sandbox while the originating client is alive; the native lease remains the bound if that client disappears. A different client can reconnect using the saved entrypoint process ID.                                                                                                                                                                                                                                            |
 | Cloudflare  | The conditional Worker entry supplies a Durable Object bridge and custom-hostname preview proxy; infrastructure configuration must still remove the vendor Container declaration and provide Runtime secrets. Custom preview routing is implemented but has no live public-hostname acceptance evidence. No isolated PID namespaces, interpreter contexts, bucket mounts, backup format, terminal WebSocket protocol, watchers/change versions, custom process IDs or provider cleanup-record semantics. Foreground named sessions use resident Bash; background processes inherit exported state/cwd but do not yet inherit every local variable/function/option.                                                                                                                                                                                                                                    |

package/DAYTONA.md

@@ -17,7 +17,8 @@ from withruntime.daytona import AsyncDaytona  # was: from daytona import AsyncDa
 ```
 
 The mapping was written against `@daytona/sdk` 0.220.0 and `daytona` 0.220.0
-on PyPI, and checked against `@daytona/sdk` 0.222.0 on 5 October 2026. The exact releases and artifact hashes
+on PyPI, and checked against `@daytona/sdk` and `daytona` 0.223.1 on
+9 October 2026 (below, "0.223.1"). The exact releases and artifact hashes
 are kept in `compatibility-lock.json`.
 
 ## Keys
@@ -65,7 +66,7 @@ package talks only to Runtime.
 | `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.                                                                                                                                                                                       |
+| `public: true`, `setPublic` (Python `set_public`)                             | `getPreviewLink(port)` shares the port publicly; without it, privately with a token. `setPublic` turns every port already shared public or private at once, at the same address.                                                                                           |
 | `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`.                                                              |
@@ -82,7 +83,7 @@ package talks only to Runtime.
 | `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.                                                                                                                                                |
+| `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. `mouse.down` and `up` hold and release a button; `scroll` goes up, down, left or right.                                                        |
 | `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`.                                                                                                                               |
@@ -94,14 +95,16 @@ Each of these throws `NotSupportedError` before anything happens. Its
 
 | Daytona                                                               | Use instead                                                                                                                                                                             |
 | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| A snapshot name with no Runtime image or snapshot                     | `daytona.snapshot.create({ name, image })` here, or `npx withruntime image build`. This throws `DaytonaNotFoundError`.                                                                  |
+| A snapshot name with no Runtime image or snapshot                     | `daytona.snapshot.create({ name, image })` here, or `npx withruntime images 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.                                                                                                                                   |
 | 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()`.                                                                                             |
+| `keyboard.down` and `up`, `modifiers` on a click, drag or scroll      | `keyboard.press(key, modifiers)` or `keyboard.hotkey("ctrl+shift+t")`: the keys pressed together at once.                                                                               |
+| `clicks` above 2                                                      | One click, or two with `double`; to select a line, click once and press shift+End.                                                                                                      |
 | `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>`.                                                                                               |
+| Signed preview URLs, signed upload and download URLs, SSH access      | `getPreviewLink`, `fs.uploadFile` and `downloadFile`, `npx withruntime sandboxes 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 })`.                                                                                                               |
@@ -123,6 +126,31 @@ Some differences are not refusals:
 - `autoArchiveInterval` is recorded only: Runtime has no archive tier.
 - Runtime's stock image is Ubuntu 24.04 with Python 3.12, Node.js 24 and Bun.
 
+## 0.223.1, 9 October 2026
+
+Reviewed the published npm tarballs for `@daytona/sdk`, `@daytona/api-client`,
+`@daytona/toolbox-api-client` and `@daytona/analytics-api-client` 0.223.0 →
+0.223.1, and the PyPI wheel and sdist for `daytona` 0.223.0 → 0.223.1. Each was
+its registry's latest when checked. Every pinned file matched the hash already
+in `compatibility-lock.json`, and every new file matched its registry's SHA-512
+integrity or SHA-256 digest; each wheel's Python source is byte for byte its
+sdist's. Nothing was installed, imported or run. The three API clients changed
+only their version. `@daytona/sdk` changed `Sandbox` and `Process` (ESM and
+CommonJS alike), and `daytona` the same two modules, sync and async.
+
+| Upstream change                                                                                                                                                                                     | Drop-in disposition                                                                                                                                                                                                                                                                     |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sandbox.setPublic(isPublic)` (Python `set_public(public, request_timeout=None)`) makes the sandbox's preview URLs public or private, and sets `sandbox.public`.                                    | Followed, in both languages. Every port already shared whose visibility differs is shared again with the new one, at the same address, and later `getPreviewLink` calls use it. Without credit Runtime refuses a public share (`public_preview_not_allowed`) and `public` is unchanged. |
+| `executeCommand` (Python `exec`) documents that commands run under zsh, bash or sh (zsh in Daytona's images), how to start a server in the background, and that `nproc` may report the host's CPUs. | Documentation only. The drop-in keeps running commands under bash, which is what Daytona's quoting advice is for; a sandbox's `nproc` reports its own vCPUs.                                                                                                                            |
+| `getPreviewLink` and `getSignedPreviewUrl` (Python `create_signed_preview_url`) document the token header, the API key as a bearer token, and a longer expiry.                                      | Documentation only. A Runtime private preview takes its token as `x-runtime-preview-token`; signed preview URLs stay refused, as above.                                                                                                                                                 |
+| `@daytona/sdk` requires `shell-quote` ^1.11.0, was ^1.8.2.                                                                                                                                          | The oracle's `bun.lock` already resolved 1.11.0.                                                                                                                                                                                                                                        |
+
+`tests/daytona/daytona-0-223-1.test.ts` and
+`sdks/python/tests/test_daytona_0_223_1.py` check `setPublic` both ways, that
+a public port is not shared again, and the refusal without credit; they fail
+without this change. The oracle was not run against the new release, since it
+executes Daytona's code; the provider remains marked `partial`.
+
 ## Tests
 
 `bun run test` in `packages/cloud-sdk` runs the unit tests of both languages

package/E2B.md

@@ -20,10 +20,10 @@ 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 checked against `e2b` 2.52.1
-and `@e2b/code-interpreter` 2.8.0 (Python: `e2b` 2.52.1, `e2b-code-interpreter`
-2.10.1) on 5 October 2026. The exact package releases and artifact hashes are kept in
-`compatibility-lock.json`.
+The mapping was written against `e2b` 2.51.0 and checked against `e2b` 2.55.0
+and `@e2b/code-interpreter` 2.8.3 on 9 October 2026. Python was checked
+against `e2b` 2.55.1 and `e2b-code-interpreter` 2.10.5 the same day. The exact
+package releases and artifact hashes are kept in `compatibility-lock.json`.
 
 ## Keys
 
@@ -96,10 +96,10 @@ account the key belongs to and where the key came from.
 | `metadata`                                                                               | labels (at most 32).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `envs`                                                                                   | Given to every command and code run through this object.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `allowInternetAccess: false`                                                             | `network: { internet: false }`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `lifecycle.onTimeout`                                                                    | `onTimeout`: `kill` is `delete`, `pause` is `pause`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `lifecycle.onTimeout`                                                                    | `onTimeout`: `kill` is `delete`, `pause` is `pause`; `{ action: "pause", mode: "full" }` 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. A command whose sandbox is killed under it ends with `TimeoutError` too, saying the sandbox was killed or reached its end of life.                                                                                                                                                                                                                                                                                                                                          |
+| Command past its timeout                                                                 | Disconnects with `TimeoutError` (Python: `TimeoutException`) without killing the command; reconnect by pid to keep reading. A JavaScript command whose sandbox is killed under it throws `SandboxNotRunningError`, a `TimeoutError`, saying the sandbox was killed or reached its end of life.                                                                                                                                                                                                                                                                                                          |
 | `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. `commands.list` shows each command as E2B starts it: `cmd` `/bin/bash`, `args` `["-l", "-c", "<your command>"]` (a PTY: `["-i", "-l"]`), the command cut at 256 characters, `envs` empty.                                                                                                                                                                                                                                                                                                                  |
@@ -116,7 +116,7 @@ account the key belongs to and where the key came from.
 | `sandbox.pause()`, `betaPause`, `Sandbox.pause(id)`                                      | `pause`, keeping memory and files. `false` when it was already paused.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `getInfo`, `isRunning`                                                                   | `get`. `templateId` is the template the sandbox was created from, as you named it (kept in the label `e2b-template`, which `metadata` leaves out), or `base`. `envdVersion` is `runtime`. A sandbox Runtime paused for being idle is `running`. `endAt` is when it ends by itself; one that never will (no time limit, as a pilot's) reads 24 hours ahead, the furthest E2B allows.                                                                                                                                                                                                                     |
 | `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `fork`, `createSnapshot`, `deleteSnapshot`                                               | Runtime's memory-preserving forks and snapshots; `createSnapshot({ mode: "filesystem" })` is a disk snapshot, from which a sandbox boots afresh. 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
@@ -130,23 +130,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(...)`                                                                                         |
-| `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.                               |
+| E2B                                                           | Use instead                                                                                                          |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| An E2B template name with no Runtime image of that name       | Build it: `npx withruntime images 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.                                                                                      |
+| A pause with `mode: "filesystem"` or `keepMemory: false`      | Runtime's pause keeps memory. For the files alone, `createSnapshot({ mode: "filesystem" })`.                         |
+| `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)`
@@ -199,3 +199,64 @@ RUNTIME_API_KEY=... python3 sdks/python/scripts/e2b_e2e.py        # the same cas
 
 Either one run with `--dry` sets up and shows the one-line change without
 creating anything.
+
+## JavaScript qualification, 6 October 2026
+
+Reviewed the published npm tarballs for `e2b` 2.52.1 → 2.53.1 and
+`@e2b/code-interpreter` 2.8.0 → 2.8.2. Both new versions were npm's latest
+when checked. All four downloaded tarballs matched their registry SHA-512
+integrities; the new values are in `compatibility-lock.json` and the oracle's
+`bun.lock`. No package code was executed during source review.
+
+Each package changed its manifest and six distribution files: CommonJS and
+ES-module JavaScript, their source maps, and both declaration formats. The
+source maps contain the TypeScript sources (no separate `src` directory ships);
+CommonJS and ES-module source contents match. Ten E2B source files and three
+interpreter source files changed. The changes and their dispositions:
+
+| Upstream change                                                                                                                                                                                                                                                                         | Drop-in disposition                                                                                                                                                                                                                                                                                                                                                                      |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SandboxNotRunningError` and `SandboxUnreachableError`, exported by E2B and re-exported by the interpreter; both extend `TimeoutError` and accept `ErrorOptions.cause`.                                                                                                                 | Mirrored: both imports, names, parents, constructor signatures and causes match. Runtime's explicit `sandbox_stopped`, `sandbox_paused` and `sandbox_not_running` codes select the first; `sandbox_not_ready` and `host_unavailable` select the second.                                                                                                                                  |
+| HTTP 502 and RPC Unavailable distinguish a stopped sandbox from an unreachable one. Failed connection and ambiguous stream errors use a health probe; browser network failures are recognized too. Process and watch startup no longer replace Unavailable with `SandboxNotFoundError`. | Mirrored through Runtime's explicit state codes, including command, file, watch and interpreter guards. A command losing its sandbox now throws `SandboxNotRunningError`. E2B's envd health probes, proxy message matching and RPC parsing are not copied: Runtime uses its own API. An unclassified connection failure does not establish sandbox state and retains its existing error. |
+| Streaming RPCs preserve a plain-text or JSON proxy 502 message; recognized Connect error codes retain their meaning. HTTP error-body extraction is shared with the health probe.                                                                                                        | Not mirrored: E2B's proxy and Connect transport are not used. Runtime's structured code, message, hint, request id and original cause remain available.                                                                                                                                                                                                                                  |
+| Removed `E2B_USER_AGENT_SOURCE`, `ConnectionConfig.requestSource`, user-agent source suffixes, automatic CI error logging and trace-id diagnostics. Logger middleware now returns the request and response.                                                                             | Not mirrored: Runtime never implemented those E2B transport diagnostics; `ConnectionConfig` and `ApiClient` remain unsupported.                                                                                                                                                                                                                                                          |
+| Create, connect and fork share a response mapper and a private response type; the protected return annotations allow optional transport fields.                                                                                                                                         | Not mirrored: this refactors E2B's transport response without changing public Sandbox behavior; Runtime builds its own sandbox objects.                                                                                                                                                                                                                                                  |
+| Interpreter errors include a nonempty trimmed response body for generic HTTP failures, without a CI-only switch or trace suffix; 404 and 502 retain their previous classes.                                                                                                             | Already preserves server explanations: Runtime translates its structured API errors, including the message, hint and request id. E2B's private Jupyter HTTP formatter and status-line wording are not used.                                                                                                                                                                              |
+| Interpreter request URLs no longer append the traffic-source query; private diagnostic helpers disappear from declarations.                                                                                                                                                             | Not mirrored: Runtime does not send requests to E2B's Jupyter endpoints or append that query.                                                                                                                                                                                                                                                                                            |
+| Interpreter streaming uses one UTF-8 decoder across chunks and flushes it at EOF.                                                                                                                                                                                                       | Already matched by Runtime's `TextDecoderStream`. A `runCode` test sends every byte separately, including two-, three- and four-byte characters and a final line without a newline; callbacks and final results retain the text.                                                                                                                                                         |
+| Interpreter dependency rises from `e2b ^2.48.0` to `^2.53.1`; package versions and build metadata advance.                                                                                                                                                                              | Oracle pins both exact releases. No other public exports, caller options, defaults or method signatures changed.                                                                                                                                                                                                                                                                         |
+
+`tests/e2b/exports.test.ts` checks both import surfaces, constructor causes and
+Runtime error translation. `tests/e2b/sandbox.test.ts` checks the error when a
+running command loses its sandbox. `tests/e2b/code-interpreter.test.ts` exercises
+the real native transport beneath `runCode` with in-memory HTTP replies, including
+split UTF-8 and server failures without replay. These fixtures do not establish
+live-host behavior, isolation, recovery, performance superiority or full E2B
+compatibility; the provider remains marked `partial`.
+
+## e2b 2.55.0, 9 October 2026
+
+Reviewed the published npm tarballs for `e2b` 2.53.1 → 2.55.0 and
+`@e2b/code-interpreter` 2.8.2 → 2.8.3, and the PyPI wheels and sdists for
+`e2b` 2.53.1 → 2.55.0 → 2.55.1 and `e2b-code-interpreter` 2.10.3 → 2.10.4 →
+2.10.5. Each was npm's or PyPI's latest when checked. Every pinned file matched
+the hash already in `compatibility-lock.json`, and every new file matched its
+registry's SHA-512 integrity or SHA-256 digest; each wheel's Python source is
+byte for byte its sdist's. Nothing was installed, imported or run. JavaScript
+sources were read from the source maps, which carry the TypeScript. Nine `e2b`
+source files changed, one was removed, and one interpreter file changed.
+
+| Upstream change                                                                                                                                                                                                                                                                                          | Drop-in disposition                                                                                                                                                                                                                                                                                                                                                                             |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pause`, `betaPause`, `createSnapshot` and `lifecycle.onTimeout` take `mode: "full" \| "filesystem"` (Python `mode=`, keyword-only); `keepMemory` (`keep_memory`) is deprecated. Both at once, an unknown mode, or a mode on `action: "kill"` throws `InvalidArgumentError`. `SnapshotMode` is exported. | Followed, in both languages. `createSnapshot({ mode: "filesystem" })` takes a Runtime disk snapshot and `"full"` the whole machine. A pause with `"filesystem"` throws `NotSupportedError`, as `keepMemory: false` did, naming the disk snapshot. `"full"` pauses. The same `InvalidArgumentError`s, with E2B's messages. Until now a `mode` was ignored: a pause asked to drop memory kept it. |
+| `DockerfileSyntaxError` is exported (from the new `@e2b/dockerfile-utils` / `e2b-dockerfile-utils` 0.1.0): a plain `Error` (Python `ValueError`) with `line`. The template builder's Dockerfile and `.dockerignore` parsing moves into that package, replacing `dockerfile-ast` / `dockerfile-parse`.    | Exported with E2B's parent, message and `line`, also from `e2b.template.dockerfile_parser`. Templates stay refused, naming `npx withruntime images build`, so nothing throws it.                                                                                                                                                                                                                |
+| Template `copy` and `makeDir` keep `mode: 0` instead of dropping it.                                                                                                                                                                                                                                     | Not mirrored: templates are refused.                                                                                                                                                                                                                                                                                                                                                            |
+| A file entry for a symlink is `FileType.SYMLINK` when newer envd reports the target's type with an `isSymlink` flag.                                                                                                                                                                                     | Already matched: Runtime's listing marks the link itself `symlink`.                                                                                                                                                                                                                                                                                                                             |
+| Python's command stream decodes empty output chunks instead of skipping them, still yielding only nonempty text. A JavaScript comment is removed.                                                                                                                                                        | No change in what a caller sees; Runtime's own stream is used.                                                                                                                                                                                                                                                                                                                                  |
+| The interpreter builds its Jupyter address with `getSandboxUrl` (Python `get_sandbox_url(port=)`, added in `e2b` 2.55.1) instead of a direct URL. Interpreter dependencies rise to `e2b ^2.55.0` (Python `>=2.55.1`).                                                                                    | Not mirrored: Runtime does not call E2B's Jupyter endpoints. The oracle and the Python contract requirements pin the exact releases, with `@e2b/dockerfile-utils` and `e2b-dockerfile-utils` 0.1.0 in place of the parsers.                                                                                                                                                                     |
+| API documentation: `team_id` may be a `prj_` project id; `secret_limit_reached` is a listed error code.                                                                                                                                                                                                  | Not used by the drop-in.                                                                                                                                                                                                                                                                                                                                                                        |
+
+`tests/e2b/e2b-2-55.test.ts` and `sdks/python/tests/test_e2b_2_55.py` check the
+modes, the refusals, their messages and the new exports; they fail without
+this change. The official differential contracts were not run against the new
+releases, since they execute E2B's code; the provider remains marked `partial`.

package/README.md

@@ -26,13 +26,14 @@ console.log(result.exitCode, result.stdout);
 ```
 
 `Sandbox.create()` needs no arguments and returns once the sandbox is running;
-`await using` stops it when the block ends (Node 24, Bun or TypeScript; on
-Node 22 call `await sbx.stop()`). With no arguments you get the
-included usage, a 1 GB machine running all month every month with no card (up to
-eight sandboxes running at once without credit), 2 vCPU, 4 GiB of
+`await using` deletes it when the block ends (Node 24, Bun or TypeScript; on
+Node 22 call `await sbx.delete()`), and `keep: true` stops it instead, keeping
+its disk. With no arguments you get the
+free usage, with no card (up to
+four sandboxes running at once without credit), 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).
-The included usage is spent first, then prepaid credit, with nothing to
+The free usage is spent first, then prepaid credit, with nothing to
 choose; `funding` is accepted and ignored.
 
 The sandbox object does the rest:
@@ -41,7 +42,7 @@ The sandbox object does the rest:
   work, with `cwd`, `env` (the place for secrets), `stdin` and `timeoutMs`;
 - `terminal()` for an interactive terminal over a WebSocket;
 - `forwardPort(5432)` to reach any TCP port in the sandbox from this machine, and
-  `tunnel()` for single connections and SSH logins (`runtime sandbox ssh` uses it);
+  `tunnel()` for single connections and SSH logins (`runtime sandboxes ssh` uses it);
 - `files` to read, write, list, glob, stat, move and remove, and to copy whole
   directories with `upload` and `download`;
 - `pause`, `wake`, `extend`, `fork` and `snapshot` (a paused sandbox also wakes
@@ -161,14 +162,14 @@ https://withruntime.com/docs/frameworks.
 
 ```bash no-run
 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 sandboxes run -- python3 - < invoice.py   # connects on first use
+npx withruntime sandboxes create
 npx withruntime help
 ```
 
 Installed with `npm i -g withruntime`, the command is `runtime`:
-`runtime sandbox exec <id> -- ls`, `runtime sandbox shell <id>`,
-`runtime image build --pip pandas`, and `--json` on every command.
+`runtime sandboxes exec <id> -- ls`, `runtime sandboxes shell <id>`,
+`runtime images build --pip pandas`, and `--json` on every command.
 
 ## MCP
 

package/README.src.md

@@ -28,13 +28,14 @@ console.log(result.exitCode, result.stdout);
 ```
 
 `Sandbox.create()` needs no arguments and returns once the sandbox is running;
-`await using` stops it when the block ends (Node 24, Bun or TypeScript; on
-Node 22 call `await sbx.stop()`). With no arguments you get the
-included usage, {{included-machine}} every month with no card (up to
+`await using` deletes it when the block ends (Node 24, Bun or TypeScript; on
+Node 22 call `await sbx.delete()`), and `keep: true` stops it instead, keeping
+its disk. With no arguments you get the
+free usage, with no card (up to
 {{trial-sandboxes}} sandboxes running at once without credit), 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).
-The included usage is spent first, then prepaid credit, with nothing to
+The free usage is spent first, then prepaid credit, with nothing to
 choose; `funding` is accepted and ignored.
 
 The sandbox object does the rest:
@@ -43,7 +44,7 @@ The sandbox object does the rest:
   work, with `cwd`, `env` (the place for secrets), `stdin` and `timeoutMs`;
 - `terminal()` for an interactive terminal over a WebSocket;
 - `forwardPort(5432)` to reach any TCP port in the sandbox from this machine, and
-  `tunnel()` for single connections and SSH logins (`runtime sandbox ssh` uses it);
+  `tunnel()` for single connections and SSH logins (`runtime sandboxes ssh` uses it);
 - `files` to read, write, list, glob, stat, move and remove, and to copy whole
   directories with `upload` and `download`;
 - `pause`, `wake`, `extend`, `fork` and `snapshot` (a paused sandbox also wakes
@@ -163,14 +164,14 @@ https://withruntime.com/docs/frameworks.
 
 ```bash no-run
 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 sandboxes run -- python3 - < invoice.py   # connects on first use
+npx withruntime sandboxes create
 npx withruntime help
 ```
 
 Installed with `npm i -g withruntime`, the command is `runtime`:
-`runtime sandbox exec <id> -- ls`, `runtime sandbox shell <id>`,
-`runtime image build --pip pandas`, and `--json` on every command.
+`runtime sandboxes exec <id> -- ls`, `runtime sandboxes shell <id>`,
+`runtime images build --pip pandas`, and `--json` on every command.
 
 ## MCP