aron-cf · Oct 15, 2026 · Oct 15, 2026 · Oct 15, 2026 · Oct 15, 2026 · Oct 15, 2026
diff --git a/.changeset/stable-status.md b/.changeset/stable-status.md
@@ -0,0 +1,5 @@
+---
+"@cloudflare/computer": patch
+---
+
+`Workspace`, its filesystem, the worker-javascript backend, mounts, agent tools, Git, Assets, and Artifacts are now stable; `LegacyContainerBackend` is deprecated in favor of `ContainerBackend`; the container and worker-shell backends, `ws:container`, sync, and `computerd` stay experimental.
diff --git a/.github/SECURITY.md b/.github/SECURITY.md
@@ -1,7 +1,35 @@
 # Security Policy
 
 > [!IMPORTANT]
-> Cloudflare Computer is in an early preview/experimental state and is under active, rapid development.
-> Please treat any deployment as experimental and do not rely on it for production security guarantees.
-> 
-> Reporting a security issue: If you find what you believe to be a security issue, please open a GitHub issue in this repository describing it. 
+> Most of Cloudflare Computer is stable, meaning suitable for production use. The parts listed below are experimental or deprecated. Do not rely on them for production security guarantees. The [status table](../packages/computer/README.md#status) describes the same split by API.
+>
+> Reporting a security issue: If you find what you believe to be a security issue, please open a GitHub issue in this repository describing it.
+
+## Experimental code
+
+These directories and files hold experimental code:
+
+- `packages/computerd/`: the `computerd` daemon and its FUSE mount.
+- `packages/computer-computerd-linux-x64/`: the `computerd` container image.
+- `packages/rpc/`: the RPC wire protocol between the durable object and `computerd`.
+- `packages/computer/src/backends/container/`: the container backend.
+- `packages/computer/src/backends/worker-shell/`: the Worker shell backend and its shell command groups.
+- `packages/computer/src/modules/container.ts`: the `ws:container` host module.
+- `packages/dofs/src/sync/`: the sync protocol building blocks.
+- `packages/dofs/src/schema/sync.ts`: the tables that hold sync state.
+
+`workspace.push()` and `workspace.pull()` in `packages/computer/src/workspace.ts` drive the sync with `computerd`, so they are experimental too, even though the rest of that file is stable.
+
+## Deprecated code
+
+These directories hold deprecated code, which will be removed in a future release:
+
+- `packages/computer/src/backends/container-legacy/`: the legacy container backend. Use `packages/computer/src/backends/container/` instead.
+
+## Code that is not shipped
+
+These directories are not part of any published package, so they carry no stability or security guarantees:
+
+- `examples/`: example Workers. Each example's README says which experimental parts it uses.
+- `script/`: maintenance scripts and test harnesses.
+- `packages/computer/test-harness/`, `packages/computer/src/test-harness/`, `packages/computer/tests/`, and `packages/computer/test-helpers/`: test code.
diff --git a/README.md b/README.md
@@ -26,11 +26,10 @@ Workspace can also be constructed without a backend at all, giving
 callers the filesystem on its own.
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
->
-> Suitable for experiments, exploration and prototypes. It is NOT suitable
-> for production use at this time.
+> The `@cloudflare/computer` package should be considered suitable for
+> production use. The package contains work-in-progress and experimental
+> components such as the `ContainerBackend`. These should be considered
+> unsuitable for production use. See the [status reference](packages/computer/README.md#status) for more details.
 >
 > The specification under [`docs/`](docs/) is forward-looking — read it for
 > intent, not as description of the code today.
@@ -58,7 +57,8 @@ public surface. Each is a Worker workspace with its own README.
   `scheduling_policy: "durable_object"` moves both out of the config.
 - [`examples/container-legacy`](examples/container-legacy) — the same
   surface against a container the platform schedules and sizes from the
-  `containers` block.
+  `containers` block. Uses the deprecated legacy container backend; new
+  code should follow `examples/container`.
 - [`examples/worker-shell`](examples/worker-shell) — same HTTP surface as the
   container example, but the shell runs [just-bash](https://github.com/vercel-labs/just-bash)
   in a Dynamic Worker loaded through `env.LOADER`. No container.
@@ -111,18 +111,24 @@ package-specific status and usage notes.
 - [`packages/dofs`](packages/dofs/README.md) (`@cloudflare/dofs`) —
   Durable Object SQLite-backed virtual filesystem, sync protocol
   building blocks, and a `@platformatic/vfs` provider for Node.
+  Stable, except the sync protocol building blocks.
 - [`packages/rpc`](packages/rpc/README.md)
   (`@cloudflare/computer-rpc`) — capnweb wire types and
   server/client helpers shared between the Durable Object and `computerd`.
+  Experimental.
 - [`packages/computerd`](packages/computerd/README.md)
   (`@cloudflare/computerd`) — the `computerd` daemon: a FUSE mount plus
   HTTP/WebSocket RPC server that runs inside the sandbox container.
+  Experimental.
 - [`packages/computer`](packages/computer/README.md)
   (`@cloudflare/computer`) — the top-level Computer package
-  consumed by Durable Objects. Work in progress.
+  consumed by Durable Objects. Stable, except the container and Worker
+  shell backends and the pieces listed as experimental in its
+  [status table](packages/computer/README.md#status).
 - [`packages/computer-computerd-linux-x64`](packages/computer-computerd-linux-x64/README.md)
   — private Docker image context for the prebuilt `computerd` linux-x64
   binary. The image, not an npm package, is the release artifact.
+  Experimental.
 
 ## Performance
 

diff --git a/docs/02_sync_protocol.md b/docs/02_sync_protocol.md
@@ -1,5 +1,10 @@
 # 02. Sync Protocol
 
+> [!WARNING]
+> **Experimental.** The sync protocol between the durable object and `computerd` may change in any release and
+> is not yet suitable for production use. See the
+> [status table](../packages/computer/README.md#status).
+
 > [!NOTE]
 > This document tracks the shipped wire shape in `packages/dofs/src/sync/*`
 > and `packages/rpc/src/{interface,server,sync-driver}.ts`. A handful of

diff --git a/docs/07_injected_service.md b/docs/07_injected_service.md
@@ -1,5 +1,10 @@
 # 07. Injected Service
 
+> [!WARNING]
+> **Experimental.** `computerd` and the container backend may change in any release and
+> is not yet suitable for production use. See the
+> [status table](../packages/computer/README.md#status).
+
 > [!NOTE]
 > This doc now reflects shipped code in `packages/computerd/` and
 > `packages/computer/src/backends/`. Items marked **(planned)** are
@@ -127,7 +132,8 @@ an `images` map. Each launch selects an image from
 pass options such as `entrypoint`, `labels`, and snapshot settings to
 `container.start()`.
 
-`LegacyContainerBackend` works with containers that the platform schedules.
+`LegacyContainerBackend` is deprecated; use `ContainerBackend` for new
+code. It works with containers that the platform schedules.
 The containers block chooses the image and instance size, so this backend
 passes only the environment and internet setting when it starts the
 container.

diff --git a/docs/08_capnweb_interface.md b/docs/08_capnweb_interface.md
@@ -1,5 +1,10 @@
 # 08. Capnweb Interface
 
+> [!WARNING]
+> **Experimental.** The capnweb wire protocol and `@cloudflare/computer-rpc` may change in any release and
+> is not yet suitable for production use. See the
+> [status table](../packages/computer/README.md#status).
+
 > [!NOTE]
 > This doc now reflects shipped code in `packages/rpc/`. Items marked
 > **(planned)** are deferred work.

diff --git a/docs/12_worker_backend.md b/docs/12_worker_backend.md
@@ -1,5 +1,10 @@
 # 12. Worker backend
 
+> [!WARNING]
+> **Experimental.** The Worker shell backend (`WorkerShellBackend`) may change in any release and
+> is not yet suitable for production use. See the
+> [status table](../packages/computer/README.md#status).
+
 > [!NOTE]
 > This doc reflects shipped code in
 > `packages/computer/src/backends/worker-shell/`. The example deployment
@@ -25,9 +30,10 @@ import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";
 The primary container backend (`@cloudflare/computer/backends/container`)
 gives you a real Linux environment with arbitrary binaries on `$PATH`,
 optional network access, and a full POSIX filesystem. It costs a container
-per session and a real roundtrip on every filesystem operation. Use
-`@cloudflare/computer/backends/container-legacy` instead when the platform
-schedules and sizes the container.
+per session and a real roundtrip on every filesystem operation. The
+deprecated `@cloudflare/computer/backends/container-legacy` serves
+containers the platform schedules and sizes; new code should use the
+primary container backend.
 
 The worker backend trades the real environment for a Workers
 isolate that boots instantly, scales out cheaply, and has no

diff --git a/docs/17_isolate_javascript.md b/docs/17_isolate_javascript.md
@@ -1,5 +1,10 @@
 # Isolate JavaScript runtime
 
+> [!NOTE]
+> **Stable.** `WorkerJavaScriptBackend` and its host modules are
+> suitable for production use, except `ws:container`, which runs on the
+> experimental container backend. See the [status table](../packages/computer/README.md#status).
+
 `WorkerJavaScriptBackend` runs an ECMAScript module in a fresh Cloudflare Dynamic Worker:
 
 ```ts
@@ -178,7 +183,7 @@ An import that is not built in, configured, one of the allowed Node.js modules,
 
 The allowed Node.js modules are the ones that work entirely inside the isolate: `node:path`, `node:url`, `node:util`, `node:events`, `node:buffer`, `node:assert`, `node:string_decoder`, `node:querystring`, `node:stream`, `node:crypto`, `node:zlib`, `node:timers`, `node:async_hooks`, and `node:diagnostics_channel`, with their subpaths such as `node:path/posix` and `node:timers/promises`. The runtime provides them, and imports of them are left as written. A bare name such as `path` works too and becomes `node:path`, unless a configured module has that name, in which case the configured module wins. The runtime has more Node.js modules, but they either duplicate what the Workspace provides, as `node:fs` does, reach outside the isolate, or are stubs that throw when called, so they stay unavailable.
 
-Any import that is not a path is resolved by name. The Worker Loader has no `node_modules` lookup and resolves a bare import next to the importing file, so Workspace stores each source and host module once, in a `__modules__` directory of the Worker's bundle, and rewrites every import of one into a relative path to it. Every file that imports `lodash` gets the same instance, however many directories the code spans. An absolute import is rewritten the same way. Relative paths are the only form the Worker Loader's legacy and new module registries resolve alike, so imports work whether or not `compatibilityFlags` includes `new_module_registry`. When a module fails to link, the error names it as the code wrote it.
+Any import that is not a path is resolved by name. The Worker Loader has no `node_modules` lookup and resolves a bare import next to the importing file, so Workspace stores each source and host module once, in a `__modules__` directory of the Worker's bundle, and rewrites every import of one into a relative path to it. Every file that imports `lodash` gets the same instance, however many directories the code spans. An absolute import is rewritten the same way. Relative paths are the only form the Worker Loader's legacy and new module registries resolve alike, so imports work whether or not `compatibilityFlags` includes `new_module_registry`. The Workers runtime still treats `new_module_registry` as experimental, so a Worker that adds it also needs the `experimental` compatibility flag; the default settings need neither. When a module fails to link, the error names it as the code wrote it.
 
 The backend describes its modules for a model in `backend.description`, which `workspace.runtime.backends()` returns and the `exec` tool shows. It is built from the same `modules` option the backend runs with, so it always matches what is installed:
 

diff --git a/docs/README.md b/docs/README.md
@@ -1,11 +1,10 @@
 # `@cloudflare/computer`
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
->
-> Suitable for experiments, exploration and prototypes. It is NOT suitable
-> for production use at this time.
+> The `@cloudflare/computer` package should be considered suitable for
+> production use. The package contains work-in-progress and experimental
+> components such as the `ContainerBackend`. These should be considered
+> unsuitable for production use. See the [status reference](../packages/computer/README.md#status) for more details.
 >
 > The specification in this directory is forward-looking — read it for
 > intent, not as description of the code today.
@@ -44,7 +43,7 @@ The package ships several entrypoints:
 | --- | --- |
 | `@cloudflare/computer` | The Workspace wrapper, first-class `workspace.runtime`, stub types, the R2 and Worker bundle mounts, and proxy classes. |
 | `@cloudflare/computer/backends/container` | `ContainerBackend` and `withWorkspaceContainer`, for a container the durable object schedules (`scheduling_policy: "durable_object"`). Same sync plumbing; the launch names the image and the instance size. |
-| `@cloudflare/computer/backends/container-legacy` | `LegacyContainerBackend` and `withLegacyWorkspaceContainer`, for a container the platform schedules and sizes from the containers block. |
+| `@cloudflare/computer/backends/container-legacy` | Deprecated; use `@cloudflare/computer/backends/container`. `LegacyContainerBackend` and `withLegacyWorkspaceContainer`, for a container the platform schedules and sizes from the containers block. |
 | `@cloudflare/computer/backends/worker-shell` | `WorkerShellBackend` and the bundled just-bash command runtime. |
 | `@cloudflare/computer/backends/worker-javascript` | `WorkerJavaScriptBackend`, configured libraries, durable relative imports, `node:fs/promises`, and host modules. |
 | `@cloudflare/computer/git` | Opt-in isomorphic-git glue for working with checkouts inside the workspace. Bundled lazily, with `pako` replaced by Workers `node:zlib`, and kept out of the default `@cloudflare/computer` graph. |
@@ -238,27 +237,31 @@ events.addEventListener("exit",   (e) => { console.log("exit", JSON.parse(e.data
 This package is documented as a set of focused topics. Start with the overview
 above, then dive into the area you're working on.
 
-| Document | Topic |
-| --- | --- |
-| [01. VFS](./01_vfs.md) | Layout of the workspace tree, reserved paths, and mount points. |
-| [02. Sync Protocol](./02_sync_protocol.md) | How the DO-backed VFS synchronises with the sandbox container. |
-| [03. Filesystem Schema](./03_filesystem_schema.md) | SQLite schema backing the virtual filesystem. |
-| [04. Filesystem Interface](./04_filesystem_interface.md) | `Workspace.fs` API: `readFile`, `writeFile`, `mkdir`, `grep`, etc. |
-| [05. Runtime Interface](./05_runtime_interface.md) | `Workspace.runtime.exec/getExec/killExec/disposeExec` and backend routing. |
-| [06. Mount Interface](./06_mount_interface.md) | Pre-filling paths from R2, Artifacts, GitHub, and custom sources. **(not yet implemented)** |
-| [07. Injected Service](./07_injected_service.md) | The in-container `computerd` service that backs FUSE and shell. |
-| [08. Capnweb Interface](./08_capnweb_interface.md) | RPC wire protocol between the DO and the sandbox. |
-| [09. Tool Interface (Agents)](./09_tool_interface.md) | Ready-made AI SDK tools for `@cloudflare/agents`. |
-| [10. Project Layout](./10_project_layout.md) | Source tree of this package and how the pieces fit together. |
-| [11. Lifecycle](./11_lifecycle.md) | DO incarnations, container lifetime, capnweb session lifecycle, and hibernation. |
-| [12. Worker backend](./12_worker_backend.md) | Running the shell as just-bash inside a Dynamic Worker loaded through `env.LOADER`. |
-| [13. Git interface](./13_git_interface.md) | `workspace.git` and the `git` CLI inside the shell, backed by isomorphic-git. |
-| [14. Assets interface](./14_assets_interface.md) | `share` a workspace file to R2 and get back a presigned URL. |
-| [15. Artifacts interface](./15_artifacts_interface.md) | `createArtifact` and the `artifacts` CLI, an optionally session-scoped wrapper over the Cloudflare Artifacts binding. |
-| [16. Execution runtime architecture](./16_code_execution.md) | One runtime entry point over command and module backends. |
-| [17. Isolate JavaScript runtime](./17_isolate_javascript.md) | ECMAScript modules, durable imports, configured libraries, durable `node:fs/promises`, host modules, and managed lifecycle. |
-| [18. Runtime migration](./18_runtime_migration.md) | Breaking preview-API mappings from public shell and script-execution surfaces to `workspace.runtime`. |
-| [19. Performance](./19_performance.md) | Filesystem benchmarks: `fs-bench` numbers, an `npm install` comparison, and how to reproduce them. |
+The status column says whether the API a document describes is stable or
+experimental. Reference documents describe the code or its performance
+rather than an API.
+
+| Document | Status | Topic |
+| --- | --- | --- |
+| [01. VFS](./01_vfs.md) | Stable | Layout of the workspace tree, reserved paths, and mount points. |
+| [02. Sync Protocol](./02_sync_protocol.md) | Experimental | How the DO-backed VFS synchronises with the sandbox container. |
+| [03. Filesystem Schema](./03_filesystem_schema.md) | Stable | SQLite schema backing the virtual filesystem. |
+| [04. Filesystem Interface](./04_filesystem_interface.md) | Stable | `Workspace.fs` API: `readFile`, `writeFile`, `mkdir`, `grep`, etc. |
+| [05. Runtime Interface](./05_runtime_interface.md) | Stable | `Workspace.runtime.exec/getExec/killExec/disposeExec` and backend routing. |
+| [06. Mount Interface](./06_mount_interface.md) | Stable | Pre-filling paths from R2, Artifacts, GitHub, and custom sources. **(not yet implemented)** |
+| [07. Injected Service](./07_injected_service.md) | Experimental | The in-container `computerd` service that backs FUSE and shell. |
+| [08. Capnweb Interface](./08_capnweb_interface.md) | Experimental | RPC wire protocol between the DO and the sandbox. |
+| [09. Tool Interface (Agents)](./09_tool_interface.md) | Stable | Ready-made AI SDK tools for `@cloudflare/agents`. |
+| [10. Project Layout](./10_project_layout.md) | Reference | Source tree of this package and how the pieces fit together. |
+| [11. Lifecycle](./11_lifecycle.md) | Mixed: stub disposal is stable; the container and capnweb lifecycle are experimental | DO incarnations, container lifetime, capnweb session lifecycle, and hibernation. |
+| [12. Worker backend](./12_worker_backend.md) | Experimental | Running the shell as just-bash inside a Dynamic Worker loaded through `env.LOADER`. |
+| [13. Git interface](./13_git_interface.md) | Stable | `workspace.git` and the `git` CLI inside the shell, backed by isomorphic-git. |
+| [14. Assets interface](./14_assets_interface.md) | Stable | `share` a workspace file to R2 and get back a presigned URL. |
+| [15. Artifacts interface](./15_artifacts_interface.md) | Stable | `createArtifact` and the `artifacts` CLI, an optionally session-scoped wrapper over the Cloudflare Artifacts binding. |
+| [16. Execution runtime architecture](./16_code_execution.md) | Stable | One runtime entry point over command and module backends. |
+| [17. Isolate JavaScript runtime](./17_isolate_javascript.md) | Stable, except `ws:container` | ECMAScript modules, durable imports, configured libraries, durable `node:fs/promises`, host modules, and managed lifecycle. |
+| [18. Runtime migration](./18_runtime_migration.md) | Reference | Breaking preview-API mappings from public shell and script-execution surfaces to `workspace.runtime`. |
+| [19. Performance](./19_performance.md) | Reference | Filesystem benchmarks: `fs-bench` numbers, an `npm install` comparison, and how to reproduce them. |
 
 ## High-level API
 

diff --git a/examples/assets/README.md b/examples/assets/README.md
@@ -1,9 +1,5 @@
 # assets example
 
-> [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
-
 A Cloudflare Worker + Durable Object that turns a text prompt into
 an image and hands back a shareable link. One shot: `POST /prompt`,
 get a URL.