cloudflare / computer

查看原文 / View Original 编辑 / Edit

Cloudflare Computer

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. Cloudflare Computer 是一个存在于 Durable Object 内部的虚拟文件系统。Durable Object 在 SQLite 中保存权威状态，并通过 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. 目前提供三种后端：Container（容器）将 SQLite 状态映射到沙盒容器中，作为一个真实的 FUSE 挂载点。沙盒端的守护进程 (computerd) 将该状态挂载为文件系统，并通过 capnweb RPC 通道同步变更。它支持完整的 Linux 用户空间、真实的二进制文件和真实的网络。

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 shell 在 Dynamic Worker 中运行 just-bash。它通过 Workers RPC 连接到权威的 Workspace，因此无需额外的存储或同步往返。

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. Isolate JavaScript 在全新的 Dynamic Worker 中运行 ECMAScript 模块，支持结构化输入/结果、持久化相对导入、已配置的库、由 Workspace 支持的 node:fs/promises，以及受信任的 ws:git 和 ws:artifacts 模块。

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. 一个 Workspace 可以通过稳定 ID 注册多个后端。workspace.runtime.exec(source, { backend }) 是唯一的执行入口点；所选后端决定了 source 是 shell 命令还是 ECMAScript 模块。后端在首次使用时进行懒加载连接。Workspace 也可以在没有后端的情况下构建，仅为调用者提供文件系统功能。

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. 此软件包仅作为预览版提供，旨在收集反馈。API 不稳定，设计可能会发生变化。适用于实验、探索和原型开发。目前不适合生产环境使用。docs/ 下的规范具有前瞻性——请将其视为设计意图，而非当前代码的描述。

Using it

如何使用

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. 如果您想基于 Cloudflare Computer 进行开发，请安装 @cloudflare/computer 并遵循该软件包的 README——其中包含安装步骤、入口点映射以及文件系统和运行时接口的示例。如需提供反馈，请参阅 CONTRIBUTING.md。获批的协作者应遵循 COLLABORATORS.md 获取设置、构建和测试说明。

Examples

示例

The examples/ directory holds runnable consumers of the public surface. Each is a Worker workspace with its own README. examples/ 目录包含公共接口的可运行消费者。每个示例都是一个带有独立 README 的 Worker 工作区。

  • 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/container — 在容器内运行 computerd，挂载工作区，并通过 capnweb 与 Durable Object 通信。提供写入/读取/执行的 HTTP 接口。
  • 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-shell — 与容器示例具有相同的 HTTP 接口，但 shell 在通过 env.LOADER 加载的 Dynamic Worker 中运行 just-bash。无需容器。
  • examples/worker-javascript — mirrors worker-shell, but exec evaluates an ECMAScript module in a Dynamic Worker instead of running a shell command.
  • examples/worker-javascript — 镜像 worker-shell，但 exec 在 Dynamic Worker 中评估 ECMAScript 模块，而不是运行 shell 命令。
  • examples/think — a @cloudflare/think chat agent that uses the workspace as its working directory, reachable from a terminal.
  • examples/think — 一个 @cloudflare/think 聊天代理，它将工作区用作工作目录，可通过终端访问。
  • examples/think-compare-runtimes — a web UI that runs the same agent task against the container and worker runtimes side by side.
  • examples/think-compare-runtimes — 一个 Web UI，用于并排运行容器和 Worker 运行时下的相同代理任务。
  • 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/tutorial — 一个分步构建示例：一个端点，一个代理在主机上编写 markdown 食谱卡片，并在容器中对其运行 pandoc 以生成 PDF。
  • examples/artifacts — generates a Worker project in a workspace and publishes it to Cloudflare Artifacts as a clone-ready repo.
  • examples/artifacts — 在工作区中生成一个 Worker 项目，并将其作为可克隆的仓库发布到 Cloudflare Artifacts。
  • 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.
  • examples/assets — 使用 Workers AI 将提示词转换为图像，将其写入工作区，并通过 @cloudflare/computer/assets 返回可共享链接。

Repository layout

仓库布局

The repo is a small monorepo. Each package has its own README with package-specific status and usage notes. 该仓库是一个小型 monorepo。每个软件包都有自己的 README，包含特定于软件包的状态和使用说明。

  • packages/dofs (@cloudflare/dofs) — Durable Object SQLite-backed virtual filesystem, sync protocol building blocks, and a @platformatic/vfs provider for Node.
  • packages/dofs (@cloudflare/dofs) — 基于 Durable Object SQLite 的虚拟文件系统、同步协议构建块以及用于 Node 的 @platformatic/vfs 提供程序。
  • packages/rpc (@cloudflare/computer-rpc) — capnweb wire types and server/client helpers shared between the Durable Object and computerd.
  • packages/rpc (@cloudflare/computer-rpc) — 在 Durable Object 和 computerd 之间共享的 capnweb 线上传输类型及服务器/客户端辅助工具。
  • packages/computerd (@cloudflare/computerd) — the computerd daemon: a FUSE mount plus HTTP/WebSocket RPC server that runs inside the sandbox container.
  • packages/computerd (@cloudflare/computerd) — computerd 守护进程：在沙盒容器内运行的 FUSE 挂载点及 HTTP/WebSocket RPC 服务器。
  • packages/computer (@cloudflare/computer) — the top-level Computer package consumed by Durable Objects. Work in progress.
  • packages/computer (@cloudflare/computer) — 由 Durable Objects 使用的顶层 Computer 软件包。开发中。
  • 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.
  • packages/computer-computerd-linux-x64 — 用于预构建 computerd linux-x64 二进制文件的私有 Docker 镜像上下文。发布产物是镜像，而非 npm 软件包。

Performance

性能

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. computerd 的 FUSE 挂载在元数据密集型任务中优于真实磁盘，但在大文件顺序 I/O 上稍逊一筹。请参阅 docs/19_performance.md 获取完整的 fs-bench 数据、cloudflare/sandbox-sdk npm 安装对比以及复现方法。

Documentation

文档

  • docs/ — design specification. Forward-looking; treat as intent.
  • docs/ — 设计规范。具有前瞻性；请视为设计意图。
  • docs/19_performance.md — filesystem benchmarks.
  • docs/19_performance.md — 文件系统基准测试。

Contributing

贡献

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/. 我们通过 issues 和 discussions 接受错误报告、修复建议、功能请求和设计提案。我们不接受未经请求的 pull requests。请参阅 CONTRIBUTING.md 获取公共贡献路径。获批的协作者应遵循 COLLABORATORS.md 获取设置、格式化、测试、提交信息和 pull request 规范。如果您作为代理在此仓库中工作，请从 AGENTS.md 和 .agents/skills/ 下的技能开始。

License

许可证

MIT. See LICENSE. MIT。请参阅 LICENSE。

← 返回新闻列表 / Back to news list