# Cloudflare Computer Runtime Types Explained: WorkspaceRuntime, RuntimeCall, and Backend Architecture

> Understand Cloudflare Computer runtime types: WorkspaceRuntime, RuntimeCall, and backend architecture. Learn about sandboxed, sticky code execution.

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

---

**Cloudflare Computer distinguishes between workspace-facing runtime abstractions (`WorkspaceRuntime`), RPC wire formats (`RuntimeCall`, `RuntimeResult`), and pluggable execution backends that together enable sandboxed, sticky code execution.**

The **Computer** package (`cloudflare/computer`) provides a modular runtime system for executing untrusted code safely. The architecture centers on TypeScript type contracts in `packages/computer/src/runtime/` that decouple the workspace API from concrete execution environments like worker JavaScript or container-based sandboxes.

## Runtime Types Overview

Cloudflare Computer organizes its runtime system into six core types, each defined in dedicated source files:

| Type | Purpose | Location |
|------|---------|----------|
| **`WorkspaceRuntime`** | Concrete class created by `Workspace` on demand; manages backends and public exec API | [`packages/computer/src/runtime/runtime.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/runtime.ts) |
| **`RuntimeCall`** | RPC payload shape for runtime commands, environment variables, and sticky routing | [`packages/computer/src/runtime/wire.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/wire.ts) |
| **`RuntimeResult`** | Execution result containing ID, status, stdout, stderr, and originating runtime | [`packages/computer/src/runtime/wire.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/wire.ts) |
| **`EgressConfig`** | Outbound HTTP permission rules (URLs, methods, timeouts) | [`packages/computer/src/runtime/egress.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/egress.ts) |
| **`Capability`** | Host resource handle (WASM, KV, D1) passed through RPC bridge | [`packages/computer/src/runtime/capability.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/capability.ts) |
| **`BridgeMessage`** | Low-level Cap'n Proto message carrying serialized calls and capability handles | [`packages/computer/src/runtime/bridge.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/bridge.ts) |

These types form strict contracts: any new backend implements the same `RuntimeCall`/`RuntimeResult` interface without requiring changes to higher-level code.

## WorkspaceRuntime: The Primary Interface

The **`WorkspaceRuntime`** class in [`runtime.ts`](https://github.com/cloudflare/computer/blob/main/runtime.ts) is the concrete runtime type that users interact with. It is lazily instantiated when `workspace.runtime` is first accessed.

**Key responsibilities:**
- Stores the selected backend (e.g., `worker-javascript`, `container-javascript`)
- Tracks `runtimeId` for sticky routing to the same execution context
- Exposes public methods: `exec()`, `getExec()`, `killExec()`, `disposeExec()`

```typescript
// Acquire workspace (created elsewhere)
const ws = await Workspace.create(...);

// WorkspaceRuntime created lazily on first .runtime access
const exec = await ws.runtime.exec(`echo "Hello from Cloudflare Computer!"`);

await exec.wait();
console.log(exec.stdout);  // → Hello from Cloudflare Computer!

```

The `exec()` method transforms parameters into a `RuntimeCall` and dispatches to the configured backend through the RPC bridge.

## Wire Types: RuntimeCall and RuntimeResult

The **`RuntimeCall`** and **`RuntimeResult`** interfaces in [`wire.ts`](https://github.com/cloudflare/computer/blob/main/wire.ts) define the RPC boundary between the workspace and sandboxed execution.

**RuntimeCall properties:**
- `command`: The executable command string
- `env`: Optional environment variable map
- `runtimeId`: String for sticky routing to existing runtime instances

**RuntimeResult properties:**
- `id`: Execution identifier
- `status`: Exit code or signal
- `stdout`, `stderr`: Captured output streams
- `runtimeId`: Backend instance that produced the result

**Sticky runtime example:**

```typescript
// First execution creates runtime, returns its ID
const first = await ws.runtime.exec(`node -e "console.log('first')"`);

// Force same runtime instance for subsequent call
const second = await ws.runtime.exec(
  `node -e "console.log('second')"`,
  { runtimeId: first.runtimeId }
);

```

This `runtimeId` mechanism enables stateful execution patterns where subsequent commands share filesystem, memory, or network bindings.

## Backend Abstraction and the Bridge

Concrete execution environments implement the same contract through **`BridgeMessage`** types. The **`BridgeMessage`** interface in [`bridge.ts`](https://github.com/cloudflare/computer/blob/main/bridge.ts) transports Cap'n Proto serialized data between the Durable Object host and sandboxed runtime.

**Execution flow:**
1. `WorkspaceRuntime.exec()` creates `RuntimeCall` payload
2. Bridge serializes message with capability handles
3. Backend (worker JavaScript, container, WASM) deserializes and executes
4. Result wrapped in `RuntimeResult` and returned through bridge

The **capability system** in [`capability.ts`](https://github.com/cloudflare/computer/blob/main/capability.ts) securely exposes host resources. When runtime code requests a KV read or WASM module, the capability object validates permissions before RPC forwarding.

**Egress validation** in [`egress.ts`](https://github.com/cloudflare/computer/blob/main/egress.ts) applies similar permission checks for outbound HTTP. User scripts can only fetch URLs matching the workspace's `EgressConfig` patterns:

```typescript
// Inside sandboxed script—succeeds only if policy permits
const resp = await fetch("https://api.example.com/data", {
  cf: { egress: { allowedUrls: ["https://api.example.com/*"] } }
});

```

## Extending Runtime Types

New backends require only three implementation steps:

1. **Implement `RuntimeCall` handler** — deserialize commands, execute in sandbox, capture output
2. **Return `RuntimeResult`** — package status, streams, and runtime ID
3. **Register in `WorkspaceRuntime`** — add backend identifier to runtime selection logic

The existing **container JavaScript** and **worker JavaScript** backends in the repository demonstrate this pattern. Unit tests in [`packages/computer/tests/runtime.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/tests/runtime.test.ts) verify contract compliance across backend implementations.

## Key Source Files

| File | Runtime Type | Purpose |
|------|-------------|---------|
| [`packages/computer/src/runtime/runtime.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/runtime.ts) | `WorkspaceRuntime` | Central runtime management and public API |
| [`packages/computer/src/runtime/wire.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/wire.ts) | `RuntimeCall`, `RuntimeResult` | RPC payload definitions |
| [`packages/computer/src/runtime/bridge.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/bridge.ts) | `BridgeMessage` | Cap'n Proto transport implementation |
| [`packages/computer/src/runtime/capability.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/capability.ts) | `Capability` | Host resource permission system |
| [`packages/computer/src/runtime/egress.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/egress.ts) | `EgressConfig` | Outbound HTTP policy validation |
| [`packages/computer/tests/runtime.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/tests/runtime.test.ts) | — | Contract compliance verification |

## Summary

- **`WorkspaceRuntime`** is the concrete, workspace-facing runtime class with lazy initialization and sticky execution support
- **`RuntimeCall`** and **`RuntimeResult`** in [`wire.ts`](https://github.com/cloudflare/computer/blob/main/wire.ts) define the strict RPC contract all backends must implement
- **`BridgeMessage`** enables Cap'n Proto transport with capability handle attachment for secure host resource access
- **`Capability`** and **`EgressConfig`** provide sandboxed I/O through validated permission checks
- The type system is deliberately minimal—adding backends (WASM, new container runtimes) requires only implementing the wire contract

## Frequently Asked Questions

### What is the difference between WorkspaceRuntime and RuntimeCall?

**`WorkspaceRuntime`** is the concrete class users interact with—it manages backend selection, tracks runtime IDs, and provides the `exec()` API. **`RuntimeCall`** is a plain data structure defining the RPC payload shape sent to backends, containing the command, environment, and routing ID. The workspace runtime creates `RuntimeCall` objects; backends consume them.

### How does sticky runtime execution work in Cloudflare Computer?

The `runtimeId` field in `RuntimeCall` enables sticky routing. When `exec()` returns, the `runtimeId` in `RuntimeResult` identifies the backend instance. Subsequent calls passing this same ID are routed to the identical execution context, preserving state between commands.

### What runtime backends are available in Cloudflare Computer?

The repository implements **worker JavaScript** and **container JavaScript** backends. Both implement the same `RuntimeCall`/`RuntimeResult` contract through the Cap'n Proto bridge. New backends (WebAssembly sandboxes, alternative container runtimes) can be added by implementing this interface.

### How does Cloudflare Computer restrict sandboxed code from making arbitrary network requests?

Outbound HTTP is controlled through **`EgressConfig`** validation in [`egress.ts`](https://github.com/cloudflare/computer/blob/main/egress.ts). Each runtime execution specifies permitted URL patterns, HTTP methods, and timeouts. The bridge rejects fetch calls targeting non-matching URLs before they reach the host network stack.