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

> Discover the @cloudflare/computer-rpc package, the essential layer connecting Cloudflare Durable Objects and the computerd process for command execution and filesystem sync via cap'n-proto.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: deep-dive
- Published: 2026-09-04

---

**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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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.

```typescript
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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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.

```typescript
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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/packages/rpc/src/server.ts) handles remote execution inside the `computerd` sandbox.
- **Driver helpers** `pushOnce` and `pullOnce` in [`packages/rpc/src/driver.ts`](https://github.com/cloudflare/computer/blob/main/packages/rpc/src/driver.ts) streamline virtual filesystem synchronization.
- **Debug utilities** in [`packages/rpc/src/debug.ts`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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.