# How to Instantiate and Use the Workspace Class in a Cloudflare Durable Object

> Learn to instantiate and use the Workspace class in a Cloudflare Durable Object. This essential wrapper connects your object to SQLite, computerd daemons, and backend services via a coordinated runtime API.

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

---

**The Workspace class acts as the primary host-side wrapper that enables Durable Objects to interact with local SQLite storage, remote `computerd` daemons, and backend services through a coordinated runtime API.**

In the `cloudflare/computer` repository, the `Workspace` class serves as the central façade for managing filesystem operations, command execution, and state synchronization within Cloudflare's edge computing environment. Whether you are building a remote development environment or a persistent file-backed service, understanding how to properly instantiate and configure this class inside a Durable Object is essential for leveraging the full capabilities of the computer package.

## Understanding the Workspace Architecture

The `Workspace` class coordinates multiple internal components to provide a unified interface for Durable Objects.

**Workspace** ([[`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts)](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts)) owns a `Database` backed by `ctx.storage` and a `WorkspaceFilesystem` instance. It manages synchronization with remote backends and provides access to execution runtimes.

**WorkspaceFilesystem** ([[`packages/dofs/src/fs/filesystem.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/fs/filesystem.ts)](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/fs/filesystem.ts)) implements a thin wrapper around the `@cloudflare/dofs` virtual filesystem, enabling direct SQLite-backed reads and writes to the local store.

**WorkspaceRuntime** ([[`packages/computer/src/runtime/runtime.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/runtime.ts)](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/runtime.ts)) exposes the `exec`, `getExec`, `killExec`, and `disposeExec` methods used to run commands on remote backends.

**WorkspaceStub** ([[`packages/computer/src/stub.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/stub.ts)](https://github.com/cloudflare/computer/blob/main/packages/computer/src/stub.ts)) provides an RPC-compatible shim that can cross Workers-RPC boundaries, allowing other Workers to interact with your Durable Object's Workspace instance.

## Instantiating the Workspace Class in a Durable Object

To create a `Workspace` instance inside a Durable Object, you must pass a `WorkspaceOptions` object to the constructor during initialization.

### Required Constructor Options

The constructor requires at minimum a `storage` field implementing `DurableObjectStorageLike`, which is typically the Durable Object's `ctx.storage`:

```typescript
export class MyDurableObject extends DurableObject {
  #workspace: Workspace;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.#workspace = new Workspace({
      storage: ctx.storage,
    });
  }
}

```

### Optional Configuration Fields

For production use, you will typically provide additional configuration:

- **backends**: An array of backend descriptors (e.g., command backends communicating with `computerd`)
- **sessionId**: An optional identifier propagating to mount factories, assets, and artifacts
- **mounts**: Optional mount registry for read-only or special-purpose VFS mounts
- **git**, **assets**, **artifacts**: Optional factories/clients lazily created on first use

```typescript
this.#workspace = new Workspace({
  storage: ctx.storage,
  backends: [env.COMPUTER_BACKEND],
  sessionId: ctx.id.toString(),
});

```

## Core Workspace Operations

Once instantiated, the Workspace provides methods for initialization, command execution, and data synchronization.

### Initializing with ready()

Call `ready()` to materialize mounts and optionally pre-warm backend connections before handling requests:

```typescript
async fetch(request: Request) {
  // Initialize all lazy-loaded resources
  await this.#workspace.ready({ all: true });
  return new Response("Workspace initialized");
}

```

### Executing Commands via the Runtime

The `WorkspaceRuntime` accessible via `workspace.runtime` provides the `exec()` method for running commands. This method automatically synchronizes state—pushing local changes before execution and pulling remote results afterward:

```typescript
async runScript() {
  const result = await this.#workspace.runtime.exec({
    source: "node -e \"console.log('executing on computerd')\"",
    timeoutMs: 5_000,
  });
  
  // Process the stream of WorkspaceRuntimeEvent objects
  for await (const event of result.events) {
    console.log(event);
  }
}

```

### Manual Synchronization with push() and pull()

For scenarios requiring explicit control over synchronization, use `push()` and `pull()`:

```typescript
async syncWorkspace() {
  // Push local SQLite changes to remote backend
  const pushed = await this.#workspace.push();
  console.log(`Synchronized ${pushed} entries to remote`);
  
  // Pull remote changes into local SQLite store
  const { applied, skipped } = await this.#workspace.pull();
  console.log(`Applied ${applied} remote entries, skipped ${skipped.length}`);
}

```

## Cross-Boundary RPC with WorkspaceStub

To allow other Workers to interact with your Workspace, return a `WorkspaceStub` from your Durable Object's methods. The stub forwards RPC calls across the Workers boundary while maintaining the Workspace's state:

```typescript
async fetch(request: Request) {
  const stub = this.#workspace.stub();
  return new Response(JSON.stringify({ workspaceStub: stub }));
}

```

The stub exposes methods like `push()`, `pull()`, and `runtime.exec()`, enabling distributed architectures where client Workers orchestrate operations on Durable Object-hosted Workspaces.

## Complete Durable Object Implementation Example

Here is a complete implementation demonstrating construction, command execution, and RPC exposure:

```typescript
import { DurableObject } from "cloudflare:workers";
import { Workspace } from "@cloudflare/computer";

export class ComputerDO extends DurableObject {
  #ws: Workspace;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.#ws = new Workspace({
      storage: ctx.storage,
      backends: [env.COMPUTER_BACKEND],
      sessionId: ctx.id.toString(),
    });
  }

  async fetch(request: Request) {
    await this.#ws.ready({ all: true });
    
    // Return RPC stub for cross-worker access
    if (new URL(request.url).pathname === "/stub") {
      return Response.json({ stub: this.#ws.stub() });
    }
    
    // Execute command directly within the DO
    const result = await this.#ws.runtime.exec({
      source: "uname -a",
      timeoutMs: 10_000,
    });
    
    return new Response(JSON.stringify({ result }));
  }

  async sync() {
    await this.#ws.push();
    await this.#ws.pull();
    return { status: "synchronized" };
  }
}

```

## Summary

- The `Workspace` class in `cloudflare/computer` wraps `ctx.storage` to provide SQLite-backed filesystem operations and remote command execution for Durable Objects.
- Instantiate `Workspace` by passing `ctx.storage` from the Durable Object constructor, optionally configuring backends, session IDs, and mount registries.
- Use `ready()` to initialize lazy-loaded resources, `runtime.exec()` to run commands with automatic sync, and `push()`/`pull()` for manual state synchronization.
- Return `workspace.stub()` from Durable Object methods to enable RPC access from other Workers.
- All filesystem operations hit the local SQLite store immediately; remote synchronization occurs explicitly via the sync methods or automatically during command execution.

## Frequently Asked Questions

### What storage backend does the Workspace class use?

The `Workspace` class uses the Durable Object's `ctx.storage` as its backing store, wrapping it in a `WorkspaceFilesystem` that provides SQLite-backed virtual filesystem operations. According to the source code in [`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts), the constructor requires a `storage` field implementing `DurableObjectStorageLike`, which is typically the storage object provided to the Durable Object's constructor.

### How does command execution handle state synchronization?

When you call `workspace.runtime.exec()`, the implementation automatically calls `push()` before executing the command to ensure the remote backend has the latest local state, then calls `pull()` after execution to retrieve any changes made by the command. This behavior is defined in the `WorkspaceRuntime` class within [`packages/computer/src/runtime/runtime.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/runtime.ts), ensuring consistency between the local SQLite store and remote `computerd` instances.

### Can I use the Workspace class outside of Durable Objects?

Yes, the `Workspace` class works in any Cloudflare Worker context provided you supply a valid `DurableObjectStorageLike` implementation. While designed for Durable Objects using `ctx.storage`, you can instantiate it with a test stub or custom storage implementation for use in standard Workers or testing environments, as demonstrated in the unit tests located in [`packages/computer/src/workspace.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.test.ts).

### What is the purpose of the WorkspaceStub?

`WorkspaceStub` serves as an RPC-compatible proxy that can cross the Workers-RPC boundary, allowing client Workers to invoke Workspace methods on a Durable Object-hosted instance. When you call `workspace.stub()`, you receive a serializable object (defined in [`packages/computer/src/stub.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/stub.ts)) that forwards `push()`, `pull()`, and `runtime.exec()` calls back to the original Workspace instance, enabling distributed architectures.