computerd: clean up RPC interfaces

.agents/skills/capnweb/SKILL.md

@@ -14,7 +14,9 @@ description: |
 between the Durable Object and `computerd`. It's an object-capability RPC
 system with promise pipelining, structured-clone-style transfer of
 stubs, and bidirectional calls. The wire format used here is text
-JSON over a long-lived WebSocket, with an HTTP batch alternative.
+JSON over a long-lived WebSocket. That is the only carrier: capnweb's
+HTTP batch transport cannot deliver a stream returned from a call,
+which is what every read on this interface is.
 
 ## Where things live
 
@@ -48,10 +50,10 @@ you don't explicitly dispose stubs, you leak resources on the other
 side of the connection.
 
 This matters more here than in many capnweb deployments because the
-connection is **long-lived**. HTTP batch sessions auto-dispose
-everything when the batch ends, but our WebSocket between the
-Durable Object and `computerd` stays up for the lifetime of the workspace.
-Every undisposed stub stays alive until that connection drops.
+connection is **long-lived**. A short-lived session disposes everything
+when it ends; our WebSocket between the Durable Object and `computerd`
+stays up for the lifetime of the workspace, so every undisposed stub
+stays alive until that connection drops.
 
 ## The caller-disposes rule
 

.agents/skills/debugging-computerd-fuse/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debugging-computerd-fuse
-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 /ws 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.
+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.
 ---
 
 # Debugging computerd against real FUSE
@@ -87,10 +87,12 @@ with a missing `/dev/fuse` would have failed startup outright.
 
 ## Drive computerd from a Node script
 
-computerd serves a composite `WorkspaceRPC` over `/ws` (capnweb WebSocket)
-and `/api` (capnweb HTTP batch). The `@cloudflare/computer-rpc/client`
-package wraps the WS form and the `/driver` subpath exposes
-`pushOnce`/`pullOnce` against a Node-side `Database`.
+computerd serves a composite `WorkspaceRPC` over `/api`, a capnweb
+WebSocket. That is the only RPC carrier: capnweb's HTTP batch transport
+cannot deliver a returned stream, which is what every read on this
+interface is. The `@cloudflare/computer-rpc/client` package wraps the
+socket and the `/driver` subpath exposes `pushOnce`/`pullOnce` against a
+Node-side `Database`.
 
 Set up a probe project once:
 
@@ -123,7 +125,7 @@ import { pullOnce, pushOnce } from "@cloudflare/computer-rpc/driver";
 import { WebSocket } from "ws";
 
 const url = process.env.COMPUTERD_URL;                // e.g. http://127.0.0.1:18080
-const wsUrl = `${url.replace(/^http(s?):\/\//, "ws$1://")}/ws`;
+const wsUrl = `${url.replace(/^http(s?):\/\//, "ws$1://")}/api`;
 
 const storage = new SQLiteTestStorage();
 const db = new Database(storage);

.changeset/connect-names-host-paths.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/computer": minor
+---
+
+The /connect caller now provides both API & healthcheck endpoints. The container no longer builds either path itself, so a host is free to serve them wherever it likes.

.changeset/remove-upstream-url.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/computer": minor
+---
+
+The UPSTREAM_URL environment variable has been removed along with the container's own sync loop. Syncing is driven by whichever peer holds the other end of the Cap'n Web session.

.changeset/rename-ws-endpoint-to-api.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/computer": minor
+---
+
+The Cap'n Web /ws endpoint has been renamed to /api at both ends of the connection. A durable object that routes the container's outbound upgrade must match /api in its own fetch handler. Support for the Cap'n Web HTTP batch transport has been removed, so /api carries a websocket only.

AGENTS.md

@@ -133,8 +133,9 @@ 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 two `computerd` containers wired peer-to-peer and
-  soaks the sync loop. Use it to chase convergence or churn bugs.
+- `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.
@@ -147,6 +148,10 @@ loop. Reach for these when you're chasing a behavior the unit tests don't cover.
   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
   user-facing entry point that boots a privileged Docker container;

docs/07_injected_service.md

@@ -32,9 +32,8 @@ staging the binary into a container image.
    same paths. The backend is picked by `FUSE_MOUNT` (default `auto`,
    see the env-var table below).
 2. **Dirty tracking.** Writes that flow through FUSE land in the
-   in-container VFS database; sync (when `UPSTREAM_URL` is set) is
-   what surfaces those revisions back out. See doc 02 for the sync
-   protocol.
+   in-container VFS database; the host pulls those revisions back out
+   across the capnweb session. See doc 02 for the sync protocol.
 3. **Exec.** Runs shell commands and streams stdout/stderr back over
    capnweb. See [05. Shell Interface](./05_runtime_interface.md).
 4. **Apply.** Accepts changes pushed by the DO and writes them into
@@ -52,11 +51,15 @@ backend pins it to `8080`) and serves:
 | --- | --- | --- |
 | `/health` | `GET`, `HEAD` | Liveness probe; `200 ok\n` as soon as the HTTP server binds. |
 | `/__computerd/info` | `GET` | Runtime info: FUSE backend, mount point, port. |
-| `/api` | `POST` | HTTP-batch capnweb transport. |
-| `/ws` | `GET` (upgrade) | WebSocket capnweb transport — the bootstrap stub is `WorkspaceRPC`. |
-| `/connect` | `POST` | Tells `computerd` to dial *out* to a caller-supplied URL and serve a `WorkspaceRPC` session over that outbound WebSocket. Used by the Cloudflare backend (see below). |
+| `/api` | `GET` (upgrade) | WebSocket capnweb transport — the bootstrap stub is `WorkspaceRPC`. Only the exact path upgrades. A request without an `Upgrade` header gets `400`; an unsupported `Sec-WebSocket-Version` gets `426` and the versions the server speaks. |
+| `/api/watermarks` | `GET`, `HEAD` | Sync revisions: `currentRev`, `pushRev`, `fetchCursor`. The same values `sync.watermarks()` returns, for callers that want a few numbers without holding a session. |
+| `/connect` | `POST` | Tells `computerd` to dial *out* to a caller-supplied endpoint and serve a `WorkspaceRPC` session over that outbound WebSocket. Used by the Cloudflare backend (see below). |
 | `/` | `GET` | Banner/info page. |
 
+`/api` is the workspace surface: the session itself, plus anything that
+reads through it. `/__computerd` is daemon introspection, which is why
+runtime info sits there and revisions do not.
+
 The capnweb bootstrap interface is **`WorkspaceRPC`** (defined in
 `packages/rpc/`), split into `sync` and `shell` sub-stubs.
 
@@ -108,9 +111,9 @@ Provider-agnostic shape — three steps, in order:
    path the mount is awaited *before* `listen`, so by the time
    `/health` answers FUSE is up too. With `FUSE_MOUNT=none` there is
    no FUSE step at all.
-3. **Open the capnweb session.** Either the host upgrades to `/ws`
-   directly, or it asks `computerd` (via `POST /connect`) to dial *out* to a
-   URL it controls and serve the session over that outbound socket.
+3. **Open the capnweb session.** Either the host upgrades to `/api`
+   directly, or it asks `computerd` (via `POST /connect`) to dial *out* to an
+   endpoint it controls and serve the session over that outbound socket.
    Either way, the bootstrap stub is `WorkspaceRPC`.
 
 ### Cloudflare Containers specifics
@@ -132,8 +135,10 @@ wires it like this:
    repeated until it returns `200`.
 4. **Invert the WebSocket.** The DO arms an upgrade slot
    (`#armUpgrade`) and then `POST`s to `/connect` on the container
-   (`#postConnect`). `computerd` reads that request and dials *out* to the
-   egress at `${egressHost}/ws`. Because the egress is intercepted,
+   (`#postConnect`). The request names the egress base and both paths,
+   so `computerd` polls `base + health` and then dials `base + api`;
+   the daemon assembles no paths of its own. Because the egress is
+   intercepted,
    that outbound dial loops back to the DO's `handleFetch()`, which
    accepts the upgrade and resolves the in-flight `#pendingUpgrade`.
    The capnweb session then runs over that socket. **The WebSocket
@@ -154,10 +159,9 @@ These are the variables `computerd` actually consumes (see
 
 | Variable | Default | Meaning |
 | --- | --- | --- |
-| `PORT` | `45678` | Port the HTTP/WS server listens on. CF backend pins this to `8080`. |
+| `PORT` | `45678` | Port the HTTP server listens on. CF backend pins this to `8080`. |
 | `MOUNT_POINT` | `/workspace` | Absolute path inside the container to mount the FUSE filesystem at. Ignored when `FUSE_MOUNT=none`. |
 | `FUSE_MOUNT` | `auto` | Backend selector: `auto` probes `/dev/fuse` (linux) or macFUSE (darwin) and falls back to the userspace shim; `fuse` / `macfuse` require the corresponding real backend; `shim` forces the userspace shim; `none` skips the mount entirely. |
-| `UPSTREAM_URL` | unset | If set, `computerd` starts a sync client against this URL to push/pull VFS revisions. |
 | `EXEC_LOG_MAX_BYTES` | runner default | Caps the per-exec stdout/stderr log retained in-memory. |
 | `LOG_FILE` | unset | If set, every `console.log` / `console.error` line and any `uncaughtException` / `unhandledRejection` is also appended to this file. Stdout/stderr behaviour is unchanged. |
 

docs/08_capnweb_interface.md

@@ -6,16 +6,14 @@
 
 [capnweb](https://github.com/cloudflare/capnweb) is the RPC framing used
 between the Durable Object and the in-container `computerd` computerd.
-The wire format is text JSON over a single WebSocket (with an HTTP-batch
-alternative). The interface served is `WorkspaceRPC`, defined in
+The wire format is text JSON over a single WebSocket. The interface
+served is `WorkspaceRPC`, defined in
 `packages/rpc/src/interface.ts` and consumed by both sides.
 
 ## Transport
 
-- **Carrier.** One long-lived WebSocket per Workspace. The DO opens it
-  against the computerd's `/ws` endpoint, with `/api` available
-  as an HTTP-batch alternative (single POST per call) for callers that
-  can't hold a socket. Default port is `45678`; it will become a
+- **Carrier.** One long-lived WebSocket per Workspace, on the
+  computerd's `/api` endpoint. Default port is `45678`; it will become a
   build-time variable so hosts can pin a non-default port.
 - **Framing.** capnweb text frames. Binary frames are unsupported.
   **(planned)** the server will fail the session loudly on the first

docs/11_lifecycle.md

@@ -24,7 +24,7 @@ capnweb WebSocket session.
 │  │ Workspace           │  │                  │  │ computerd              │  │
 │  │  fs:  WorkspaceFS   │  │                  │  │  HTTP server     │  │
 │  │  shell: ShellRPC    │  │                  │  │   /health        │  │
-│  │  sync: SyncRPC      │◀─┼── capnweb WS ───▶│  │   /connect /ws   │  │
+│  │  sync: SyncRPC      │◀─┼── capnweb WS ───▶│  │  /connect /api   │  │
 │  │  push() / pull()    │  │                  │  │  FUSE mount      │  │
 │  │  ready()            │  │                  │  │  exec runner     │  │
 │  └──────────┬──────────┘  │                  │  └────────┬─────────┘  │
@@ -50,7 +50,7 @@ The 1:1 mapping is load-bearing for several reasons:
   doesn't have to multiplex multiple WS peers.
 
 The DO is the WebSocket *server* in this pairing, even though `computerd`
-exposes its own `/ws` server-side and could be dialed directly. The
+exposes its own `/api` server-side and could be dialed directly. The
 reason for the inversion is documented in
 [07. Injected Service §Bootstrap sequence](./07_injected_service.md):
 the egress interceptor needs to be wired before any traffic flows, and
@@ -90,7 +90,7 @@ an incarnation boundary. What survives is:
 
 On every new incarnation `Workspace.ready()` re-runs `#connect()`,
 which re-enters the backend's bootstrap sequence. If the container is
-still alive, the backend's `POST /connect` + `/ws` handshake produces
+still alive, the backend's `POST /connect` + `/api` handshake produces
 a fresh capnweb session against the same in-memory VFS on the
 container side. If the container died too (e.g. host OOM took both),
 the next sync round is a rev-0 baseline rebuild from the DO's store.
@@ -129,9 +129,9 @@ that point so the next call rebuilds from scratch (see the container host and ba
 
 The critical asymmetry: the **container's VFS is process-lifetime
 in-memory**, while the **DO's VFS is durable SQLite**. A container
-restart loses container-side state. Sync via `UPSTREAM_URL` (which
-the Cloudflare backend wires automatically) is what brings state back
-on the next push/pull round.
+restart loses container-side state. The durable object drives sync
+across the capnweb session it opens through `POST /connect`, and that
+is what brings state back on the next push/pull round.
 
 ## Capnweb lifecycle
 
@@ -373,7 +373,7 @@ between agent turns, and it's exactly where hibernation pays off.
 
 Adopting PartySocket for reconnect/backoff would require the DO
 to be the WebSocket *client* dialing `computerd`'s
-`/ws` endpoint. That model is appealing for reconnect, but
+`/api` endpoint. That model is appealing for reconnect, but
 hibernatable WebSockets only work server-side via
 `ctx.acceptWebSocket()` — there is no hibernation API for outbound
 client sockets. **Inverting the dial direction permanently forecloses

docs/README.md

@@ -87,7 +87,7 @@ To build the binary from source instead, run `npm run build:bin
 `artifacts/computerd/computerd-linux-x64`, then `COPY` that into the
 image.
 
-`computerd`'s own default port is `45678`; the Cloudflare container backend pins the in-image listener to `8080`, which is what `examples/container/` uses. See [07. Injected Service](./07_injected_service.md) for the env vars (`PORT`, `MOUNT_POINT`, `FUSE_MOUNT`, `UPSTREAM_URL`, `EXEC_LOG_MAX_BYTES`) and the reverse-dial boot sequence.
+`computerd`'s own default port is `45678`; the Cloudflare container backend pins the in-image listener to `8080`, which is what `examples/container/` uses. See [07. Injected Service](./07_injected_service.md) for the env vars (`PORT`, `MOUNT_POINT`, `FUSE_MOUNT`, `EXEC_LOG_MAX_BYTES`) and the reverse-dial boot sequence.
 
 ## Example
 

examples/container/README.md

@@ -21,7 +21,7 @@ client ─► Worker /c/<name>/{file,exec}
              ▼
        DO (ContainerExample) ──► Container ──► computerd (:8080)
              ▲                                  │
-             │      ws://computer.internal/ws  │
+             │      ws://computer.internal/api │
              └────────── capnweb session ◄──────┘
 ```
 
@@ -30,19 +30,20 @@ client ─► Worker /c/<name>/{file,exec}
    `Workspace` instance. That backend owns the entire computerd lifecycle:
    container start,
    outbound egress interception, port-readiness polling, POST
-   `/connect` to computerd, `/ws` upgrade routing, and capnweb session
+   `/connect` to computerd, `/api` upgrade routing, and capnweb session
    attach.
 2. computerd reaches the Worker through the container's **outbound
    interception** (`ctx.container.interceptOutboundHttp("computer.internal",
    …)`, set up by the backend). The DO passes
    `ctx.exports.WorkspaceProxy({ props: { binding, id } })` as the
    egress fetcher; that `WorkerEntrypoint` (re-exported from
-   `@cloudflare/computer`) routes `/ws` upgrades back to the owning DO.
+   `@cloudflare/computer`) routes `/api` upgrades back to the owning DO.
 3. When `Workspace.ready()` is called for the first time, the
    backend posts `/connect` into computerd with
-   `{ url: "http://computer.internal" }`. computerd polls
-   `computer.internal/health`, then dials
-   `ws://computer.internal/ws`.
+   `{ base: "http://computer.internal", health: "/health", api: "/api" }`.
+   computerd polls `computer.internal/health`, then dials
+   `ws://computer.internal/api`. Naming both paths in the request keeps
+   the daemon from assembling routes it does not serve.
 4. `WorkspaceProxy.fetch` forwards the upgrade to the DO's `fetch()`
    via the DO binding looked up from its props. The DO's `fetch()`
    delegates to `backend.handleFetch(req)`, which performs the

examples/container/src/index.ts

@@ -4,7 +4,7 @@
 // The DO is a thin shell over CloudflareContainerBackend: it picks
 // the container (this.ctx.container) and the egress fetcher
 // (ctx.exports.WorkspaceProxy bound to this DO instance), forwards
-// container-bound /ws upgrades back through the backend, and
+// container-bound /api upgrades back through the backend, and
 // otherwise just calls into a single Workspace instance.
 //
 // Wire shape:
@@ -14,7 +14,7 @@
 //              ▼
 //        ContainerExample DO ──► Container ──► computerd (:8080)
 //              ▲                                │
-//              │  ws://computer.internal/ws    │
+//              │  ws://computer.internal/api   │
 //              └─── capnweb session ◀─────────────┘
 
 import { DurableObject, tracing } from "cloudflare:workers";
@@ -92,7 +92,7 @@ function workspaceOptions(self: InstanceType<typeof ContainerBase>): WorkspaceOp
 // hands back round-trip into this DO; the actual SyncRPC + ShellRPC
 // traffic stays on the computerd ↔ DO capnweb wire.
 export class ContainerExample extends withWorkspace(ContainerBase, workspaceOptions) {
-  // ---- WebSocket: computerd's outbound /ws upgrade ---------------------
+  // ---- WebSocket: computerd's outbound /api upgrade --------------------
 
   override async fetch(request: Request): Promise<Response> {
     return this.backend.handleFetch(request);

examples/mcp/src/index.test.ts

@@ -26,7 +26,7 @@ describe("Computer Code Mode MCP", () => {
     expect(health.status).toBe(200);
     expect(await health.text()).toBe("ok\n");
 
-    const internal = await SELF.fetch("https://example.test/ws");
+    const internal = await SELF.fetch("https://example.test/api");
     expect(internal.status).toBe(404);
   });
 

examples/mcp/src/index.ts

@@ -60,7 +60,7 @@ export class ComputerMCP extends withWorkspace(ComputerMCPBase, workspaceOptions
     const path = new URL(request.url).pathname;
     // computerd reaches this callback through an internal binding. The public
     // Worker forwards only /mcp.
-    if (path === "/ws") return this.containerShell.handleFetch(request);
+    if (path === "/api") return this.containerShell.handleFetch(request);
     if (path !== "/mcp") return new Response("not found", { status: 404 });
 
     const unauthorized = authorize(request, this.env.MCP_TOKEN);