Cloudflare Computer：为 Agent 配备一台电脑

Cloudflare Computer 是一个存在于 Durable Object 内部的虚拟文件系统。Durable Object 在 SQLite 中保存权威状态，并通过 workspace.runtime 暴露一个可插拔的执行界面。目前提供三种后端：

• Container 将 SQLite 状态投射到沙箱容器中，作为真实的 FUSE 挂载。沙箱侧守护进程（computerd）将状态挂载为文件系统，并通过 capnweb RPC 通道把变更同步回去。具备完整的 Linux 用户空间、真实二进制文件和真实网络。
• Isolate shell 在 Dynamic Worker 中运行 just-bash。它通过 Workers RPC 访问权威 Workspace，因此不存在第二个存储，也没有同步往返开销。
• Isolate JavaScript 在新的 Dynamic Worker 中运行 ECMAScript 模块，提供结构化输入和结果、持久化相对导入、已配置的库、由 Workspace 支持的 node:fs/promises，以及受信任的 ws:git 和 ws:artifacts 模块。

一个 Workspace 可以在稳定 ID 下注册多个后端。workspace.runtime.exec(source, { backend }) 是唯一的执行入口；所选后端决定 source 是 Shell 命令还是 ECMAScript 模块。后端会在首次使用时惰性连接。

Workspace 也可以在完全不配置后端的情况下构建，使调用方能够单独使用文件系统。

重要提示

仅限预览版（PREVIEW ONLY） 此软件包仅作为收集反馈的预览版本提供。API 尚不稳定，设计也可能发生变化。

适合用于实验、探索和原型开发。目前不适合用于生产环境。

docs/ 中的规范面向未来——请将其作为设计意图来阅读，而不要将其视为对当前代码的描述。

如果你希望基于 Cloudflare Computer 进行开发，请安装 @cloudflare/computer，并遵循该软件包的 README——其中包含安装步骤、入口映射，以及 fs 和 runtime 界面的完整示例。

如需提交反馈，请参阅 CONTRIBUTING.md。获批准的协作者应遵循 COLLABORATORS.md 中的设置、构建和测试说明。

examples/ 目录包含可运行的公共接口使用示例。每个示例都是一个拥有各自 README 的 Worker 工作区。

• examples/container —— 在容器内运行 computerd，挂载一个 workspace，并通过 capnweb 与 Durable Object 通信。提供 write / read / exec HTTP 接口。
• examples/worker-shell —— 与容器示例具有相同的 HTTP 接口，但 Shell 在通过 env.LOADER 加载的 Dynamic Worker 中运行 just-bash。无需容器。
• examples/worker-javascript —— 与 worker-shell 相对应，但 exec 会在 Dynamic Worker 中执行 ECMAScript 模块，而不是运行 Shell 命令。
• examples/think —— 一个可从终端访问、使用 workspace 作为工作目录的 @cloudflare/think 聊天 Agent。
• examples/think-compare-runtimes —— 一个 Web UI，可并排在容器和 Worker 运行时上执行同一个 Agent 任务。
• examples/tutorial —— 分步构建教程：一个端点、一个在主机上编写 Markdown 食谱卡的 Agent，以及一个在容器中对该文件运行 pandoc 以生成 PDF 的流程。
• examples/artifacts —— 在 workspace 中生成一个 Worker 项目，并将其发布到 Cloudflare Artifacts，成为可克隆的仓库。
• examples/assets —— 使用 Workers AI 根据提示词生成图像，将其写入 workspace，并通过 @cloudflare/computer/assets 返回可分享链接。

该仓库是一个小型 monorepo。每个软件包都有各自的 README，其中包含软件包特定的状态和使用说明。

• packages/dofs (@cloudflare/dofs) —— 基于 Durable Object SQLite 的虚拟文件系统、同步协议构建模块，以及适用于 Node 的 @platformatic/vfs 提供程序。
• packages/rpc (@cloudflare/computer-rpc) —— 由 Durable Object 与 computerd 共享的 capnweb 线路类型和服务端/客户端辅助工具。
• packages/computerd (@cloudflare/computerd) —— computerd 守护进程：在沙箱容器中运行的 FUSE 挂载和 HTTP/WebSocket RPC 服务器。
• packages/computer (@cloudflare/computer) —— 供 Durable Objects 使用的顶层 Computer 软件包。仍在开发中。
• packages/computer-computerd-linux-x64 —— 面向预构建 computerd linux-x64 二进制文件的私有 Docker 镜像上下文。镜像而非 npm 软件包才是发布构件。

computerd 的 FUSE 挂载在元数据密集型工作负载上优于真实磁盘，但在大型顺序 I/O 上落后于真实磁盘。完整的 fs-bench 数据、与 cloudflare/sandbox-sdk 的 npm install 对比，以及复现方式，请参阅 docs/19_performance.md。

我们通过 issue 和讨论接受错误报告、修复建议、功能请求和设计提案。我们不接受未经请求的 Pull Request。公开贡献途径请参阅 CONTRIBUTING.md。

获批准的协作者应遵循 COLLABORATORS.md 中关于环境设置、格式化、测试、提交信息和 Pull Request 约定的要求。

如果你以 Agent 身份在此仓库中工作，请先阅读 AGENTS.md，以及 .agents/skills/ 下的技能说明。

MIT 许可证。参阅 LICENSE。

Cloudflare Computer is a virtual filesystem that lives inside a Durable Object. The Durable Object holds the authoritative state in SQLite and exposes one pluggable execution surface through workspace.runtime. Three backends ship today:

• Container projects the SQLite state into a sandbox container as a real FUSE mount. A sandbox-side daemon (computerd) mounts the state as a filesystem and syncs changes back over a capnweb RPC channel. Full Linux userland, real binaries, real network.
• Isolate shell runs just-bash in a Dynamic Worker. It reaches the authoritative Workspace over Workers RPC, so there is no second store or sync round trip.
• Isolate JavaScript runs an ECMAScript module in a fresh Dynamic Worker with structured input/results, durable relative imports, configured libraries, Workspace-backed node:fs/promises, and trusted ws:git and ws:artifacts modules.

A Workspace may register multiple backends under stable IDs. workspace.runtime.exec(source, { backend }) is the single execution entry point; the selected backend defines whether source is a shell command or an ECMAScript module. Backends connect lazily on first use.

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 specification under docs/ is forward-looking — read it for intent, not as description of the code today.

If you want to build on Cloudflare Computer, install @cloudflare/computer and follow that package's README — it has the installation steps, the entrypoint map, and worked examples of the fs and runtime surfaces.

To contribute feedback, see CONTRIBUTING.md. Approved collaborators should follow COLLABORATORS.md for setup, build, and test instructions.

The examples/ directory holds runnable consumers of the public surface. Each is a Worker workspace with its own README.

• examples/container — runs computerd inside a container, mounts a workspace, and talks to a Durable Object over capnweb. A write / read / exec HTTP surface.
• examples/worker-shell — same HTTP surface as the container example, but the shell runs just-bash in a Dynamic Worker loaded through env.LOADER. No container.
• examples/worker-javascript — mirrors worker-shell, but exec evaluates an ECMAScript module in a Dynamic Worker instead of running a shell command.
• examples/think — a @cloudflare/think chat agent that uses the workspace as its working directory, reachable from a terminal.
• examples/think-compare-runtimes — a web UI that runs the same agent task against the container and worker runtimes side by side.
• examples/tutorial — a step-by-step build: one endpoint, one agent that writes a markdown recipe card on the host and runs pandoc on it in the container to produce a PDF.
• examples/artifacts — generates a Worker project in a workspace and publishes it to Cloudflare Artifacts as a clone-ready repo.
• examples/assets — turns a prompt into an image with Workers AI, writes it to the workspace, and returns a shareable link through @cloudflare/computer/assets.

The repo is a small monorepo. Each package has its own README with package-specific status and usage notes.

• packages/dofs (@cloudflare/dofs) — Durable Object SQLite-backed virtual filesystem, sync protocol building blocks, and a @platformatic/vfs provider for Node.
• packages/rpc (@cloudflare/computer-rpc) — capnweb wire types and server/client helpers shared between the Durable Object and computerd.
• packages/computerd (@cloudflare/computerd) — the computerd daemon: a FUSE mount plus HTTP/WebSocket RPC server that runs inside the sandbox container.
• packages/computer (@cloudflare/computer) — the top-level Computer package consumed by Durable Objects. Work in progress.
• packages/computer-computerd-linux-x64 — private Docker image context for the prebuilt computerd linux-x64 binary. The image, not an npm package, is the release artifact.

computerd's FUSE mount beats real disk on metadata-heavy work and trails it on large sequential I/O. See docs/19_performance.md for the full fs-bench numbers, a cloudflare/sandbox-sdk npm install comparison, and how to reproduce them.

We accept bug reports, fix proposals, feature requests, and design proposals through issues and discussions. We do not accept unsolicited pull requests. See CONTRIBUTING.md for the public contribution paths.

Approved collaborators should follow COLLABORATORS.md for setup, formatting, testing, commit message, and pull request conventions.

If you're working in this repo as an agent, start with AGENTS.md and the skills under .agents/skills/.

MIT. See LICENSE.