File Edit Size Limits for Cloudflare OS Agents: Understanding the 64 MiB RPC Boundary

Cloudflare OS agents enforce a strict 64 MiB payload limit on all file edit RPC messages to prevent memory exhaustion and denial-of-service attacks across the distributed Workers environment.

File edit size limits for Cloudflare OS agents are hardcoded into the platform's RPC layer to ensure stable operation within Durable Object storage constraints. These limits apply uniformly to both composed change objects and raw artifact transfer bodies, protecting the system from resource exhaustion. Understanding where these boundaries are enforced in the cloudflare/cloudflare-os source code helps developers implement robust client-side validation and error handling.

The 64 MiB RPC Payload Ceiling

The Cloudflare OS platform imposes a 64 MiB (mebibyte) maximum on every RPC message transmitted between agents. This ceiling applies regardless of whether the payload contains composed code changes or binary artifact data. When an edit exceeds this threshold, the runtime immediately aborts the transfer and returns an error, ensuring that no single operation can overwhelm the channel or downstream storage systems.

This limit is intrinsic to the underlying capnweb implementation and the Durable Object architecture, serving as a critical safeguard against excessive memory usage and distributed denial-of-service vectors.

Where the Limit is Enforced in the Source Code

The 64 MiB boundary is documented and enforced across two primary components within the repository.

Workshop Shared Changes (code-change.ts)

In packages/workshop-shared/src/code-change.ts, the data structures for composed changes carry explicit documentation regarding the RPC size constraints. According to the source comments, composed changes get stored and travel in RPC messages, both of which have hard size limits. This file defines the TypeScript interfaces that prepare edits for transmission.

Gatekeeper Context Artifact Sync (artifact-sync.ts)

The packages/gatekeeper-context/src/artifact-sync.ts file implements the transfer-size limiter pattern for raw artifact bodies. The inline documentation specifies the 64 MB budget for raw transfers during artifact synchronization. This module ensures that binary payloads respect the same boundary as composed changes.

Implementing Client-Side Validation

To avoid runtime failures, applications must validate edit sizes before invoking the agent's API. The following TypeScript example demonstrates how to pre-flight check a ChangeSet against the 64 MiB boundary using constants defined in packages/workshop-shared/src/limits.ts.

import { MAX_RPC_PAYLOAD } from "@gadgets/workshop-shared/limits"; // hypothetical constant

async function sendEdit(edit: ChangeSet) {
  // Serialize the edit to JSON to estimate its byte size.
  const payload = JSON.stringify(edit);
  const sizeInBytes = new TextEncoder().encode(payload).length;

  if (sizeInBytes > 64 * 1024 * 1024) {
    throw new Error(
      `Edit payload (${sizeInBytes} bytes) exceeds the 64 MiB limit. ` +
      `Split the change into smaller parts or reduce the edited file size.`
    );
  }

  // Proceed with the RPC call – the underlying capnweb implementation will also enforce the limit.
  await rpcAgent.applyChange(edit);
}

Handling Size-Limit Errors

When the RPC layer rejects an oversized payload, the agent returns an error that client code must handle gracefully. Implement granular error checking to distinguish between size violations and other transport failures.

try {
  await sendEdit(largeChange);
} catch (err) {
  if (err.message.includes("exceeds the 64 MiB limit")) {
    // Notify the user and suggest splitting the edit.
    displayError("Your edit is too large; please break it into smaller chunks.");
  } else {
    // Handle other errors.
    console.error(err);
  }
}

Summary

• 64 MiB hard limit: All RPC messages carrying file edits are capped at 64 mebibytes per the platform's architecture.
• Dual enforcement: The limit applies to both composed changes in packages/workshop-shared/src/code-change.ts and raw artifact transfers in packages/gatekeeper-context/src/artifact-sync.ts.
• Runtime protection: Exceeding the limit triggers an immediate abort, safeguarding Durable Object storage and memory resources from exhaustion.
• Client responsibility: Applications must validate payload sizes before transmission to prevent runtime errors and provide clear user feedback.

Frequently Asked Questions

What happens if a file edit exceeds the 64 MiB limit?

The Cloudflare OS agent runtime aborts the RPC transfer immediately and returns an error message indicating the payload exceeds the 64 MiB boundary. The edit is not processed, and the application receives an exception that must be handled client-side before retrying with smaller chunks.

Does the 64 MiB limit apply to individual files or entire change sets?

The limit applies to the entire RPC message payload, which includes the serialized change set or artifact transfer body. If you are batching multiple file edits into a single RPC call, the aggregate size must remain under 64 MiB to avoid rejection.

Can the 64 MiB limit be configured or increased for specific agents?

No, the 64 MiB limit is a platform-level constant hardcoded into the RPC layer and Durable Object storage constraints. According to the source code in packages/workshop-shared/src/code-change.ts and packages/gatekeeper-context/src/artifact-sync.ts, this boundary cannot be overridden via configuration flags or runtime parameters.

How should I handle editing files larger than 64 MiB?

Split the file into smaller chunks or transmit diffs rather than full file contents. Implement client-side logic to fragment large edits across multiple RPC calls, ensuring each individual message remains below the 64 MiB threshold validated by the agent's limiter pattern.

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