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

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
RuntimeCall	RPC payload shape for runtime commands, environment variables, and sticky routing	packages/computer/src/runtime/wire.ts
RuntimeResult	Execution result containing ID, status, stdout, stderr, and originating runtime	packages/computer/src/runtime/wire.ts
EgressConfig	Outbound HTTP permission rules (URLs, methods, timeouts)	packages/computer/src/runtime/egress.ts
Capability	Host resource handle (WASM, KV, D1) passed through RPC bridge	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

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 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()

// 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 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:

// 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 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 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 applies similar permission checks for outbound HTTP. User scripts can only fetch URLs matching the workspace's EgressConfig patterns:

// 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 verify contract compliance across backend implementations.

Key Source Files

File	Runtime Type	Purpose
packages/computer/src/runtime/runtime.ts	WorkspaceRuntime	Central runtime management and public API
packages/computer/src/runtime/wire.ts	RuntimeCall, RuntimeResult	RPC payload definitions
packages/computer/src/runtime/bridge.ts	BridgeMessage	Cap'n Proto transport implementation
packages/computer/src/runtime/capability.ts	Capability	Host resource permission system
packages/computer/src/runtime/egress.ts	EgressConfig	Outbound HTTP policy validation
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 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. 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.

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