Cloudflare Computer Core Runtime Types Explained: A Complete API Reference

The Cloudflare Computer core runtime types are a compact TypeScript type system defined in 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 and are consumed by WorkspaceRuntime in 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.

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

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

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

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

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

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

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

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

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

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

// 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	Central type definitions for all runtime interfaces
packages/computer/src/runtime/runtime.ts	WorkspaceRuntime implementation using these types
packages/computer/src/runtime/wire.ts	Cap'n Proto wire encoding for Durable Object communication
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 and consumed by the WorkspaceRuntime class in 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.

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