Cloudflare + Modal Boundaries

Rafiki runs as two connected services. Cloudflare handles the public URL and session authority. Modal runs the execution backend behind it.

What Most Developers Need To Know

Cloudflare Worker URLs are the only supported public URL your app should call.
Durable Objects keep session state, streaming orchestration, and event fan-out at the edge.
Modal runs the agent execution backend, tool access, and artifact storage.
Background jobs and artifacts are still requested through the Worker, even when execution happens in Modal.

High-Level Architecture

flowchart LR
    Client["Client or Backend"] --> Worker["Cloudflare Worker"]
    Worker --> SessionDO["Session Durable Object"]
    Worker --> EventBus["Event Bus Durable Object"]
    Worker --> Jobs["Job and Artifact Routes"]
    SessionDO --> Modal["Internal Modal Execution Backend"]
    Jobs --> Modal
    EventBus --> Client
    Modal --> Tools["Models and Tools"]

Public Components

Cloudflare Worker

validates public auth
routes requests to the right public surface
enforces rate limits, CORS, and public error handling

Session Durable Objects

keep per-session state and message history
coordinate sequential prompt execution
bridge streamed execution into public WebSocket events

Event Bus

fans out session and job events over WebSockets
lets clients subscribe to session or user activity

Job and Artifact Routes

accept background work through POST /submit
expose job status and artifacts through public Worker URLs

Modal runs the agent runtime, tool execution, workspaces, and artifact storage. Those details live behind the Worker and do not become a separate public URL for your app.

Supported Public Patterns

Need	Public route	Notes
one request, one full response	`POST /query`	simplest integration path
live streamed progress	`GET /query_stream`	WebSocket upgrade
session updates across tabs or clients	`GET /ws` or `GET /events`	event subscriptions
long-running work	`POST /submit` + `GET /jobs/{job_id}`	background job flow
inspect session state	`/session/{session_id}/...`	state, messages, queue, stop

What Stays Internal

Modal gateway URLs and service-to-service auth
sandbox lifecycle, readiness, and rollout mechanics
monitoring, alerting, and cost tuning
operator remediation and deployment runbooks