Preview Environments and E2E Infrastructure

Relevant source files

• .github/workflows/ci.yml
• .github/workflows/pkg-pr-new.yml
• .github/workflows/preview-sweep.yml
• .github/workflows/preview.yml
• .github/workflows/publish-desktop.yml
• .github/workflows/publish-executor-package.yml
• .github/workflows/publish-selfhost-docker.yml
• .github/workflows/release.yml
• apps/cloud/src/engine/execution-limit-messages.ts
• apps/cloud/src/engine/execution-stack-metered.ts
• apps/cloud/src/env-augment.d.ts
• apps/cloud/src/mcp/session-durable-object.ts
• apps/cloud/src/server.ts
• apps/cloud/worker-configuration.d.ts
• apps/cloud/wrangler.jsonc
• apps/host-cloudflare/.gitignore
• apps/host-cloudflare/scripts/preview.ts
• e2e/cloud/mcp-execution-limits.test.ts
• e2e/local/local-server.ts
• e2e/local/stdio-mcp.test.ts
• e2e/scenarios/mcp-opencode-real.test.ts
• e2e/scenarios/openapi-source.test.ts
• e2e/scripts/rebuild-viewer.ts
• e2e/selfhost/oauth-app-modal.test.ts
• e2e/setup/autumn-plans.ts
• e2e/setup/cloud.boot.ts
• e2e/setup/cloud.globalsetup.ts
• e2e/setup/selfhost.globalsetup.ts
• e2e/src/ports.ts
• e2e/src/recording-url-bar.ts
• e2e/src/surfaces/autumn.ts
• e2e/src/surfaces/browser.ts
• e2e/src/surfaces/cli.ts
• e2e/src/surfaces/mcp.ts
• e2e/src/target.ts
• e2e/src/timeline.ts
• e2e/targets/cloud.ts
• e2e/targets/selfhost.ts
• e2e/viewer/src/App.tsx
• e2e/viewer/src/SessionPlayer.tsx
• e2e/viewer/src/TerminalCast.tsx
• e2e/viewer/src/styles.css
• e2e/viewer/src/vite-env.d.ts
• packages/hosts/cloudflare/src/mcp/agent-session-durable-object.ts
• scripts/validate-release-ref.ts
• tests/release-workflows.test.ts
• turbo.json

The Executor project utilizes a sophisticated ephemeral infrastructure system to validate changes across its distributed components (Cloud, Self-host, and CLI). This system manages the lifecycle of Cloudflare-based preview stacks and orchestrates multi-process end-to-end (E2E) test environments.

Ephemeral Cloudflare Preview Stacks

The apps/host-cloudflare package includes a CLI utility, preview.ts, for managing ephemeral "Preview Environments" on Cloudflare. These environments allow developers to deploy a full stack (Worker, D1, R2, and Access) for a specific pull request or branch.

Stack Components and Lifecycle

Preview environments are composed of several Cloudflare resources that mirror the production architecture:

• Durable Objects (DO): Used for hibernatable MCP sessions and rate limiting apps/cloud/wrangler.jsonc19-36
• D1 Database: Provides the SQLite storage layer for the host-cloudflare variant.
• R2 Buckets: Provides the BLOBS storage for multi-MB resolved plugin specs apps/cloud/wrangler.jsonc80-85
• Cloudflare Access: Secures the preview URL behind organizational authentication.

The preview.ts CLI

The preview CLI manages the creation and teardown of these stacks. Key operations include:

• Namespace Isolation: Generating unique names for D1 databases and Workers to prevent collisions between PRs.
• Configuration Injection: Dynamically updating wrangler.jsonc bindings for the ephemeral resources.
• Cleanup: A nightly "sweep" workflow (preview-sweep.yml) identifies and deletes stale preview resources to manage Cloudflare account limits.

Data Flow: Preview Deployment

Sources: apps/host-cloudflare/scripts/preview.ts (), .github/workflows/preview-sweep.yml (), apps/cloud/wrangler.jsonc:19-85 ()

E2E Infrastructure and Port Allocation

The E2E suite handles the complexity of booting multiple interconnected services (Emulators, Databases, and App Servers) simultaneously.

Atomic Port Allocation

To prevent collisions in CI (where multiple shards or concurrent jobs may run on the same runner), the system uses a claimAndBoot pattern e2e/setup/cloud.globalsetup.ts68-97

• Port Blocks: Services are assigned offsets within a claimed block (e.g., Cloud Vite Dev at +0, DB at +1, WorkOS at +2) e2e/setup/cloud.globalsetup.ts72-75
• Probing: The claimAndBoot function probes for free port ranges and retries on EADDRINUSE to handle race conditions with ephemeral outbound sockets e2e/setup/cloud.globalsetup.ts61-64

Service Emulators

Executor runs its real authentication and billing code against local emulators:

• WorkOS Emulator: Mints OAuth tokens and handles AuthKit redirects e2e/setup/cloud.boot.ts62-66
• Autumn Emulator: Seeds a plan catalog to test billing eligibility and trial checkouts e2e/setup/cloud.boot.ts67-73

Test Targets

The infrastructure supports three primary targets, defined in e2e/src/target.ts:

1. Cloud: Runs the apps/cloud stack with PGlite and emulators e2e/setup/cloud.boot.ts111-145
2. Self-host: Runs the Docker-based distribution or its equivalent Node-based host e2e/setup/selfhost.globalsetup.ts
3. Local: Validates the CLI and local-server behavior e2e/local/local-server.ts

Entity Mapping: E2E Boot Sequence

Sources: e2e/setup/cloud.globalsetup.ts:68-111 (), e2e/setup/cloud.boot.ts:51-145 (), e2e/setup/boot.ts ()

E2E Viewer and Observability

To facilitate debugging of complex distributed failures, the project includes an E2E Viewer application.

Trace and Recording Capture

• Motel Exporter: A suite-owned trace store (motel) captures distributed traces from both the server and the browser during test runs e2e/setup/cloud.globalsetup.ts52-59
• Span Correlation: Server and browser spans are stitched together via W3C parent-span headers, allowing the viewer to show a complete waterfall of an execution apps/cloud/src/mcp/session-durable-object.ts116-120
• Session Player: The viewer includes a SessionPlayer and TerminalCast component to replay CLI interactions and browser sessions captured during the E2E run e2e/viewer/src/SessionPlayer.tsx e2e/viewer/src/TerminalCast.tsx

Artifacts and Logs

In CI, logs from the dev-db and vite dev processes are swept into failure artifacts e2e/setup/cloud.globalsetup.ts17-26 The bootLogFile captures stdout/stderr which would otherwise be lost in the sharded environment.

Component	Role	Code Entity
Port Manager	Atomic block allocation	claimAndBoot e2e/src/ports.ts
Cloud Boot	Shared boot recipe	bootCloud e2e/setup/cloud.boot.ts
Trace Store	Ephemeral OTLP sink	bootMotel e2e/setup/motel.ts
Visualizer	Debugging dashboard	e2e/viewer/src/App.tsx

Sources: e2e/setup/cloud.globalsetup.ts:17-59 (), apps/cloud/src/mcp/session-durable-object.ts:116-120 (), e2e/viewer/src/SessionPlayer.tsx (), e2e/viewer/src/TerminalCast.tsx ()