discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens

cloudflare/computer · source

Snapshot 0 · 2026-11-04T12:47:28Z · TypeScript · MIT

GitHub description at capture

Give your agent a computer 👾

README at capture

# 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`. 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](https://github.com/vercel-labs/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 host modules such as
  `codemode:git`, `codemode:artifacts`, and `codemode:container`.

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]
> 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.

## Using it

If you want to build on Cloudflare Computer, install
[`@cloudflare/computer`](packages/computer/README.md) 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`](CONTRIBUTING.md).
Approved collaborators should follow [`COLLABORATORS.md`](COLLABORATORS.md)
for setup, build, and test instructions.

## Examples

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

- [`examples/container`](examples/container) — runs `computerd` inside a
  container the Durable Object schedules itself, mounts a workspace, and
  talks to the object over capnweb. A `write` / `read` / `exec` HTTP
  surface. The launch names the image and the instance size, because
  `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. 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.
- [`examples/worker-javascript`](examples/worker-javascript) — mirrors
  `worker-shell`, but `exec` evaluates an ECMAScript module in a Dynamic
  Worker instead of running a shell command.
- [`examples/vite-bundle`](examples/vite-bundle) — a Vite-built Worker
  that ships `src/skills` into every workspace with `computerBundle()`
  and `WorkerBundle`, including under `vite dev`.
- [`examples/egress`](examples/egress) — sends one URL through the container,
  Worker shell, and Worker JavaScript backends with matching `none`, `all`, or
  custom egress policies.
- [`examples/mcp`](examples/mcp) — a Computer MCP example:
  one Code Mode `code` tool backed by a durable workspace, a Worker shell,
  and a full Linux container.
- [`examples/rlm`](examples/rlm) — shows how generated JavaScript can read long
  context from a Computer Workspace, call bounded model workers, and reduce their
  structured results with code.
- [`examples/pi-ai`](examples/pi-ai) — a one-shot [pi](https://github.com/earendil-works/pi)
  agent. Its loop asks the model, runs the workspace tools it asked for,
  and repeats until the model stops asking.
- [`examples/tanstack-ai`](examples/tanstack-ai) — the same one-shot agent on
  [TanStack AI](https://tanstack.com/ai), where `chat()` runs the loop.
- [`examples/think`](examples/think) — a [`@cloudflare/think`](https://www.npmjs.com/package/@cloudflare/think)
  chat agent that uses the workspace as its working directory, reachable
  from a terminal.
- [`examples/think-compare-runtimes`](examples/think-compare-runtimes) —
  a web UI that runs the same agent task against the container and
  worker runtimes side by side.
- [`examples/tutorial`](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`](examples/artifacts) — generates a Worker project
  in a workspace and publishes it to Cloudflare Artifacts as a
  clone-ready repo.
- [`examples/assets`](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`.

Every example's `Env` type is generated by `wrangler types` rather than
committed. `npm install` at the repo root runs each example's
`build:types` script, and `npm run build:types` regenerates them all
after a `wrangler.jsonc` or env template changes.

## Repository layout

The repo is a small monorepo. Each package has its own README with
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. 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

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

## Documentation

- [`docs/`](docs/README.md) — design specification. Forward-looking;
  treat as intent.
- [`docs/19_performance.md`](docs/19_performance.md) — filesystem benchmarks.

## 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`](CONTRIBUTING.md) for the public
contribution paths.

Approved collaborators should follow
[`COLLABORATORS.md`](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`](AGENTS.md) and the skills under
[`.agents/skills/`](.agents/skills/).

## License

MIT. See [`LICENSE`](LICENSE).