README.md— what this repo is and how the pieces fit together.CONTRIBUTING.md— public contribution paths.COLLABORATORS.md— setup, checks, commit and pull request conventions. The canonical source for the day-to-day workflow.docs/README.md— design specification. Forward- looking; treat as intent, not as a description ofmain.docs/08_capnweb_interface.md— the RPC contract between the Durable Object andcomputerd. Required reading before touchingpackages/rpcorpackages/computer.- Each package's own
README.md— implementation status and package-specific notes.
In-repo skills live under .agents/skills/. Load
the file directly when the trigger applies:
| Skill | Load when |
|---|---|
prose |
Writing code comments, commit messages, READMEs, or documentation. |
pull-requests |
Writing or editing a pull request description. |
test-driven-development |
Implementing logic, fixing a bug, or changing behavior. |
capnweb |
Touching anything that crosses the RPC boundary: packages/rpc, packages/computer, the computerd client, or the Durable Object server. |
cloudflare |
Index of host-side Cloudflare skills — Workers, Durable Objects, wrangler, sandbox SDK, agents SDK. |
A fresh container does not have everything the tests need. The traps below cost real time if you discover them one failure at a time.
Native build tools. packages/computerd depends on a vendored copy
of fuse-napi at packages/computerd/vendor/fuse-napi, a native addon
compiled from source on install. Building it needs a C toolchain and the
libfuse 3 headers. On Debian or Ubuntu:
apt-get install build-essential pkg-config libfuse3-dev fuse3Any libfuse 3 compiles. Kernel passthrough for local-only paths needs
3.17 or newer (Debian trixie); against an older one the addon builds
without it and those paths are served by computerd instead.
If the addon build fails, npm install aborts the whole install, not
just that one package. When you only need the rest of the workspace,
install with npm install --ignore-scripts. That also skips the root
postinstall, so run npm run build:types before building the
examples, and build the addon yourself when you need it:
cd packages/computerd/vendor/fuse-napi && npx node-gyp rebuildThe binary build uses Docker. npm run build:bin compiles the addon
for linux-x64 inside a node:22-trixie-slim container, so it works the
same from an arm64 machine (through emulation, which is slow the first
time; the result is cached under packages/computerd/dist/sea). Set
COMPUTERD_FUSE_ADDON to a prebuilt fuse.node to skip that step.
remote-exec is Rust. packages/remote-exec builds a static Linux
binary with Cargo, which needs Rust with both musl targets and capnp;
its tests and @cloudflare/computer's npm run test:remote-exec need
Linux. Nothing else in the workspace needs Rust, and the npm package
doesn't ship the binary. packages/remote-exec/dev/run.sh runs any
command in a Linux container that has everything.
Build before you test. The test scripts don't build the sibling
packages first. Several suites need build output that is absent in
a clean checkout: packages/computerd imports the sibling @cloudflare/dofs
and @cloudflare/computer-rpc packages from their dist/
directories, packages/computerd's src/cli/computerd.test.ts spawns the bundled
CLI at dist/cli/computerd.js, and examples/think-compare-runtimes
imports @cloudflare/computer/backends/container-legacy, which exists only
after the computer package is built. Run npm run build across the
npm workspace before npm test on a clean checkout.
Real FUSE needs privilege. packages/computerd's src/cli/computerd.test.ts
runs its real-FUSE case only when /dev/fuse is reachable; otherwise
it resolves to the shim and skips. The guard is a bare existence check,
so a mknod'd /dev/fuse in an unprivileged container defeats the
skip and the mount then fails with EPERM, turning a clean skip into a
hard failure. Leave the device absent unless the container is
privileged (--privileged, or CAP_SYS_ADMIN with device access). The
src/exec/runner.fuse.test.ts and src/fuse/passthrough.fuse.test.ts
suites are separate: they skip unless both Docker and the prebuilt
computerd binary are available, and run computerd inside a privileged
container. See the
debugging-computerd-fuse skill
for the privileged Docker setup.
Run from the repo root:
npm run format # oxfmt (rewrites files)
npm run check # oxlint + oxfmt --check + sherifnpm run check must exit zero. Fix the underlying issue rather than
silencing the rule.
Then run the package-level tests for whatever you touched:
npm test # whole workspace
npm test --workspace @cloudflare/dofs # one package
npm test --workspace @cloudflare/dofs -- src/foo.test.ts # one fileFull details, including typecheck and build commands, are in
COLLABORATORS.md.
Follow COLLABORATORS.md. The short version:
- One logical change per commit.
- Imperative subject prefixed with the scope (
dofs:,rpc:,computer:,computerd:,examples/think:,docs:,ci:). Multiple scopes joined with commas. - Self-contained body wrapped at 72 characters. No references to chat history, agent sessions, sibling commit SHAs, or task identifiers.
- No emojis. No marketing voice. Prose paragraphs in the body, not bulleted lists.
Full guidance is in .agents/skills/prose/SKILL.md
and .agents/skills/pull-requests/SKILL.md.
Keep a changeset to one line. Link to the docs when they say more, and put longer upgrade steps there rather than in the changeset.
Two top-level directories hold helper scripts. They're outside the npm workspace package set on purpose — they're tooling, not shipped code.
script/ holds maintainance scripts and operator-facing harnesses for computerd and the sync
loop. Reach for these when you're chasing a behavior the unit tests don't cover.
shellboots a debian-slim container with the linuxcomputerdbinary mounted under/usr/local/bin. The starting point for anything that needs a real FUSE mount.computerd-soak.mjsboots onecomputerdcontainer, takes the host's part of the sync loop from a local store, and reports convergence lag beside container memory. Use it to chase convergence or churn bugs.computerd-stub-soak.mjssoaks the long-lived WebSocket session and readssession.getStats()to detect stub-disposal drift. Run it for changes around the capnweb lifecycle.computerd-fuse-flush.mjsend-to-end checks that the FUSE driver spills its in-memory write buffer into the backing VFS, so a capnweb-sidepullOnceactually sees the bytes.fs-tests.sh/run-fs-tests.shrun the filesystem conformance harness against the FUSE mount.fs-bench.sh/run-fs-bench.shbenchmark common development tasks against the mount with a tmpfs baseline for comparison.exec-testsbootscomputerdin docker with FUSE disabled and exercises a fewshell.execscenarios.lib/cloudflare-workers-stub.mjsis a node--importhook that stubs thecloudflare:workersmodule, so a host-side script can import@cloudflare/computer's main entry outside workerd. Not runnable on its own;exec-testsuses it.npm-bench.sh/run-npm-bench.shbenchmark npm package installs on native disk vs the FUSE mount.run-npm-bench.shis the user-facing entry point that boots a privileged Docker container;run-npm-bench-inner.shis the in-container entrypoint that installs dependencies, startscomputerd, and invokesnpm-bench.sh, which runs the actual benchmark. SetSCENARIOS,REPS,WARMUP, andOUTPUT_JSONto control what runs and where results land.
When you add a script, drop a one-line description at the top of the file and add it to the list above.
- RPC. The wire contract is capnweb. Read
docs/08_capnweb_interface.mdand thecapnwebskill before changing anything that crosses the Durable Object ↔computerdboundary. Stubs are object-capabilities; dispose them. Leaks are tracked by the harness inpackages/rpc. - Storage.
packages/dofsis the authoritative SQLite layer. Filesystem primitives operate on aDatabasehandle; the sync protocol building blocks share the same handle. The package README enumerates the exported surface. - FUSE shim.
packages/computerdruns in the sandbox container. FUSE- backed tests only run on Linux and are skipped elsewhere automatically. - Examples are real consumers.
examples/think,examples/container-legacy, andexamples/worker-shellexercise the public surface. If you change a public API, update them in the same change.