# Pluggable Execution Backends for Cloudflare Computer: The Complete Developer Guide

> Explore Cloudflare Computer's six pluggable execution backends including container, worker, and sandbox options. Execute code efficiently across diverse environments using the Workspace.runtime.exec() API.

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

---

**Cloudflare Computer provides six pluggable execution backends—`container`, `container-shell`, `worker-javascript`, `worker-shell`, `sandbox`, and `command`—that implement a common runtime contract through the `Workspace.runtime.exec()` API, allowing developers to execute code in Docker containers, Cloudflare Workers, or in-process sandboxes depending on workload requirements.**

The cloudflare/computer repository implements a modular runtime system where pluggable execution backends determine exactly how user code is isolated and executed. Each backend adheres to the same abstract contract used by the central dispatcher, enabling you to swap between full OS containers, serverless JavaScript runtimes, or lightweight local execution without changing your application logic.

## Overview of the Execution Backend Architecture

At the core of the system is the `Workspace.runtime` dispatcher defined in [`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts). When you invoke `runtime.exec()`, the system consults the backend registry located at [`packages/computer/src/runtime/registry.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/registry.ts) to locate the appropriate implementation. All backends expose an identical interface, meaning you simply pass a `backend` option to select the execution environment.

This pluggable architecture makes it straightforward to add new execution targets (such as a WebAssembly-only runner) by implementing the same contract and registering the name in the backend registry.

## The Six Built-in Execution Backends

Cloudflare Computer ships with six distinct execution backends, each optimized for specific isolation, performance, or compatibility requirements.

### Container Backend

The **`container`** backend executes code inside a Docker-based container that provides a fully isolated Linux environment. It serves as the default production backend for workloads requiring complete OS-level sandboxing.

Implementation: [`packages/computer/src/backends/container/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/backends/container/index.ts)

### Container-Shell Backend

The **`container-shell`** backend is a lightweight variant of the container implementation that runs a shell command directly in the container image without launching a full runtime. This is useful for simple CLI interactions where you need container isolation but minimal overhead.

Implementation: [`packages/computer/src/backends/container/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/backends/container/index.ts) (same module, different entry-point)

### Worker-JavaScript Backend

The **`worker-javascript`** backend runs JavaScript modules inside the Cloudflare Workers runtime. It offers fast cold-start performance and native access to Workers-only APIs, making it ideal for edge-deployed logic.

Implementation: [`packages/computer/src/backends/worker-javascript/worker-javascript.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/backends/worker-javascript/worker-javascript.ts)

### Worker-Shell Backend

The **`worker-shell`** backend executes commands in the Workers environment via a shell shim. It allows scripts that require a shell-style interface to run while remaining inside the Workers runtime sandbox.

Implementation: [`packages/computer/src/backends/worker-shell/worker-shell.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/backends/worker-shell/worker-shell.ts)

### Sandbox Backend

The **`sandbox`** backend provides a minimal in-process sandbox used primarily for unit-test isolation. Because it does not spawn external processes, it executes significantly faster than container-based options, though with reduced isolation guarantees.

Implementation: [`packages/computer/src/backends/sandbox.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/backends/sandbox.ts) (created on-demand when referenced)

### Command Backend

The **`command`** backend is a generic exec implementation that forwards commands to the host OS (`/bin/sh`) when the current environment permits. It is primarily utilized by the test suite and for local debugging scenarios where full container isolation is unnecessary.

Implementation: [`packages/computer/src/backends/command.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/backends/command.ts)

## How to Select and Configure a Backend

You specify the execution backend by passing the `backend` option to `Workspace.runtime.exec()`. If no backend is specified, the system defaults to the container backend for production workloads.

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

async function demo(ws: Workspace) {
  // Run inside a Docker container (default production backend)
  const containerResult = await ws.runtime.exec("ls -la", {
    backend: "container",
  });
  console.log("container:", containerResult.stdout);

  // Run JavaScript inside Cloudflare Workers
  const jsResult = await ws.runtime.exec("export default 42", {
    backend: "worker-javascript",
  });
  console.log("worker-js:", jsResult.stdout);

  // Execute shell command via Workers shim
  const shellResult = await ws.runtime.exec("echo hello", {
    backend: "worker-shell",
  });
  console.log("worker-shell:", shellResult.stdout);
}

```

For fast unit-test style execution without external dependencies, use the sandbox backend:

```typescript
await ws.runtime.exec("node -e 'console.log(1+2)'", {
  backend: "sandbox",   // In-process execution, no container spawn
});

```

## Extending with Custom Backends

You can extend the system by implementing the backend interface and registering your implementation with the runtime registry. This allows you to add specialized execution environments (for example, a WASM-only runner) while maintaining compatibility with the existing `Workspace.runtime.exec()` API.

```typescript
import { registerBackend } from "@cloudflare/computer/runtime";

class MySpecialBackend {
  async exec(command: string, opts: any) {
    // Custom execution logic
    return { stdout: "custom", exitCode: 0 };
  }
}

registerBackend("my-special", new MySpecialBackend());

// Use your custom backend
await ws.runtime.exec("do-something", { backend: "my-special" });

```

## Summary

- **Six built-in backends**: Cloudflare Computer ships with `container`, `container-shell`, `worker-javascript`, `worker-shell`, `sandbox`, and `command` execution backends.
- **Common contract**: All backends implement the same interface used by `Workspace.runtime.exec()` in [`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts).
- **Registry pattern**: The dispatcher looks up implementations via [`packages/computer/src/runtime/registry.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/registry.ts) based on the `backend` option you provide.
- **Isolation levels**: Choose `container` for full OS isolation, `worker-javascript` for fast edge execution, or `sandbox` for lightweight in-process testing.
- **Extensible design**: New backends can be registered via `registerBackend()` to support custom execution environments.

## Frequently Asked Questions

### What is the default execution backend for Cloudflare Computer?

The **`container`** backend is the default production execution environment. It provides a Docker-based Linux sandbox and is automatically selected when you call `Workspace.runtime.exec()` without specifying a `backend` option, as implemented in [`packages/computer/src/backends/container/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/backends/container/index.ts).

### How do I switch between execution backends at runtime?

Pass the **`backend`** option to the `Workspace.runtime.exec()` method. The value should be a string matching one of the registered backend names (e.g., `backend: "worker-javascript"` or `backend: "sandbox"`). The runtime registry in [`packages/computer/src/runtime/registry.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/registry.ts) resolves this name to the concrete implementation.

### Which backend should I use for unit testing?

Use the **`sandbox`** backend for unit tests. Defined in [`packages/computer/src/backends/sandbox.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/backends/sandbox.ts), this backend runs code in-process without spawning external containers or processes, providing fast execution speeds suitable for test suites while maintaining basic isolation.

### Can I create custom execution backends for Cloudflare Computer?

Yes. You can implement the backend contract (an `exec()` method accepting a command string and options) and register it using `registerBackend()` from `@cloudflare/computer/runtime`. Once registered, your custom backend can be selected via the `backend` option just like the built-in container or Workers implementations.