withruntime 0.8.4 → 0.10.0

package/BLAXEL.md

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

package/COMPATIBILITY.md

@@ -0,0 +1,145 @@
+# Sandbox compatibility evidence
+
+The compatibility modules are **partial, version-pinned sandbox adapters**. Their
+exported methods translate to Runtime's native client. They are not replacements
+for every service in a competitor's SDK, and this document does not claim that
+all applications switch unchanged.
+
+The four established modules are documented in `E2B.md`, `DAYTONA.md`, `VERCEL.md`
+and `BLAXEL.md`. The six additional TypeScript modules below were checked against
+published package declarations downloaded on 29 September 2026. Prime Intellect
+publishes a Python sandbox SDK; Runtime does not invent a TypeScript drop-in
+interface for it. Python coverage is in the Python SDK's compatibility documents.
+
+The Cloudflare module implements the 0.x `@cloudflare/sandbox` API. Version 1.0.0,
+published 30 September 2026, is a different package: it removes `getSandbox`, the
+`Sandbox` class, `exec`, processes, sessions and preview proxying, and keeps only
+`Files`, `S3Mount` and `DirectoryBackup` for the caller's own Durable Object. The
+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 |
+
+## Authentication and resources
+
+Set `RUNTIME_API_KEY` or sign in with `runtime login`. An explicitly supplied
+Runtime key begins with `rtcloud_`. Vendor credentials supplied to a replaced
+constructor are discarded locally, never forwarded to Runtime. Every adapter
+also accepts an injected native `Runtime` client for testing or configured
+transports. The conditional Worker entry reads the `RUNTIME_API_KEY` Worker secret and optional
+`RUNTIME_API_URL`; a Durable Object binding is not a Runtime credential.
+
+CodeSandbox, Sprites and Freestyle request Runtime persistence to preserve their
+resource-lifetime intent. Persistent sandboxes require paid credit. Runloop enables persistence only when the caller
+explicitly suspends: native stop retains its disk and resume boots that disk afresh,
+without restoring old processes. Paid admission must succeed before stopping. An
+uncertain stop keeps persistence enabled so the caller can retry without discarding
+data. Lifecycle calls serialize within one client; competing opposite intents from
+different clients rely on native transition admission. Runtime
+admission, credit, disk and CPU limits remain authoritative; an adapter does not
+buy resources, override account limits or promise another provider's capacity.
+Supported explicit regions use Runtime's region names. Unsupported provider
+regions, GPU requests and fractional CPU shapes fail before allocation rather
+than silently receiving different hardware.
+
+Environment variables are stored in a sandbox-private file with mode 0600, not
+in resource labels. Reconnecting clients read the file; snapshots preserve it
+unless an explicit replacement environment is supplied. Python and TypeScript
+share the file path and `compat.provider` resource label.
+
+## Evidence that can be repeated locally
+
+Run `bun test tests/compat` from the SDK package and run `bun run check-types`.
+The test run compiles unchanged typed consumer bodies from
+`tests/compat/consumers/workflows.ts.txt` against all ten TypeScript adapters,
+including E2B's interpreter. Run
+`bun tests/compat/check-consumers.ts <verified-cache>` to compile the
+same bodies against the pinned upstream declarations; the script checks each
+package name and version against the lock before compiling. Both targets passed
+on 29 September 2026. Only import resolution changes between the two runs.
+
+The published-package behavior checks are also reproducible. Prepare the integrity-verified
+cache with the SDK's compatibility preparation command. Run
+`bun tests/compat/prepare-runtime.ts <verified-cache> <reference-directory>`;
+it copies published packages without modifying the cache, removes build-only development
+dependencies from copied manifests, and installs runtime dependencies with scripts disabled
+and the checked-in frozen `tests/compat/reference.bun.lock`. Then run
+`bun tests/compat/compare-upstream.ts <verified-cache> <reference-directory>` and
+`bun tests/compat/worker-local.ts <reference-directory>/node_modules/miniflare <reference-directory>`.
+
+| Published implementation executed      | Shared behavior compared                                                 | Instrument boundary                                                                                                             |
+| -------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| Sprites filesystem                     | Binary/text/JSON files, dotfiles, directory entries, missing-file errors | Controlled HTTP versus native API router and simulated guest                                                                    |
+| Freestyle filesystem                   | Blob/string writes, progress, byte ranges, streamed slices               | Controlled HTTP versus native API router and simulated guest                                                                    |
+| Runloop client                         | Create, text files, command results, shutdown                            | Controlled HTTP versus native API router and simulated guest                                                                    |
+| CodeSandbox client                     | Creation defaults, tags, metadata, hibernate/delete                      | Controlled HTTP; native metadata/lifecycle modeled because fixture has no orchestration database                                |
+| Modal client and Sandbox               | Tag replacement/clearing and terminate                                   | Published injected control-plane client; native metadata/lifecycle modeled                                                      |
+| Cloudflare getSandbox/session wrappers | ID validation, sessions, file calls, exec, process waits                 | Both run in pinned local workerd against Runtime's Durable Object and simulated guest; the official Container daemon is not run |
+
+All six comparisons passed locally on 29 September 2026. They establish the stated
+client behavior with controlled responses, not equivalence of hosted vendor services.
+
+The new adapter contract tests drive Runtime's actual API router, request
+validation and response schemas with a simulated guest. They exercise:
+
+- Command failures and asynchronous execution output.
+- Reconnection with retained environment and unchanged dotfile paths.
+- Binary file transfers larger than the native single-request limit.
+- Large append staging and cleanup.
+- Refusal of unsupported resource options before allocation.
+- Failed initialization cleanup, including a second failure during cleanup.
+- Preserving a snapshot's environment when no override was given.
+- Never forwarding vendor credentials to Runtime.
+- Stopping paused persistent sandboxes before releasing their disk, including a
+  pause racing a client's cached state, without waking them.
+- Named-shell environment and working-directory persistence in real local Bash,
+  nonzero exits, variable-name collisions, and explicit per-call overrides. The resident
+  broker also exercises function/alias/option persistence, return/exit/exec, concurrent
+  calls, cancellation, overridden printf and an invalid command PATH.
+- Cloudflare session callbacks/files/process waits and Modal process streams,
+  stdin, files and entrypoint completion. These two tests replace create/image
+  orchestration because the simulated-guest fixture has no database/image builder.
+
+The optional `tests/compat/live.ts` runner requires `--run`, an explicit Runtime
+key, and at least one remaining trial hour. It allocates at most six resources,
+forces trial funding and short leases, records every created ID, and attempts
+cleanup for all IDs even after a failure. It does not build images, create
+snapshots or expose public previews. Its explicit persistence override makes it
+an execution/file smoke test, not evidence of paid persistent lifetime behavior.
+
+Local tests do not prove cross-host durability, Linux isolation, vendor runtime
+image equivalence, public Worker hosting, or performance against a competitor.
+The measured results of live acceptance belong in its run report.
+
+## Exact boundaries of this version
+
+These boundaries describe present behavior, rather than a second worklist.
+Remaining implementation work is tracked only in the repository `WORKLIST.md`.
+
+| Provider    | Boundary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| 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.                                                                                                                                                                                                                                    |
+
+## Keeping compatibility current
+
+`compatibility-lock.json` records the inspected versions and package integrity.
+The repository's upstream check detects new releases and changed package contents.
+A deprecated npm package or yanked Python release also requires review; a
+registry failure cannot count as a pass. The daily workflow is source-controlled
+but does not run until pushed to a repository with working GitHub Actions.
+A changed pin is evidence to review, not permission to announce compatibility:
+compare the published declarations, replay the relevant unchanged consumer,
+exercise its failure paths, and update this coverage table with the same change.

package/DAYTONA.md

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

package/E2B.md

@@ -1,7 +1,7 @@
 # Code written for E2B, on Runtime
 
-Run code written for [E2B](https://e2b.dev)'s SDK on Runtime Cloud by changing
-one import. It is part of Runtime's SDK (`withruntime`), built on the same
+Supported sandbox calls from [E2B](https://e2b.dev)'s SDK keep their call
+shapes on Runtime Cloud after changing the import. It is part of Runtime's SDK (`withruntime`), built on the same
 client, so it gets that SDK's retries, idempotency keys and errors. Importing
 `withruntime` alone does not load it.
 
@@ -22,7 +22,8 @@ from withruntime.e2b.code_interpreter import Sandbox  # was: from e2b_code_inter
 
 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
-23 September 2026.
+29 September 2026. The exact package releases and artifact hashes are kept in
+`compatibility-lock.json`.
 
 ## Keys
 
@@ -58,14 +59,15 @@ machine. An E2B key (`e2b_...`) is never sent anywhere. If one is passed as
 | `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 })`                        | `exec`, streamed, so the whole output comes back however large; output lost before it was read sets `truncated` and warns. Default timeout 60 s. `0` means no limit (Runtime's longest, 24 hours).                                                          |
+| `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                                                                 | Throws `TimeoutError`.                                                                                                                                                                                                                                      |
+| Command past its timeout                                                                 | Disconnects with `TimeoutError` (Python: `TimeoutException`) without killing the command; reconnect by pid to keep reading.                                                                                                                                 |
 | `commands.run(cmd, { background: true })`                                                | `spawn`. Returns a `CommandHandle` with `pid`, `wait()`, `kill()` (SIGKILL), `sendStdin`, `closeStdin`, `disconnect`, `stdout`, `stderr`, `exitCode`.                                                                                                       |
 | `commands.list`, `kill(pid)`, `sendStdin(pid)`, `closeStdin(pid)`, `connect(pid)`        | Runtime's processes. A pid is a number derived from Runtime's process id, not the Linux pid.                                                                                                                                                                |
+| `pty.create`, `connect`, `sendInput`, `resize`, `kill` (Python snake_case)               | Native PTY processes with lossless byte callbacks. A reader timeout or disconnect detaches without killing the process; reconnect resumes reading.                                                                                                          |
 | `files.read(path, { format })`                                                           | `files.read`. `text`, `bytes`, `blob` and `stream` (Python: `text`, `bytes`, `stream`).                                                                                                                                                                     |
 | `files.write(path, data)`, `write([...])`, `writeFiles`                                  | `files.write`. Parent directories are made, and a file that exists is replaced.                                                                                                                                                                             |
-| `files.list(path, { depth })`                                                            | `files.list`, hidden files included. `owner` and `group` are always `""`.                                                                                                                                                                                   |
+| `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.                                                                                                                                     |
@@ -75,12 +77,12 @@ machine. An E2B key (`e2b_...`) is never sent anywhere. If one is passed as
 | `sandbox.pause()`, `betaPause`, `Sandbox.pause(id)`                                      | `pause`, keeping memory and files. `false` when it was already paused.                                                                                                                                                                                      |
 | `getInfo`, `isRunning`                                                                   | `get`. `templateId` is `base` or the image or snapshot id. `envdVersion` is `runtime`.                                                                                                                                                                      |
 | `Sandbox.list({ query: { metadata, state }, limit })`                                    | `sandboxes.list` by labels and state, oldest first, with E2B's paginator (`hasNext`, `nextItems()`).                                                                                                                                                        |
-| `fork`, `createSnapshot`, `deleteSnapshot`                                               | Runtime's forks and snapshots. While Runtime has them switched off, they throw `NotSupportedError` with Runtime's own message.                                                                                                                              |
+| `fork`, `createSnapshot`, `deleteSnapshot`                                               | Runtime's memory-preserving forks and snapshots; deleting a snapshot removes that saved capture.                                                                                                                                                            |
 | `getHost(port)`                                                                          | `<port>-<id>.runtimehost.com` at once, as E2B answers it, and the port is shared as a public Runtime preview beside the caller (the sync Python sandbox shares it before returning). `await sandbox.getPublicHost(port)` returns once the share has landed. |
-| `runCode(code, { language, context, onStdout, onStderr, onResult, onError, timeoutMs })` | Runtime's interpreter, Python and JavaScript. The sandbox's `envs` reach code through a context made once for them. `onResult` is called after the run ends.                                                                                                |
+| `runCode(code, { language, context, onStdout, onStderr, onResult, onError, timeoutMs })` | Runtime's interpreter: Python, JavaScript, TypeScript, R, Java and Bash, plus Go. The sandbox's `envs` reach code through a context made once for them. `onResult` streams each result and waits for asynchronous callbacks.                                |
 | `Execution`, `Result`, `Logs`, `ExecutionError`, `OutputMessage`                         | The same shapes. Results that are too large to send inline are fetched and inlined. `logs.stdout` has one entry per line.                                                                                                                                   |
 | `createCodeContext`, `listCodeContexts`, `restartCodeContext`, `removeCodeContext`       | Runtime's interpreter contexts.                                                                                                                                                                                                                             |
-| `getMetrics({ start, end })`, `Sandbox.getMetrics(id)`                                   | Runtime's measured CPU and memory, one entry per host reading (every minute by default). `diskUsed` is null: Runtime does not read disk use inside the sandbox.                                                                                             |
+| `getMetrics({ start, end })`, `Sandbox.getMetrics(id)`                                   | Runtime's measured CPU and memory, one entry per host reading. `diskUsed` is null: Runtime does not read disk use inside the sandbox.                                                                                                                       |
 | Error classes                                                                            | E2B's names and parents. Each also carries Runtime's `code`, `hint` and `requestId`, with the original error as `cause`.                                                                                                                                    |
 
 ## Gaps
@@ -103,28 +105,40 @@ before anything happens. The error's `feature` names the gap and its
 | `mcp`, `getMcpUrl`, `getMcpToken`                                                            | Runtime's own MCP server, `npx withruntime mcp`.                                                                    |
 | `iam`, `Secret`                                                                              | A Runtime secret (`npx withruntime secrets set NAME --host <host>`): the sandbox sees a placeholder.                |
 | `volumeMounts`, `Volume`                                                                     | Runtime volumes: `runtime: { create: { volumes: [{ volumeId, path }] } }`.                                          |
-| `pty`                                                                                        | `sandbox.runtime.terminal(...)`.                                                                                    |
 | `git`                                                                                        | `commands.run("git ...")`. E2B has deprecated its git module too.                                                   |
-| `files.watchDir`                                                                             | Poll with `files.list`.                                                                                             |
 | 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` in `bash`, `r`, `java` or `typescript`                                             | `commands.run(...)`.                                                                                                |
 | `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)`
+returns a handle with `get_new_events()` and `stop()`; asynchronous
+`watch_dir(path, on_event, on_exit=...)` delivers callbacks. Stop is safe inside
+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.
-  E2B's code interpreter template preinstalls data libraries such as pandas and
-  matplotlib, and Runtime's image does not. Install them with `pip install`, or
-  build them into an image. Results never carry `chart`. A DataFrame arrives in
+  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`.
-- `requestTimeoutMs`, `retries`, `logger`, `secure` and `validateApiKey` are
-  accepted and ignored. Runtime's SDK sets its own request deadlines and
-  retries.
+- JavaScript file operations, command creation and reads, stdin/EOF, lookup, kill and reconnect honor `requestTimeoutMs` and `signal`.
+  Python file `request_timeout` bounds the request, including streamed reads. `retries`, `logger`, `secure` and `validateApiKey` are
+  accepted without changing the native transport settings.
+- Interpreter deadlines follow the pinned packages: JavaScript defaults to
+  sixty seconds and Python to five minutes; zero disables the read deadline.
+  A client timeout detaches the reader without interrupting the cell. The
+  sandbox lease still applies.
 
 ## Tests
 

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:
 
@@ -41,11 +44,14 @@ The sandbox object does the rest:
 - `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
-  by itself on the next call), `update` for its name, automatic wake, idle pause
-  and persistence, and `keepAlive` to extend its lease while your process runs;
+  by itself on the next call), `update` for its name, environment, automatic
+  wake, idle pause and persistence, `keepAlive` to extend its lease while your
+  process runs, `switchImage` to move it to a new image keeping /workspace,
+  and `delete` to remove it for good;
 - `interpreter`, `network`, `previews`, `desktop`, `mounts` (your S3, R2 or
-  Google Cloud Storage bucket as a folder), `metrics` and `mcp` (servers from
-  the MCP catalog, run in the sandbox) for the other products.
+  Google Cloud Storage bucket as a folder), `tailscale` (a paid sandbox on your
+  own tailnet), `metrics` and `mcp` (servers from the MCP catalog, run in the
+  sandbox) for the other products.
 
 A sandbox pauses itself after 60 seconds with nothing happening in it, keeping
 its memory and processes, and the next call wakes it, so an idle sandbox costs
@@ -54,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`, `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`,
@@ -62,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
 
@@ -84,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:
@@ -118,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
@@ -129,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.
@@ -149,7 +159,8 @@ https://withruntime.com/docs/frameworks.
 ## CLI
 
 ```bash no-run
-npx withruntime sandbox run -- python3 -c 'print(6 * 7)'   # connects on first use
+printf '%s\n' 'print(sum([125, 250, 375]))' > invoice.py
+npx withruntime sandbox run -- python3 - < invoice.py   # connects on first use
 npx withruntime sandbox create
 npx withruntime help
 ```

package/README.src.md

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