cloudflare/computer

Cloudflare Computer – What It Is

Cloudflare Computer is a library that gives you a virtual filesystem backed by a Cloudflare Durable Object. The Durable Object stores the file data in SQLite, and the library lets you run code that reads and writes that filesystem through three interchangeable “backends”:

Backend	How it works	What you get
Container	The SQLite state is projected into a sandboxed Linux container via a FUSE mount. A daemon (`computerd`) runs inside the container, exposing the FS over a Cap’n‑Proto‑over‑WebSocket RPC channel.	Full Linux user‑land, real binaries, network access – ideal when you need to run arbitrary tools (e.g., `pandoc`, `git`).
Isolate Shell	Executes the lightweight just‑bash shell inside a Cloudflare Dynamic Worker. Calls the Durable Object directly via Workers RPC, so there is no extra storage sync.	Very fast shell commands, no container overhead, but only shell‑compatible tools.
Isolate JavaScript	Spins up a fresh Dynamic Worker that runs an ECMAScript module. The module sees a `node:fs/promises`‑like API that is backed by the Workspace, plus special host modules (`ws:git`, `ws:artifacts`, `ws:container`).	Run JavaScript code that can read/write the virtual FS and call Cloudflare‑provided services.

All three backends are accessed through a single entry point:

await workspace.runtime.exec(source, { backend: "container" })

The source can be a shell command (for the shell backend) or an ES module (for the JavaScript backend). A Workspace can also be created without any backend, exposing just the filesystem API.

Why It Matters for AI / Agents

Many AI‑agent architectures need a persistent, mutable workspace where they can:

Store intermediate files (e.g., downloaded images, generated code).
Run external tools (compilers, image processors, git) to transform those files.
Share the same state across multiple invocations or workers.

Cloudflare Computer provides exactly that, but hosted on Cloudflare’s edge platform, so the workspace lives close to the AI model inference workers and can be accessed from any Durable Object‑aware service.

Key Features

Durable‑Object‑backed persistence – SQLite inside a Durable Object guarantees strong consistency and automatic replication.
Pluggable execution backends – Choose between a full Linux container, a lightweight Bash shell, or a JavaScript module, all using the same FS surface.
FUSE‑style mount – The container backend presents the virtual FS as a real mount, letting any Linux binary operate on it.
Structured RPC – Communication between the Durable Object and the container daemon uses a Cap’n‑Proto‑over‑WebSocket protocol (@cloudflare/computer-rpc).
First‑class support for AI‑agent examples – The repo ships many ready‑to‑run demos (e.g., a one‑shot pi agent, a TanStack AI chat loop, a PDF‑generation tutorial) that showcase typical agent workflows.
Performance‑tested – Benchmarks show the FUSE mount out‑performs real disk for metadata‑heavy workloads.

Typical Use Cases

Agent tool execution – An LLM‑driven agent can ask the workspace to run git clone, compile code, or invoke pandoc to turn markdown into PDF, all via the container backend.
RAG‑style data pipelines – Store fetched web content, run text‑processing scripts, and feed the cleaned data back to a model, all within the same Durable Object workspace.
Multi‑runtime experimentation – Compare how a task runs in a container vs. a Bash worker vs. a JavaScript worker using the think-compare-runtimes example.
Artifact publishing – Generate a project inside the workspace and publish it to Cloudflare Artifacts with the artifacts example.

Maturity & Stability

The top‑level @cloudflare/computer package is marked stable for its core API, but the container and worker‑shell backends are still experimental and not recommended for production.
The underlying @cloudflare/dofs (Durable Object FS) is stable.
Detailed status tables are in packages/computer/README.md#status.

Getting Started

Install the package:
```
npm i @cloudflare/computer
```
Follow the package‑specific README (packages/computer/README.md) for:
- Setting up a Durable Object that creates a Workspace.
- Choosing a backend and calling workspace.runtime.exec.
- Running the provided examples (npm run build:types && npm run dev:example/<name>).
For a quick demo, try the tutorial example, which builds a single endpoint that writes a markdown recipe, runs pandoc in a container, and returns a PDF.

Documentation & Resources

Design spec – docs/ (forward‑looking, intent‑only).
Performance numbers – docs/19_performance.md.
Examples – See the examples/ folder; each sub‑folder has its own README.
Contribution guide – CONTRIBUTING.md, COLLABORATORS.md.

License

MIT.

cloudflare/computer