What Is @cloudflare/computer-rpc? Inside Cloudflare Computer's RPC Layer

The @cloudflare/computer-rpc package is the core Remote Procedure Call (RPC) layer that connects a Cloudflare Durable Object (the "workspace" server) with the computerd process running inside a sandbox container, implementing a cap'n-proto-based protocol for command execution and filesystem synchronization.

The @cloudflare/computer-rpc package forms the communication backbone of the Cloudflare Computer environment. It defines the typed contract used for all messages between client-side front-end code and the back-end container that executes shell commands. According to the cloudflare/computer source code, this package encapsulates the wire protocol, client-side API, and server-side handlers that enable real-time streaming of command output and virtual filesystem (VFS) operations.

Core Architecture and Responsibilities

The package serves five primary functions within the Cloudflare Computer stack.

• Defining the public RPC surface. Located in packages/rpc/src/index.ts, this module exports the core type definitions including ShellRPC, SyncRPC, WorkspaceRPC, and the ExecEvent shape. These TypeScript interfaces describe how clients invoke shell commands, synchronize the virtual filesystem, and receive streamed execution events.

• Providing client helpers. The packages/rpc/src/client.ts file implements createWorkspaceClient, which instantiates a ready-to-use RPC client that communicates with the Durable Object via WebSocket.

• Implementing the server side. In packages/rpc/src/server.ts, the functions acceptWebSocketSession and createWorkspaceServer spin up the RPC server inside the computerd process, handling incoming RPC calls and forwarding them to internal services.

• Exposing driver utilities. The packages/rpc/src/driver.ts entry point contains high-level helpers like pushOnce and pullOnce that perform single sync cycles between client and server, simplifying the typical "push-then-pull" workflow.

• Supplying debug utilities. The packages/rpc/src/debug.ts module provides tools for tracking stub lifetimes and taking snapshots of RPC state, essential for testing and troubleshooting.

Public RPC Types and Protocol Definitions

The foundation of the communication layer resides in packages/rpc/src/index.ts. This file exports the cap'n-proto-derived TypeScript definitions that enforce type safety across the wire.

Key exported types include:

• WorkspaceRPC: Defines the top-level interface for workspace management operations.
• ShellRPC: Specifies the methods available for shell command execution, including process spawning and signal handling.
• SyncRPC: Handles virtual filesystem synchronization between the client view and the remote container.
• ExecEvent: Describes the shape of streamed execution events, including stdout, stderr, and exit codes.

These types ensure that both the client and server agree on the structure of every message exchanged over the WebSocket connection.

Client-Side Implementation

Front-end code interacts with the Computer environment through the client module defined in packages/rpc/src/client.ts. The primary entry point is createWorkspaceClient, which accepts a configuration object containing the WebSocket URL of the Durable Object and returns a typed client instance.

import { createWorkspaceClient } from "@cloudflare/computer-rpc/client";

const client = await createWorkspaceClient({
  url: "wss://example.com/api",
});

const { shell } = await client.workspace();
const exec = await shell.exec({ cmd: ["ls", "-l"], cwd: "/" });

for await (const ev of exec.events) {
  if (ev.type === "stdout") console.log(ev.data);
  if (ev.type === "stderr") console.error(ev.data);
  if (ev.type === "exit") console.log(`exit code ${ev.code}`);
}

The client abstracts the underlying WebSocket transport and cap'n-proto serialization, presenting a clean Promise-based API for command execution and event streaming.

Server-Side RPC Handling

On the container side, packages/rpc/src/server.ts implements the RPC server that runs inside the computerd process. The createWorkspaceServer function initializes the server instance, while acceptWebSocketSession handles incoming WebSocket upgrade requests from clients.

These functions deserialize incoming cap'n-proto messages, route them to the appropriate internal services (such as the shell executor or VFS driver), and serialize responses back to the client. The server implementation ensures that commands execute within the sandboxed environment and that filesystem changes propagate correctly to the client.

Driver Utilities for Filesystem Synchronization

The packages/rpc/src/driver.ts module simplifies common synchronization patterns through high-level helper functions. Rather than manually managing the sync protocol, developers can use:

• pushOnce(client): Uploads local filesystem changes to the remote workspace in a single operation.
• pullOnce(client): Downloads remote filesystem changes to the local view.

import { createWorkspaceClient } from "@cloudflare/computer-rpc/client";
import { pushOnce, pullOnce } from "@cloudflare/computer-rpc/driver";

const client = await createWorkspaceClient({ url: "wss://example.com/api" });

await pushOnce(client);
await pullOnce(client);

These utilities manage the complex handshake required to reconcile file system state between the client and the remote container, handling conflict resolution and batching optimizations automatically.

Debugging and Development Tools

When building applications on top of @cloudflare/computer-rpc, the packages/rpc/src/debug.ts module provides essential diagnostic capabilities. It exports utilities for tracking the lifecycle of RPC stubs (capability references) and capturing snapshots of the current RPC state.

These tools prove particularly valuable when writing unit tests for RPC clients or diagnosing connection leaks and capability retention issues in long-running workspace sessions.

Summary

The @cloudflare/computer-rpc package delivers the complete communication infrastructure for Cloudflare Computer:

• Type definitions in packages/rpc/src/index.ts establish the cap'n-proto-based contract for ShellRPC, SyncRPC, and WorkspaceRPC.
• Client functionality via createWorkspaceClient in packages/rpc/src/client.ts enables WebSocket-based communication from front-end code.
• Server implementation through acceptWebSocketSession and createWorkspaceServer in packages/rpc/src/server.ts handles remote execution inside the computerd sandbox.
• Driver helpers pushOnce and pullOnce in packages/rpc/src/driver.ts streamline virtual filesystem synchronization.
• Debug utilities in packages/rpc/src/debug.ts support testing and troubleshooting of RPC connections.

Frequently Asked Questions

How does @cloudflare/computer-rpc handle communication between client and server?

The package uses WebSocket connections to transport cap'n-proto serialized messages between the client-side Durable Object and the server-side computerd process. The createWorkspaceClient function establishes the client connection, while acceptWebSocketSession handles server-side session acceptance, enabling bidirectional streaming of commands and filesystem events.

What are the main RPC interfaces exposed by the package?

According to packages/rpc/src/index.ts, the primary interfaces are WorkspaceRPC for workspace management, ShellRPC for command execution, and SyncRPC for filesystem operations. The ExecEvent type defines the structure of streamed output events including stdout, stderr, and exit status codes.

Can I use the driver utilities for one-off synchronization tasks?

Yes. The packages/rpc/src/driver.ts module exports pushOnce and pullOnce specifically for single-step synchronization workflows. These functions wrap the lower-level SyncRPC calls and handle the full handshake cycle, making them ideal for scripts or applications that need to sync state without managing the persistent connection manually.

What debugging tools does @cloudflare/computer-rpc provide?

The packages/rpc/src/debug.ts file contains utilities for tracking stub lifetimes and capturing RPC state snapshots. These tools help developers identify capability leaks, monitor connection health, and debug serialization errors during development and testing phases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}