# Debugging Computerd Fuse

Debug computerd in real-FUSE mode end-to-end without workerd, vitest-pool-workers, or...

- Repository: https://github.com/cloudflare/computer (9770 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add cloudflare/computer --skill debugging-computerd-fuse -g -a claude-code -y`
Codex: `npx skills add cloudflare/computer --skill debugging-computerd-fuse -g -a codex -y`
Cursor: `npx skills add cloudflare/computer --skill debugging-computerd-fuse -g -a cursor -y`
Gemini CLI: `npx skills add cloudflare/computer --skill debugging-computerd-fuse -g -a gemini-cli -y`

## Description

Debug computerd in real-FUSE mode end-to-end without workerd, vitest-pool-workers, or wrangler in the loop. Boot the linux-x64 binary in a privileged docker container, drive its capnweb /api endpoint from Node, simulate DO-side sync from a SQLiteTestStorage, and isolate FUSE-related deadlocks. Load when a real-FUSE bug reproduces locally but unit tests pass, when the harness vitest tests hang against a real container, or when you need to attribute a wedge to FUSE vs sync vs exec.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Debugging computerd against real FUSE

This skill captures the recipe for isolating bugs in computerd that only
fire when the kernel-FUSE backend is the one wired up. Most unit
tests run against `SQLiteTestStorage` and an in-process VFS or the
userspace `FUSE_MOUNT=shim` polling driver, neither exercises the
kernel-FUSE callback path. Several production-only bugs (write
buffer never spilled to the VFS, `spawn(cwd=/mount)` deadlocks)
have shipped to `next` and not been caught by the regular suites
because the harness is hard to drive end-to-end from a dev box.

The workflow here bypasses workerd, wrangler, and the
vitest-pool-workers harness. It boots the computerd SEA binary in a real
docker container with `/dev/fuse` and SYS_ADMIN, and drives its
capnweb endpoints from a plain Node script.

## When to reach for this

- A user report of "wrote a file via FUSE, RPC reads see 0 bytes."
- A report of "exec hangs forever" or "computerd `/health` stops
  responding after the first shell call."
- Adding a new computerd op (FUSE callback, sync RPC, runner feature)
  and you want a smoke test that doesn't depend on Docker-in-DO or
  Cloudflare Containers.
- The harness vitest suite (`packages/computer/src/test-harness/`)
  hangs at `ws.shell.exec` against the docker container and you
  need to attribute the wedge to computerd vs workerd vs the network
  shim.
- Confirming a fix actually settles in the deployed binary: the
  SEA build is what wrangler ships, and reproducing locally with
  the same binary is the only way to be sure.

## What you need

The rest: https://github.com/cloudflare/computer/blob/HEAD/.agents/skills/debugging-computerd-fuse/SKILL.md