How the Worker Shell Backend Avoids a Second Store in Cloudflare Computer

The Worker Shell backend eliminates redundant persistence layers by using the Durable Object's SQLite database as the single authoritative store, explicitly declaring sync: "none" to disable all synchronization operations.

The cloudflare/computer repository implements a portable computing environment that runs inside Cloudflare Workers. When configuring the Worker Shell backend, the system deliberately avoids creating a second data store by treating the host Durable Object's SQLite database as the sole source of truth for all filesystem state.

Single-Store Architecture Design

The Worker Shell backend backs a Workspace with a simple Bash-style shell that runs inside a Dynamic Worker minted through env.LOADER. Instead of replicating data to a secondary persistence layer, the architecture delegates all storage operations directly to the Durable Object's SQLite database.

According to the source documentation in packages/computer/src/backends/worker-shell/index.ts, the backend explicitly notes that "the DO's SQLite is the single authoritative store" (lines 4-7). This design choice is further reinforced in the implementation header at packages/computer/src/backends/worker-shell/worker-shell.ts, which states: "Because there's no second store, the BackendHandle declares sync: 'none' (lines 16-18).

Disabling Synchronization Operations

By declaring itself as having no secondary store, the backend short-circuits the standard synchronization protocol that typically reconciles state between a workspace and its backing store.

Declaring sync: "none"

When connect() returns a BackendHandle, it explicitly sets the sync property to "none" (lines 70-78 in worker-shell.ts). This signals to the workspace that no initial watermark reconciliation should occur on connection, and that push/pull operations should be treated as no-ops.

Short-Circuiting Workspace Operations

Consequently, Workspace.push and Workspace.pull become short-circuiting no-ops. The initial watermark reconciliation that typically runs when establishing a connection is skipped entirely, eliminating network overhead and potential consistency issues between multiple stores.

Enforcing the Contract with noopSync()

The backend supplies a noopSync() implementation whose methods throw if called, enforcing the single-store contract at runtime. As implemented in packages/computer/src/backends/worker-shell/worker-shell.ts (lines 72-78), attempting to invoke synchronization methods results in an error: WorkerShellBackend: sync.push must not be called.

Implementation Example

To instantiate the Worker Shell backend with single-store semantics:

import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";

/* 1️⃣  Create a backend that uses the Durable Object's SQLite store */
const backend = new WorkerShellBackend({
  loader,                 // Dynamic Worker loader (env.LOADER)
  workspace,              // WorkspaceServiceProxy props for the DO
  ctx,                    // Durable Object context exposing WorkspaceServiceProxy
  // Optional: add extra command groups
  // commands: [SOME_SHELL_FEATURE],
});

/* 2️⃣  Connect the backend – the returned handle reports sync: "none" */
const handle = await backend.connect();
console.log(handle.sync); // → "none"

/* 3️⃣  Use the Workspace RPC – push/pull are no-ops */
await handle.rpc.shell.exec({ source: "echo hello" });
/* push / pull would throw if called:
   handle.rpc.sync.push(); // throws: WorkerShellBackend: sync.push must not be called
*/

Key Source Files

The single-store architecture is implemented across the following modules:

• packages/computer/src/backends/worker-shell/worker-shell.ts – Implements the backend logic, declares sync: "none", and provides the no-op sync RPC that throws on invalid access.

• packages/computer/src/backends/worker-shell/index.ts – Public API surface that documents the architectural guarantee that the Durable Object's SQLite serves as the sole store.

• packages/computer/src/backends/worker-shell/adapter.ts – Workspace adapter that forwards filesystem calls directly to the Durable Object's store without introducing additional persistence layers.

• examples/worker-shell/README.md – Practical example demonstrating how to instantiate WorkerShellBackend in production scenarios.

• docs/12_worker_backend.md – High-level design documentation describing the Worker backend architecture.

Summary

• The Worker Shell backend uses the Durable Object's SQLite database as the only persistence layer, eliminating the need for secondary storage.
• The BackendHandle explicitly sets sync: "none" to indicate that no synchronization protocol is required.
• Push and pull operations are converted to no-ops, and initial watermark reconciliation is skipped to improve performance.
• The noopSync() implementation enforces the single-store contract by throwing errors if synchronization methods are accidentally invoked.
• All filesystem operations performed by the shell are proxied back to the host Durable Object, maintaining data consistency through a single authoritative source.

Frequently Asked Questions

Why does the Worker Shell backend use sync: "none"?

The backend uses sync: "none" because it treats the host Durable Object's SQLite database as the single authoritative store. Since there is no secondary persistence layer to synchronize with, the standard push/pull reconciliation protocol would serve no purpose and is therefore disabled to reduce overhead and complexity.

What happens if sync.push() or sync.pull() is called?

If these methods are invoked, the noopSync() implementation throws an error with the message WorkerShellBackend: sync.push must not be called (or similar for pull). This runtime enforcement ensures that code cannot accidentally attempt to synchronize with a non-existent secondary store.

How does the backend persist data without a second store?

The backend delegates all filesystem operations to the Durable Object's SQLite database through the Workspace adapter. When the shell executes commands that modify the filesystem, these changes are proxied directly to the host Durable Object's storage, making the SQLite database the sole source of truth for all state.

Where is the single-store architecture documented in the source code?

The architecture is documented in packages/computer/src/backends/worker-shell/index.ts (lines 4-7) with the explicit comment that the Durable Object's SQLite is the single authoritative store. Implementation details appear in packages/computer/src/backends/worker-shell/worker-shell.ts (lines 16-18 and 70-78), which declare the sync: "none" property and implement the protective no-op handlers.

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