Skip to content

Conversation

@deathbyknowledge
Copy link

Greetings 👋

I'm Steve from Cloudflare's Agents team. We build and maintain the Sandbox SDK and we thought it'd be a great idea to expand the sandboxing here to allow different provider options (modal/cloudflare), customizable at deploy time.

Cloudflare's Sandbox SDK has fast cold starts and great placements, although we do not support snapshotting (yet! coming soon).

PS: Cool repo!

Add support for choosing between Modal and Cloudflare sandbox backends
via the SANDBOX_BACKEND environment variable (or sandbox_backend in Terraform).

Changes:
- Add SandboxManager interface for backend abstraction
- Create ModalSandboxManager implementing the interface
- Create CloudflareSandboxManager implementing the interface
- Add factory function that selects backend based on env var
- Update SessionDO to use abstraction for spawn/snapshot/restore
- Add packages/sandbox/ with Cloudflare container code:
  - TypeScript supervisor (port of Modal's entrypoint.py)
  - TypeScript bridge (port of Modal's bridge.py)
  - Dockerfile for Cloudflare container image
  - inspect-plugin.js (same as Modal, OpenCode custom tool)
- Update Terraform to support sandbox_backend variable
- Make Modal resources conditional (only deployed when backend=modal)
- Add docs/SANDBOX_BACKENDS.md with setup instructions

Backend comparison:
- Modal: Supports snapshot/restore, Python supervisor, full Terraform support
- Cloudflare: No snapshot support yet, TypeScript supervisor, requires wrangler for containers

Default backend is 'modal' for backward compatibility.
Set sandbox_backend="cloudflare" in terraform.tfvars for Cloudflare.
- Move sandbox backend documentation from docs/SANDBOX_BACKENDS.md to README
- Add condensed comparison table and configuration example
- Update architecture diagram to show Modal/Cloudflare options
- Add packages/sandbox/**/*.js to ESLint ignores
- Fix inspect-plugin.js globals and unused parameter
- Add @cloudflare/sandbox dependency and export Sandbox class
- Support both header-based (Modal) and query param (Cloudflare/Bun) auth
- Fix Terraform outputs for conditional backend modules
@greptile-apps
Copy link

greptile-apps bot commented Jan 28, 2026

Greptile Overview

Greptile Summary

Added Cloudflare Sandbox as an alternative backend to Modal, creating a pluggable sandbox architecture.

Key Changes

  • Introduced SandboxManager interface abstraction allowing multiple backend implementations
  • Implemented CloudflareSandboxManager using @cloudflare/sandbox SDK with fast cold starts (~5-15s)
  • Refactored Modal integration into ModalSandboxManager implementing the same interface
  • Created new packages/sandbox with TypeScript supervisor and bridge for Cloudflare containers
  • Added Terraform configuration for conditional deployment based on sandbox_backend variable
  • Updated WebSocket authentication to support both header-based (Modal/Python) and query param-based (Cloudflare/Bun) auth

Architecture

The abstraction properly handles backend differences:

  • Modal: Full snapshot/restore support with modalObjectId tracking
  • Cloudflare: No snapshot support yet (gracefully degrades to fresh spawn)
  • Control plane DurableObject seamlessly switches between backends via createSandboxManager(env)

Important Files Changed

Filename Overview
packages/control-plane/src/sandbox/types.ts Introduced clean SandboxManager interface for backend abstraction with proper optional snapshot support
packages/control-plane/src/sandbox/cloudflare.ts Implemented Cloudflare backend using SDK, properly checking for Sandbox binding and handling environment config
packages/control-plane/src/sandbox/modal.ts Refactored Modal integration into clean manager class implementing SandboxManager interface
packages/control-plane/src/session/durable-object.ts Updated to use SandboxManager abstraction, properly checking supportsSnapshots() before snapshot operations, added dual auth support for WebSocket
packages/sandbox/src/supervisor.ts Node.js/Bun supervisor managing OpenCode server and bridge lifecycle with git sync, health checks, and process monitoring
packages/sandbox/src/bridge.ts Bun-based bridge for WebSocket communication using query param auth (Bun WebSocket limitation), handles events and commands
terraform/environments/production/main.tf Added conditional deployment logic based on sandbox_backend variable, properly using count for modal vs cloudflare modules
terraform/modules/cloudflare-sandbox/main.tf New module deploying control plane via wrangler CLI with container support, generates wrangler.jsonc with Sandbox DO binding

@arcinston
Copy link

@ColeMurray if we good get this feature - would be really awesome

@ColeMurray
Copy link
Owner

thanks @deathbyknowledge, super cool! I created an issue here for discussion: #26

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants