Cloud Host (Cloudflare Workers)

Relevant source files

• apps/cloud/src/api.request-scope.node.test.ts
• apps/cloud/src/api/error-response.ts
• apps/cloud/src/api/layers.ts
• apps/cloud/src/api/protected.ts
• apps/cloud/src/api/router.ts
• apps/cloud/src/auth/middleware-live.ts
• apps/cloud/src/edge/docs.test.ts
• apps/cloud/src/edge/docs.ts
• apps/cloud/src/edge/index.ts
• apps/cloud/src/edge/openai-apps-challenge.test.ts
• apps/cloud/src/edge/openai-apps-challenge.ts
• apps/cloud/src/engine/execution-gate.ts
• apps/cloud/src/engine/execution-rate-limit.ts
• apps/cloud/src/env-augment.d.ts
• apps/cloud/src/extensions/billing/route.ts
• apps/cloud/src/extensions/billing/service.ts
• apps/cloud/src/extensions/routes.ts
• apps/cloud/src/mcp/agent-handler.ts
• apps/cloud/src/mcp/session-durable-object.ts
• apps/cloud/src/observability/index.ts
• apps/cloud/src/observability/observability.test.ts
• apps/cloud/src/org/api.ts
• apps/cloud/src/org/auth-middleware.ts
• apps/cloud/src/org/handlers.ts
• apps/cloud/src/routes/app/billing.tsx
• apps/cloud/src/routes/app/billing_.plans.tsx
• apps/cloud/src/server.ts
• apps/cloud/src/start.ts
• apps/cloud/src/web/client.tsx
• apps/cloud/worker-configuration.d.ts
• apps/cloud/wrangler.jsonc
• apps/host-cloudflare/src/mcp/agent-handler.ts
• apps/host-cloudflare/src/mcp/index.ts
• apps/host-cloudflare/src/mcp/session-durable-object.ts
• autumn.config.ts
• e2e/cloud/mcp-browser-resume-page.test.ts
• e2e/cloud/mcp-client-sessions.test.ts
• e2e/cloud/repro-transport-brick.test.ts
• e2e/cloud/sentry-otel-correlation.test.ts
• e2e/recordings/mcp-browser-resume-page.mp4
• e2e/setup/cloud.globalsetup.ts
• e2e/setup/mcp-session-timeouts.ts
• e2e/setup/selfhost.globalsetup.ts
• e2e/src/ports.ts
• packages/hosts/cloudflare/src/mcp/agent-session-durable-object.test.ts
• packages/hosts/cloudflare/src/mcp/agent-session-durable-object.ts
• packages/hosts/cloudflare/src/mcp/agent-session-model-resume.test.ts
• packages/hosts/cloudflare/src/mcp/execution-owner-directory.test.ts
• packages/hosts/cloudflare/src/mcp/execution-owner-directory.ts
• packages/hosts/cloudflare/src/mcp/session-alarm-policy.test.ts
• packages/hosts/cloudflare/src/mcp/session-alarm-policy.ts
• packages/react/src/components/page.tsx

The Cloud Host is the production-grade deployment of the Executor platform, running on Cloudflare Workers. It leverages Durable Objects for stateful Model Context Protocol (MCP) sessions, Hyperdrive for high-performance PostgreSQL access, and Autumn for usage-based billing and metering.

Architecture Overview

The cloud host integrates the shared @executor-js/api and @executor-js/core logic into a serverless environment. It uses a unified fetch handler to route traffic between the TanStack Start SSR application, the protected plugin API, and the stateful MCP session bridge.

Code Entity Mapping: Request Flow

The following diagram bridges the natural language request flow to the specific code entities and files that handle them.

Sources: apps/cloud/src/server.ts103-146 apps/cloud/src/start.ts81-90 apps/cloud/src/mcp/agent-handler.ts115-176

Durable Objects and Session Lifecycle

Executor Cloud uses three primary Durable Object classes to manage stateful execution and rate limiting.

1. McpSessionDOSqlite

This is the core of the MCP implementation. It inherits from McpAgentSessionDOBase and provides a stateful bridge for MCP clients.

• Hibernation: It uses the Cloudflare Workers hibernation API to maintain session state (like protocol version and active tools) without incurring continuous CPU costs packages/hosts/cloudflare/src/mcp/agent-session-durable-object.ts206-210
• Storage: Since migration v2, it uses the DO SQLite backend for session persistence apps/cloud/wrangler.jsonc52-55
• Lifecycle: Sessions are minted against a specific McpResource (e.g., a Toolkit) and have an inactivity alarm that triggers cleanup packages/hosts/cloudflare/src/mcp/agent-session-durable-object.ts38-46

2. McpExecutionOwnerDirectoryDO

Maintains a mapping of execution IDs to the specific Durable Object instances that own them. This allows the system to route "Resume" requests (from browser approvals) to the correct stateful session apps/cloud/src/server.ts75

3. ExecutionRateLimiterDO

A per-organization counter used as an abuse backstop. It tracks execution volume within a sliding window and triggers alarms to purge stale counters apps/cloud/wrangler.jsonc29-35

Sources: apps/cloud/src/server.ts57-75 apps/cloud/wrangler.jsonc19-64 packages/hosts/cloudflare/src/mcp/agent-session-durable-object.ts206-210

Data Persistence (PostgreSQL & Hyperdrive)

The cloud host uses PostgreSQL as its primary datastore via Cloudflare Hyperdrive.

• Connection Management: The DbService resolves connection strings dynamically. In production, it targets the Hyperdrive binding HYPERDRIVE to pool connections and reduce latency apps/cloud/wrangler.jsonc71-77
• I/O Isolation: To satisfy Cloudflare Workers' I/O isolation requirements, the postgres.js socket is rebuilt per-request using RequestScopedServicesLive apps/cloud/src/api/layers.ts29-33
• Schema: The database uses a combinedSchema that includes core platform tables and plugin-specific requirements apps/cloud/src/mcp/session-durable-object.ts162-164

Sources: apps/cloud/src/db/db.ts153-168 apps/cloud/wrangler.jsonc71-77 apps/cloud/src/api/layers.ts29-33

Billing and Metering (Autumn)

Usage-based billing is integrated via the Autumn service. Metering occurs at the execution stack level, ensuring that both HTTP API calls and MCP tool invocations are tracked.

• Metered Stack: The cloud host provides a CloudMeteredExecutionStackLayer which wraps the standard execution engine to emit usage events to Autumn apps/cloud/src/api/protected.ts64-79
• Billing UI: A dedicated billing page (/billing) allows users to view plan status, manage subscriptions via the customer portal, and monitor usage balances for "Members" and "Executions" apps/cloud/src/routes/app/billing.tsx20-58
• Free Limits: The createOrganization handler includes a gate that checks Autumn to enforce free-tier organization limits apps/cloud/src/api/layers.ts54-56

Sources: apps/cloud/src/api/protected.ts64-79 apps/cloud/src/routes/app/billing.tsx116-161 apps/cloud/src/extensions/billing/service.ts1-20

Observability

The cloud host implements a multi-layered observability stack combining OpenTelemetry (OTel), Sentry, and Axiom.

Telemetry Pipeline

• W3C Propagation: The Worker fetch handler injects traceparent and tracestate headers when calling Durable Objects to ensure a single logical request is captured as one trace apps/cloud/src/mcp/session-durable-object.ts116-120
• Sentry Correlation: Errors are captured with OTel trace correlation. Durable Objects are wrapped using instrumentDurableObjectWithSentry to ensure isolate-specific errors are reported correctly apps/cloud/src/server.ts32-60
• Browser Ingress: The worker provides a /v1/traces endpoint that proxies browser-side OTLP spans to Axiom, avoiding CORS issues and centralizing auth tokens apps/cloud/src/server.ts113-118

Sources: apps/cloud/src/server.ts32-109 apps/cloud/src/mcp/session-durable-object.ts116-142 apps/cloud/src/observability/telemetry.ts1-50