withruntime 0.8.4 → 0.9.0

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/E2B.md

@@ -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,14 @@ 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.                                                                                                                                                                |
 | `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.                                                                                                                                     |
@@ -77,7 +78,7 @@ machine. An E2B key (`e2b_...`) is never sent anywhere. If one is passed as
 | `Sandbox.list({ query: { metadata, state }, limit })`                                    | `sandboxes.list` by labels and state, oldest first, with E2B's paginator (`hasNext`, `nextItems()`).                                                                                                                                                        |
 | `fork`, `createSnapshot`, `deleteSnapshot`                                               | Runtime's forks and snapshots. While Runtime has them switched off, they throw `NotSupportedError` with Runtime's own message.                                                                                                                              |
 | `getHost(port)`                                                                          | `<port>-<id>.runtimehost.com` at once, as E2B answers it, and the port is shared as a public Runtime preview beside the caller (the sync Python sandbox shares it before returning). `await sandbox.getPublicHost(port)` returns once the share has landed. |
-| `runCode(code, { language, context, onStdout, onStderr, onResult, onError, timeoutMs })` | Runtime's interpreter, Python 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.                                                                                             |
@@ -105,26 +106,35 @@ before anything happens. The error's `feature` names the gap and its
 | `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.
+
 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 and command creation honor `requestTimeoutMs`.
+  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

@@ -41,11 +41,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 +57,7 @@ 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`,
+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`,

package/README.src.md

@@ -43,11 +43,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 +59,7 @@ 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`,
+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`,

package/compatibility-lock.json

@@ -0,0 +1,281 @@
+{
+  "schemaVersion": 1,
+  "checkedAt": "2026-09-29",
+  "providers": [
+    {
+      "id": "e2b",
+      "status": "partial",
+      "upstreams": [
+        {
+          "registry": "npm",
+          "name": "e2b",
+          "version": "2.51.0",
+          "artifacts": {
+            "2.51.0": "sha512-P+50lx1nOYpgCFyE1xuz6JVN/TqJivMUiH7v+RW0CUSfb4+NCu8IkC5KruT2sNPgp6aexddQQ77+OZKGpZZJ+Q=="
+          }
+        },
+        {
+          "registry": "npm",
+          "name": "@e2b/code-interpreter",
+          "version": "2.8.0",
+          "artifacts": {
+            "2.8.0": "sha512-tWFi8IJYV3V6jOVfQ8V5PkzockrYP+ndWB/jKiJvRATTmNAy8+S/7S+iSh2Lb2Hrul869G2adRiN2xW8peJTig=="
+          }
+        },
+        {
+          "registry": "pypi",
+          "name": "e2b",
+          "version": "2.51.0",
+          "artifacts": {
+            "e2b-2.51.0-py3-none-any.whl": "sha256-951d0fd069f017e760b338a435bdb83589b4bfb9574fc5203a7f777e9cb994c2",
+            "e2b-2.51.0.tar.gz": "sha256-902ee861b30c8ec3e46e7f84db8c993f30695872c7b4490efaad1627ec6e08ba"
+          }
+        },
+        {
+          "registry": "pypi",
+          "name": "e2b-code-interpreter",
+          "version": "2.10.0",
+          "artifacts": {
+            "e2b_code_interpreter-2.10.0-py3-none-any.whl": "sha256-6ba776122086261875bc6033ef2dc42ac6b6e22cefdffdfd19d30e93bb09786f",
+            "e2b_code_interpreter-2.10.0.tar.gz": "sha256-57fb7f9b9ad99ebbdf407619786fdb84e31537c2fbc8358c394aa0f0cbc1af28"
+          }
+        }
+      ]
+    },
+    {
+      "id": "daytona",
+      "status": "partial",
+      "upstreams": [
+        {
+          "registry": "npm",
+          "name": "@daytona/sdk",
+          "version": "0.220.0",
+          "artifacts": {
+            "0.220.0": "sha512-PJio3vbDwRApzlsK6AGO7r4CHJcF9PI5DWuUW2yUnA2MVJSh/jotS0onKBv6boC5F+oboljTibUMxrwVPIrOlQ=="
+          }
+        },
+        {
+          "registry": "pypi",
+          "name": "daytona",
+          "version": "0.220.0",
+          "artifacts": {
+            "daytona-0.220.0-py3-none-any.whl": "sha256-5f71299eaf3a446e6569ada69919fc49997c1b2c587845057394aab886f113c8",
+            "daytona-0.220.0.tar.gz": "sha256-eda82eac9b3601e757b1dbe3ec2d966b46a9e3038b69ce44a0d90e01dac8417a"
+          }
+        },
+        {
+          "registry": "npm",
+          "name": "@daytona/api-client",
+          "version": "0.220.0",
+          "artifacts": {
+            "0.220.0": "sha512-XaMEtiQCaIHc3T7y3HUqx1A5eWSnd+FJvhpSHDwP3Snu9Nnhy4t+K2LHBWgJQn9dGtWXsdOsbB9K0BqpmFJtyA=="
+          }
+        },
+        {
+          "registry": "npm",
+          "name": "@daytona/toolbox-api-client",
+          "version": "0.220.0",
+          "artifacts": {
+            "0.220.0": "sha512-Kn94AOxhGQil0XygOOR26SaCkndE4dOtxYS0hLbqrTxcP3H1uq1HGFGSRkHFQNkaR8eL9QwFUPSMqd0Vr3A64A=="
+          }
+        },
+        {
+          "registry": "npm",
+          "name": "@daytona/analytics-api-client",
+          "version": "0.220.0",
+          "artifacts": {
+            "0.220.0": "sha512-3BGYILzjo2aFTJhLd6XBXlNEQBSo9Zr2Nj31OdX9o50fMRVUwVydF6ekIGkPGSLwskz6b6xxg5BSS+f9dbrxCQ=="
+          }
+        }
+      ]
+    },
+    {
+      "id": "vercel",
+      "status": "partial",
+      "upstreams": [
+        {
+          "registry": "npm",
+          "name": "@vercel/sandbox",
+          "version": "3.5.1",
+          "artifacts": {
+            "3.5.1": "sha512-VHItQtcv4FkSXET29b088p87MNPAIhRscF3ifrup2KkC8ix4hy4NpgCO9F3GI4yOsztgGtuV7bDx29Iufun2hQ=="
+          }
+        },
+        {
+          "registry": "pypi",
+          "name": "vercel",
+          "version": "0.11.4",
+          "artifacts": {
+            "vercel-0.11.4-py3-none-any.whl": "sha256-3ba3a0de2276a2b3daf590263082f6a82850dc77b35cf68f86a1e5bc9e83b6f1",
+            "vercel-0.11.4.tar.gz": "sha256-80038906615bf4182787af8354bce71b57d9fd5471a35ebca457d34ab5f50b2e"
+          }
+        },
+        {
+          "registry": "pypi",
+          "name": "vercel-sandbox",
+          "version": "0.7.0",
+          "artifacts": {
+            "vercel_sandbox-0.7.0-py3-none-any.whl": "sha256-f7eb897a1a5092fe8c38319ce803033b1a9ced8f414564a43a668432f91ffcd9",
+            "vercel_sandbox-0.7.0.tar.gz": "sha256-07d703790d0141dc75e0962baf35d666a6961bc1de913749137267a2550c81e2"
+          }
+        }
+      ]
+    },
+    {
+      "id": "blaxel",
+      "status": "partial",
+      "upstreams": [
+        {
+          "registry": "npm",
+          "name": "@blaxel/core",
+          "version": "0.3.24",
+          "artifacts": {
+            "0.3.24": "sha512-zF1S7vx+mYHDbK9F4FQbdobz3N+YIlNqHCyOC7R7QpbQ4nP9laeCuQRaN1OTfJVZcRwFvFQ5Nx1lh0su+esd7g=="
+          }
+        },
+        {
+          "registry": "pypi",
+          "name": "blaxel",
+          "version": "0.4.12",
+          "artifacts": {
+            "blaxel-0.4.12-py3-none-any.whl": "sha256-9ca08aa0c1c5aaac87055f684eae002365c55010eaa008d5dc36c552e153210a",
+            "blaxel-0.4.12.tar.gz": "sha256-58dc5c9aea5b21aa65538f811c7de0b24e8e7a411bdf64e374a295eb1b9cb15e"
+          }
+        }
+      ]
+    },
+    {
+      "id": "runloop",
+      "status": "partial",
+      "upstreams": [
+        {
+          "registry": "npm",
+          "name": "@runloop/api-client",
+          "version": "1.32.0",
+          "artifacts": {
+            "1.32.0": "sha512-aCNKjlGzLVEAFl8WA42LmgiYkdIkaocOlFK/cMGppijsM0AGS+1hkw/RxroQxyHlkIhjyRaqLv7m5ZNMGhks7Q=="
+          }
+        },
+        {
+          "registry": "pypi",
+          "name": "runloop-api-client",
+          "version": "1.32.0",
+          "artifacts": {
+            "runloop_api_client-1.32.0-py3-none-any.whl": "sha256-23c36910de7423f73aef91d4a963abea80a6b2f5b2df5bb8e439d788d5486cc7",
+            "runloop_api_client-1.32.0.tar.gz": "sha256-1f2077fb5a99b5ef30dbc1d96d47c1ca1d3f77895b9e186d985e47365fe85634"
+          }
+        }
+      ]
+    },
+    {
+      "id": "codesandbox",
+      "status": "partial",
+      "upstreams": [
+        {
+          "registry": "npm",
+          "name": "@codesandbox/sdk",
+          "version": "2.4.2",
+          "artifacts": {
+            "2.4.2": "sha512-pwz/+xNPLiCEvIYLxk2VJwiAFuy28V3J6FuO+xIB5U3AV/EylHlm77Lsi/WNYeXoSljIlaLLU7IemAjw3ojNfg=="
+          }
+        }
+      ]
+    },
+    {
+      "id": "sprites",
+      "status": "partial",
+      "upstreams": [
+        {
+          "registry": "npm",
+          "name": "@fly/sprites",
+          "version": "0.2.3",
+          "artifacts": {
+            "0.2.3": "sha512-LB3xmHpHLdVECTQej+Vyi/aFFTc/Otf8bZ8GwVe/Hhlx4kIFS0K+9O5B8ru8Llg+cEwvYmzyeV69vNZPpCt0fw=="
+          }
+        },
+        {
+          "registry": "pypi",
+          "name": "sprites-py",
+          "version": "0.7.1",
+          "artifacts": {
+            "sprites_py-0.7.1-py3-none-any.whl": "sha256-23774f8111c9a4fbb7007f8e305677734eb7616bebb6c668c394788399ff38a8",
+            "sprites_py-0.7.1.tar.gz": "sha256-c45596f3994376eb25dd7c4f988b3a6893dd8218502bacd7eedf2b20888d8456"
+          }
+        }
+      ]
+    },
+    {
+      "id": "freestyle",
+      "status": "partial",
+      "upstreams": [
+        {
+          "registry": "npm",
+          "name": "freestyle",
+          "version": "0.2.16",
+          "artifacts": {
+            "0.2.16": "sha512-8pC7lh/R2PDanbs9Noc1Q7YlPl8Be8hHaQA/rpwFmELrcLTUAuCuxpoZ1Xm+7fuxqhJqJzO83bTTeLcSUoJ9SA=="
+          }
+        }
+      ]
+    },
+    {
+      "id": "prime",
+      "status": "partial",
+      "upstreams": [
+        {
+          "registry": "pypi",
+          "name": "prime-sandboxes",
+          "version": "0.4.0",
+          "artifacts": {
+            "prime_sandboxes-0.4.0-py3-none-any.whl": "sha256-2a15263a30f3a3a27307c83701b92317af83ec8df0968e910100ccdb557cbb6b",
+            "prime_sandboxes-0.4.0.tar.gz": "sha256-a6934a5f5fce8342dbe9ade9816242e893ebf23b83a4fa5fda5b0ddbce651f27"
+          }
+        }
+      ]
+    },
+    {
+      "id": "modal",
+      "status": "partial",
+      "upstreams": [
+        {
+          "registry": "npm",
+          "name": "modal",
+          "version": "0.11.0",
+          "artifacts": {
+            "0.11.0": "sha512-Kvy2nejPkice2FI82p5e8TJrFDy0BaSYZjJVmvnTnu51bOH9Ok7IRtp8NavBQqMuXhbpbj6gRULwxsjNkweF6A=="
+          }
+        },
+        {
+          "registry": "pypi",
+          "name": "modal",
+          "version": "1.6.0",
+          "artifacts": {
+            "modal-1.6.0-py3-none-any.whl": "sha256-2f5981ba656570ad96379d29f0ddff876880708c84966024ce130e9e1794fa68",
+            "modal-1.6.0.tar.gz": "sha256-c5dd551b5e0a283f3c764476c0a4ebe5bdef1e4a69432fa27e1b1ad8ca5e0817"
+          }
+        }
+      ]
+    },
+    {
+      "id": "cloudflare",
+      "status": "partial",
+      "upstreams": [
+        {
+          "registry": "npm",
+          "name": "@cloudflare/sandbox",
+          "version": "0.12.10",
+          "artifacts": {
+            "0.12.10": "sha512-245s6xEdR1v0Jti0YYd8ORWcTG/f/ksjJfpubvnbky0KxFC/ZDOpbpNKdtyiRBYZqmJGtEncYW7Cwge47tDrpg=="
+          },
+          "unsupported": {
+            "version": "1.0.0",
+            "artifacts": {
+              "1.0.0": "sha512-+TZVuCey6OBDTvPLWisq4Ie7/R5Zy3zFyYOFCNRpdEIyQsKq3xwzpctonE43DfZ+wYZvvu6QYpR138PayDjF+A=="
+            },
+            "reason": "1.0 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; withruntime/cloudflare implements the 0.x API"
+          }
+        }
+      ]
+    }
+  ]
+}

package/dist/ai-harness/index.js

@@ -19,6 +19,7 @@
  * token. The key comes from RUNTIME_API_KEY or this machine's `runtime login`.
  * Needs `@ai-sdk/harness` 1.x beside this package. */
 import { HarnessCapabilityUnsupportedError, HarnessSandboxAuthenticationError, } from "@ai-sdk/harness";
+import { AI_HARNESS_COMMAND_TIMEOUT_MS } from "../api-defaults.js";
 import { Runtime } from "../client.js";
 import { AuthenticationError, NotFoundError, PermissionDeniedError, RuntimeError, } from "../errors.js";
 export const PROVIDER_ID = "runtime-sandbox";
@@ -27,7 +28,6 @@ export const PREVIEW_TOKEN_HEADER = "x-runtime-preview-token";
 const TOKEN_QUERY = "runtime_preview_token";
 const SESSION_NAME_PREFIX = "ai-harness-";
 const MAX_COMMAND_MS = 86_400_000;
-const DEFAULT_COMMAND_MS = 3_600_000;
 /** Exit codes for a command that ended without one, as coreutils `timeout` and SIGKILL give. */
 const TIMED_OUT_EXIT = 124;
 const KILLED_EXIT = 137;
@@ -161,7 +161,7 @@ export class RuntimeSandboxSession {
                 ? {}
                 : { cwd: this.#path(options.workingDirectory) }),
             ...(Object.keys(env).length ? { env } : {}),
-            timeoutMs: Math.min(MAX_COMMAND_MS, options.timeoutMs ?? this.settings.commandTimeoutMs ?? DEFAULT_COMMAND_MS),
+            timeoutMs: Math.min(MAX_COMMAND_MS, options.timeoutMs ?? this.settings.commandTimeoutMs ?? AI_HARNESS_COMMAND_TIMEOUT_MS),
         };
     }
     /** Runs `command` under `bash -c` and returns once it exits, with all of

package/dist/api-defaults.d.ts

@@ -0,0 +1,17 @@
+/** A server-side wait for a state (`GET /v1/sandboxes/{id}?waitFor=`). */
+export declare const WAIT_FOR_TIMEOUT_SECONDS = 60;
+/** A streamed exec's command limit when none is given: the API's longest. */
+export declare const STREAMED_EXEC_TIMEOUT_MS = 86400000;
+/** The lease keepAlive keeps ahead of now, and so the most it extends by. */
+export declare const KEEP_ALIVE_MARGIN_SECONDS = 600;
+/** A webhook watch runs until stopped. */
+export declare const WEBHOOK_WATCH_TIMEOUT_MS = 0;
+/** A job run's limit, and the time added to it for its sandbox to start. */
+export declare const JOB_TIMEOUT_SECONDS = 1800;
+export declare const JOB_START_SECONDS = 60;
+/** A command the framework-free tools run without a timeout of its own. */
+export declare const TOOL_EXEC_TIMEOUT_SECONDS = 300;
+/** A command the AI SDK harness runs without a timeout of its own. */
+export declare const AI_HARNESS_COMMAND_TIMEOUT_MS = 3600000;
+/** A command the OpenAI Agents sandbox runs without a timeout of its own. */
+export declare const OPENAI_AGENTS_EXEC_TIMEOUT_MS = 3600000;