# How Cloudflare Computer Runtime Types Work: A Complete Technical Guide

> Explore Cloudflare Computer runtime types. Learn how this pluggable TypeScript abstraction manages code execution, RPC communication, and sandboxed backends for your workspace.

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

---

**Cloudflare Computer runtime types are a pluggable TypeScript abstraction that defines how the workspace launches code execution, communicates over RPC, and manages sandboxed backends through a small set of contract types.**

The **Computer** package provides a flexible execution environment where runtimes act as thin adapters between your workspace and various backends. The entire runtime type system lives in `packages/computer/src/runtime/` and enables safe, sandboxed code execution with controlled I/O capabilities.

## Core Runtime Types Explained

The runtime architecture centers on six key TypeScript types that establish contracts across the RPC boundary.

### WorkspaceRuntime: The Main Controller

**`WorkspaceRuntime`** is the concrete class instantiated when you access `workspace.runtime`. Located in [`packages/computer/src/runtime/runtime.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/runtime.ts), it manages backend selection, tracks runtime IDs for sticky routing, and exposes the public API.

Key methods include:
- `exec()` — launches a new execution
- `getExec()` — retrieves an existing exec by ID
- `killExec()` — terminates a running process
- `disposeExec()` — cleans up resources

The class lazy-initializes on first use and maintains the `runtimeId` for session affinity.

### RuntimeCall and RuntimeResult: The RPC Contract

In [`packages/computer/src/runtime/wire.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/wire.ts), two types define the message format:

**`RuntimeCall`** — sent to the backend:

```typescript
{
  command: string;           // code or command to execute
  env?: Record<string, string>;  // environment variables
  runtimeId?: string;        // for sticky routing to same container/worker
}

```

**`RuntimeResult`** — returned from the backend:

```typescript
{
  id: string;               // exec identifier
  status: 'pending' | 'running' | 'success' | 'error';
  stdout: string;
  stderr: string;
  runtimeId: string;        // identifies which backend instance ran this
}

```

These wire types keep the RPC layer agnostic to backend implementation details.

### BridgeMessage: Low-Level Transport

**`BridgeMessage`** in [`packages/computer/src/runtime/bridge.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/bridge.ts) wraps serialized `RuntimeCall` and `RuntimeResult` objects for Cap'n Proto transport. It carries capability handles across the boundary between the Durable Object and sandboxed runtime.

### Capability and EgressConfig: Sandboxed I/O

**`Capability`** ([`packages/computer/src/runtime/capability.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/capability.ts)) represents host resources a runtime may request—WASM modules, KV bindings, D1 databases. The capability object passes through the RPC bridge so the runtime can invoke host-side resources safely.

**`EgressConfig`** ([`packages/computer/src/runtime/egress.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/egress.ts)) configures permitted outbound HTTP requests:
- Allowed URL patterns
- Permitted HTTP methods
- Request timeouts and limits

This dual system keeps runtimes sandboxed while enabling controlled external access.

## How Runtime Types Work Together

The execution flow follows four stages:

1. **Workspace initiates execution** — `workspace.runtime.exec()` creates a `WorkspaceRuntime` instance and serializes the call to `RuntimeCall`.

2. **Backend receives and spawns** — `WorkspaceRuntime` routes to the configured backend (worker-javascript, container-javascript, etc.) via the RPC bridge using `BridgeMessage`.

3. **Execution and capture** — The backend runs user code, streams stdout/stderr, and eventually returns a `RuntimeResult`.

4. **Capability validation** — Any resource requests or egress calls pass through `Capability` and `EgressConfig` validation before reaching host services.

## Practical Code Examples

### Basic Execution with Default Runtime

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

// Create or connect to a workspace
const ws = await Workspace.create({
  name: 'my-project',
  backend: 'worker-javascript',
});

// Execute code — runtime created lazily on first use
const exec = await ws.runtime.exec(`console.log("Hello from Cloudflare Computer!")`);

// Wait for completion and read output
await exec.wait();
console.log(exec.stdout);  // → Hello from Cloudflare Computer!

```

### Sticky Runtime Sessions

```typescript
// First exec creates a runtime and returns its ID
const first = await ws.runtime.exec(`node -e "console.log('instance A')"`);
console.log(first.runtimeId);  // e.g., "wrkr-abc123"

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

```

### Configuring Egress Policy

```typescript
// Workspace-level egress configuration
const ws = await Workspace.create({
  name: 'api-consumer',
  egress: {
    allowedUrls: ['https://api.example.com/*'],
    allowedMethods: ['GET', 'POST'],
    maxRequestDuration: 30000,
  },
});

// Runtime fetch requests are validated against this policy
const exec = await ws.runtime.exec(`
  fetch('https://api.example.com/data')
    .then(r => r.json())
    .then(data => console.log(JSON.stringify(data)))
`);

```

## Source File Reference

| File | Purpose |
|------|---------|
| [`packages/computer/src/runtime/runtime.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/runtime.ts) | `WorkspaceRuntime` class — backend 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` wire format types |
| [`packages/computer/src/runtime/bridge.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/bridge.ts) | `BridgeMessage` and 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` type for host resource access |
| [`packages/computer/src/runtime/egress.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/egress.ts) | `EgressConfig` and outbound request validation |
| [`packages/computer/tests/runtime.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/tests/runtime.test.ts) | Unit tests covering runtime lifecycle and type contracts |

## Extending the Runtime System

Adding a new backend requires only:

1. Implementing the `RuntimeCall` → `RuntimeResult` contract
2. Wiring into `WorkspaceRuntime` backend selection
3. Handling `Capability` and `EgressConfig` validation in your bridge implementation

All higher-level code—tests, examples, and the RPC layer—continues to work unchanged because the type contracts remain stable.

## Summary

- **`WorkspaceRuntime`** in [`runtime.ts`](https://github.com/cloudflare/computer/blob/main/runtime.ts) is the primary interface for creating and managing executions
- **`RuntimeCall`** and **`RuntimeResult`** in [`wire.ts`](https://github.com/cloudflare/computer/blob/main/wire.ts) define the stable RPC contract between workspace and backend
- **`BridgeMessage`** in [`bridge.ts`](https://github.com/cloudflare/computer/blob/main/bridge.ts) handles low-level Cap'n Proto transport with capability handles
- **`Capability`** and **`EgressConfig`** enable sandboxed I/O with explicit host-controlled permissions
- The minimal type surface makes backend extensions straightforward without breaking existing code

## Frequently Asked Questions

### What is a runtime ID in Cloudflare Computer?

A **runtime ID** is a string identifier returned in every `RuntimeResult` that uniquely identifies the backend instance (worker or container) that executed your code. Pass this ID to subsequent `exec()` calls using the `runtimeId` option to maintain session affinity—useful for preserving filesystem state or connection pools across multiple executions.

### How does Cloudflare Computer keep runtimes secure?

Security operates at multiple layers: the **capability** system ([`capability.ts`](https://github.com/cloudflare/computer/blob/main/capability.ts)) requires explicit host grants for resources like KV or D1, while **egress configuration** ([`egress.ts`](https://github.com/cloudflare/computer/blob/main/egress.ts)) whitelists outbound URLs and methods. The RPC bridge validates all capability and egress requests before forwarding them, ensuring sandboxed code cannot access unapproved resources.

### Can I use Cloudflare Computer runtime types with custom backends?

Yes. The runtime type system is deliberately backend-agnostic. Implement the `RuntimeCall`/`RuntimeResult` contract, wire your backend into `WorkspaceRuntime`'s backend selection logic, and handle `BridgeMessage` transport. The existing test suite in [`tests/runtime.test.ts`](https://github.com/cloudflare/computer/blob/main/tests/runtime.test.ts) validates that new backends conform to expected type contracts.

### Where are runtime results stored during execution?

`RuntimeResult` objects are not persisted to disk by default. The `WorkspaceRuntime` class holds exec state in memory and streams stdout/stderr through the active RPC connection. For result durability, your application code must capture and store the returned `RuntimeResult` or exec object before the workspace or Durable Object terminates.