AGENTS.md · cloudflare/computer

Sections

1. Read these first
2. Skills
3. Environment setup
4. Checks before you finish
5. Commits and pull requests
6. Scripts
7. Project-specific patterns

First lines (shown under the repo's MIT license)

# Agent guidelines

## Read these first

- [`README.md`](README.md) — what this repo is and how the pieces
  fit together.
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — public contribution paths.
- [`COLLABORATORS.md`](COLLABORATORS.md) — setup, checks, commit and
  pull request conventions. The canonical source for the day-to-day
  workflow.
- [`docs/README.md`](docs/README.md) — design specification. Forward-
  looking; treat as intent, not as a description of `main`.
- [`docs/08_capnweb_interface.md`](docs/08_capnweb_interface.md) —
  the RPC contract between the Durable Object and `computerd`. Required
  reading before touching `packages/rpc` or `packages/computer`.
- Each package's own `README.md` — implementation status and
  package-specific notes.

## Skills

In-repo skills live under [`.agents/skills/`](.agents/skills/). Load
the file directly when the trigger applies:

| Skill | Load when |
|---|---|
| [`prose`](.agents/skills/prose/SKILL.md) | Writing code comments, commit messages, READMEs, or documentation. |
| [`pull-requests`](.agents/skills/pull-requests/SKILL.md) | Writing or editing a pull request description. |
| [`test-driven-development`](.agents/skills/test-driven-development/SKILL.md) | Implementing logic, fixing a bug, or changing behavior. |
| [`capnweb`](.agents/skills/capnweb/SKILL.md) | Touching anything that crosses the RPC boundary: `packages/rpc`, `packages/computer`, the `computerd` client, or the Durable Object server. |
| [`cloudflare`](.agents/skills/cloudflare/SKILL.md) | Index of host-side Cloudflare skills — Workers, Durable Objects, wrangler, sandbox SDK, agents SDK. |

## Environment setup

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:

```bash
apt-get install build-essential pkg-config libfuse3-dev fuse3
```

Any 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:

```bash
cd packages/computerd/vendor/fuse-napi && npx node-gyp rebuild
```

**The 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.

**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`](.agents/skills/debugging-computerd-fuse/SKILL.md) skill
for the privileged Docker setup.

## Checks before you finish

Run from the repo root:

```bash
npm run format        # oxfmt (rewrites files)
npm run check         # oxlint + oxfmt --check + sherif
```

`npm run check` must exit zero. Fix the underlying issue rather than
silencing the rule.

Then run the package-level tests for whatever you touched:

```bash
npm test                                                  # whole workspace
npm test --workspace @cloudflare/dofs                     # one package
npm test --workspace @cloudflare/dofs -- src/foo.test.ts  # one file
```

Full details, including typecheck and build commands, are in
[`COLLABORATORS.md`](COLLABORATORS.md).

## Commits and pull requests

Follow [`COLLABORATORS.md`](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`](.agents/skills/prose/SKILL.md)
and [`.agents/skills/pull-requests/SKILL.md`](.agents/skills/pull-requests/SKILL.md).

## Scripts

Two top-level directories hold helper scripts. They're outside the
npm workspace package set on purpose — they're tooling, not shipped code.

[`script/`](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.

- `shell` boots a debian-slim container with the linux `computerd` binary
  mounted under `/usr/local/bin`. The starting point for anything
  that needs a real FUSE mount.
- `computerd-soak.mjs` boots one `computerd` container, 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.mjs` soaks the long-lived WebSocket session and
  reads `session.getStats()` to detect stub-disposal drift. Run it
  for changes around the capnweb lifecycle.
- `computerd-fuse-flush.mjs` end-to-end checks that the FUSE driver spills
  its in-memory write buffer into the backing VFS, so a capnweb-side
  `pullOnce` actually sees the bytes.
- `fs-tests.sh` / `run-fs-tests.sh` run the filesystem conformance
  harness against the FUSE mount.
- `fs-bench.sh` / `run-fs-bench.sh` benchmark common development
  tasks against the mount with a tmpfs baseline for comparison.
- `exec-tests` boots `computerd` in docker with FUSE disabled and exercises
  a few `shell.exec` scenarios.
- `lib/cloudflare-workers-stub.mjs` is a node `--import` hook that stubs
  the `cloudflare:workers` module, so a host-side script can import
  `@cloudflare/computer`'s main entry outside workerd. Not runnable on
  its own; `exec-tests` uses it.
- `npm-bench.sh` / `run-npm-bench.sh` benchmark npm package installs
  on native disk vs the FUSE mount. `run-npm-bench.sh` is the