# Cloudflare Computer Core Runtime Types Explained: A Complete API Reference

> Explore Cloudflare Computer core runtime types in this comprehensive API reference. Understand execution, filesystem, events, and lifecycle management for worker-like workspaces.

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

---

**The Cloudflare Computer core runtime types are a compact TypeScript type system defined in [`packages/computer/src/runtime/types.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/types.ts) that model execution environment primitives, filesystem operations, event streaming, and lifecycle management for worker-like workspaces.**

Cloudflare Computer exposes a strongly-typed runtime API that lets developers programmatically execute code, stream output, manipulate virtual filesystems, and manage execution lifecycles. These **core runtime types** form the contract between the high-level `WorkspaceRuntime` class and the underlying backend implementations. This guide walks through every type, its purpose, and how to use it in practice.

## What Are Core Runtime Types?

In Cloudflare Computer, **core runtime types** are TypeScript interfaces and type aliases that describe:

- Values that can cross the execution boundary
- Filesystem operations available in a workspace
- Configuration for code loading and execution
- Event streams and final results from running processes
- Backend routing and lifecycle control

These types live in [`packages/computer/src/runtime/types.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/types.ts) and are consumed by `WorkspaceRuntime` in [`packages/computer/src/runtime/runtime.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/runtime.ts).

## Primitive Value Types

### WorkspaceRuntimeValue

The `WorkspaceRuntimeValue` type defines what data can be passed to or returned from a runtime execution. It is a union of JSON-compatible primitives.

```typescript
// packages/computer/src/runtime/types.ts#L16-L22
type WorkspaceRuntimeValue =
  | undefined
  | null
  | boolean
  | number
  | string
  | WorkspaceRuntimeValue[]
  | { [key: string]: WorkspaceRuntimeValue };

```

This recursive definition allows nested arrays and plain objects, but excludes functions, class instances, and other non-serializable JavaScript values.

## Filesystem Types

### WorkspaceRuntimeStat

File metadata is represented by `WorkspaceRuntimeStat`, which mirrors POSIX `stat` information.

```typescript
// packages/computer/src/runtime/types.ts#L24-L33
interface WorkspaceRuntimeStat {
  dev: number;
  ino: number;
  mode: number;
  nlink: number;
  uid: number;
  gid: number;
  size: number;
  type: "file" | "directory" | "symlink" | "other";
  atime: Date;
  mtime: Date;
  ctime: Date;
  birthtime: Date;
}

```

### WorkspaceRuntimeFilesystem

The `WorkspaceRuntimeFilesystem` interface exposes asynchronous filesystem operations. This is the primary abstraction for workspace file manipulation.

```typescript
// packages/computer/src/runtime/types.ts#L35-L68
interface WorkspaceRuntimeFilesystem {
  readFile(path: string): Promise<Uint8Array>;
  stat(path: string): Promise<WorkspaceRuntimeStat>;
  readdir(
    path: string,
    options?: { limit?: number }
  ): Promise<{ name: string; isDirectory: boolean; isFile: boolean; isSymlink: boolean }[]>;
  grep(pattern: string, options?: { path?: string; limit?: number }): Promise<string[]>;
  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
  writeFile(path: string, content: Uint8Array | string): Promise<void>;
  // ... additional methods
}

```

The `grep` method is notable—Cloudflare Computer includes content search as a first-class filesystem operation, optimized for the underlying storage backend.

## Execution Configuration Types

### WorkspaceRuntimeLoader

Before code runs, it must be loaded. The `WorkspaceRuntimeLoader` type describes this contract.

```typescript
// packages/computer/src/runtime/types.ts#L70-L80
interface WorkspaceRuntimeLoader {
  compatibilityDate: string;
  compatibilityFlags: string[];
  limits?: {
    cpuMs?: number;
    memoryMb?: number;
  };
  modules: Map<string, string>;
  outboundFetcher?: typeof fetch;
}

```

Key fields include:
- **compatibilityDate** and **compatibilityFlags** – control runtime behavior versioning
- **limits** – enforce resource caps on execution
- **modules** – map module specifiers to source code
- **outboundFetcher** – optional custom fetch implementation for external requests

### WorkspaceRuntimeExecOptions

When calling `WorkspaceRuntime.exec()`, you pass `WorkspaceRuntimeExecOptions` to configure the execution.

```typescript
// packages/computer/src/runtime/types.ts#L104-L113
interface WorkspaceRuntimeExecOptions<E extends "utf8" | "bytes" = "bytes"> {
  backend?: string;
  cwd?: string;
  env?: Record<string, string>;
  value?: WorkspaceRuntimeValue;
  timeout?: number;
  encoding?: E;
}

```

The generic `E` parameter determines whether stdout/stderr are returned as **strings** (`"utf8"`) or **raw bytes** (`"bytes"`).

## Event and Result Types

### WorkspaceRuntimeEvent

Executions emit events through a stream. The `WorkspaceRuntimeEvent` type is a discriminated union of `stdout`, `stderr`, and `exit` events.

```typescript
// packages/computer/src/runtime/types.ts#L87-L90
type WorkspaceRuntimeEvent<E extends "utf8" | "bytes"> =
  | { name: "stdout"; value: E extends "utf8" ? string : Uint8Array }
  | { name: "stderr"; value: E extends "utf8" ? string : Uint8Array }
  | { name: "exit"; code: number };

```

The conditional type on `value` ensures type-safe encoding: when `E` is `"utf8"`, you get strings; otherwise, you get `Uint8Array`.

### WorkspaceRuntimeResult

After execution completes, `WorkspaceRuntimeResult` aggregates all output and metadata.

```typescript
// packages/computer/src/runtime/types.ts#L92-L100
interface WorkspaceRuntimeResult<E extends "utf8" | "bytes"> {
  status: WorkspaceRuntimeStatus;
  exitCode: number;
  stdout: (E extends "utf8" ? string : Uint8Array)[];
  stderr: (E extends "utf8" ? string : Uint8Array)[];
  value?: WorkspaceRuntimeValue;
  stats?: {
    cpuMs: number;
    memoryMb: number;
  };
}

```

### WorkspaceRuntimeStatus

Execution final states are enumerated by `WorkspaceRuntimeStatus`.

```typescript
// packages/computer/src/runtime/types.ts#L83
type WorkspaceRuntimeStatus = "completed" | "failed" | "cancelled";

```

## Execution Handle Types

### WorkspaceRuntimeExecHandle

The return value of `WorkspaceRuntime.exec()` is a `WorkspaceRuntimeExecHandle`—a `ReadableStream` of events with additional control methods.

```typescript
// packages/computer/src/runtime/types.ts#L130-L137
interface WorkspaceRuntimeExecHandle<E extends "utf8" | "bytes">
  extends ReadableStream<WorkspaceRuntimeEvent<E>> {
  id: string;
  backend: string;
  result(): Promise<WorkspaceRuntimeResult<E>>;
  kill(signal?: string): Promise<void>;
  [Symbol.dispose](): void;
}

```

This type implements the **async disposable pattern** via `[Symbol.dispose]`, enabling `using` declarations in modern TypeScript.

## Lifecycle and Control Types

| Type | Purpose | Key Fields |
|------|---------|------------|
| `WorkspaceRuntimeGetOptions<E>` | Retrieve a prior execution | `tail`, `replay`, `backend`, `encoding` |
| `WorkspaceRuntimeKillOptions` | Terminate a running process | `backend`, `signal` |
| `WorkspaceRuntimeDisposeOptions` | Clean up execution resources | `backend` |

## Backend Module Types

### ModuleExecutionInput and ModuleExecutionEnvelope

For lower-level backend communication, these types structure the payload when starting or querying executions.

```typescript
// packages/computer/src/runtime/types.ts#L139-L147
interface ModuleExecutionInput {
  script: string;
  loader: WorkspaceRuntimeLoader;
  options: WorkspaceRuntimeExecOptions;
}

// packages/computer/src/runtime/types.ts#L149-L165
interface ModuleExecutionEnvelope {
  id: string;
  status: WorkspaceRuntimeStatus;
  events: WorkspaceRuntimeEvent[];
  result?: WorkspaceRuntimeResult;
}

```

### WorkspaceModuleBackend Types

The backend routing layer uses several related types (defined at `packages/computer/src/runtime/types.ts#L167-L191`) to describe protocol, connection, and handle abstractions for the "module" backend that executes code.

## Practical Usage Example

```typescript
// Example: Creating a runtime and executing code
import { WorkspaceRuntime } from "@cloudflare/computer/runtime";

const runtime = new WorkspaceRuntime({
  callableBackendIds: new Set(["node"]),
  backendHandle: async (id) => /* obtain backend handle */,
  resolveBackendId: (id) => id ?? "node",
});

// Stream execution output
const handle = await runtime.exec(
  `export default async function() { console.log("Hello from Computer!"); }`,
  { encoding: "utf8" }
);

for await (const event of handle) {
  if (event.name === "stdout") console.log(event.value);
}

// Or get final result directly
const result = await handle.result();
console.log(`Exited with code ${result.exitCode}`);

```

## Key Files in the Runtime System

| File | Role |
|------|------|
| [`packages/computer/src/runtime/types.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/types.ts) | Central type definitions for all runtime interfaces |
| [`packages/computer/src/runtime/runtime.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/runtime.ts) | `WorkspaceRuntime` implementation using these types |
| [`packages/computer/src/runtime/wire.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/wire.ts) | Cap'n Proto wire encoding for Durable Object communication |
| [`packages/computer/src/backend.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/backend.ts) | Abstract `WorkspaceBackend` interface for concrete backends |

## Summary

- **`WorkspaceRuntimeValue`** – serializable data boundary for execution input/output
- **`WorkspaceRuntimeFilesystem`** – async filesystem abstraction with search capabilities
- **`WorkspaceRuntimeLoader`** – code loading contract with compatibility flags and limits
- **`WorkspaceRuntimeEvent<E>`** and **`WorkspaceRuntimeResult<E>`** – streaming and aggregated execution output
- **`WorkspaceRuntimeExecHandle<E>`** – event stream with lifecycle control methods
- **Module backend types** – lower-level payload structures for backend communication

These types are implemented in [`packages/computer/src/runtime/types.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/types.ts) and consumed by the `WorkspaceRuntime` class in [`packages/computer/src/runtime/runtime.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/runtime.ts).

## Frequently Asked Questions

### How does encoding affect the return types in Cloudflare Computer?

The `encoding` option in `WorkspaceRuntimeExecOptions` is a generic parameter that propagates through `WorkspaceRuntimeEvent` and `WorkspaceRuntimeResult`. When set to `"utf8"`, stdout and stderr values are `string` types; with `"bytes"` (the default), they are `Uint8Array`. This is enforced at the type level using TypeScript conditional types.

### What is the difference between streaming events and calling result()?

Streaming via `for await...of` on the `WorkspaceRuntimeExecHandle` yields events as they occur, enabling real-time output processing. Calling `await handle.result()` returns the final aggregated result and may skip streaming entirely by replaying stored execution data. The latter is more efficient when you only need complete output after execution finishes.

### Can I customize the fetch implementation for outbound requests?

Yes. Pass an `outboundFetcher` function in the `WorkspaceRuntimeLoader` configuration. This replaces the default `fetch` global for code running in the workspace, allowing request interception, logging, or proxying through custom infrastructure.

### What backends does Cloudflare Computer support?

The runtime uses a pluggable backend system. The `callableBackendIds` set in `WorkspaceRuntime` constructor options registers which backends accept structured input. The `resolveBackendId` function selects backends by ID, with a default fallback. The reference implementation includes a "node" module backend; additional backends implement the `WorkspaceBackend` interface from [`packages/computer/src/backend.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/backend.ts).