Environment:Helicone Helicone Cloudflare Workers Runtime
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Edge_Computing |
| Last Updated | 2026-02-14 06:00 GMT |
Overview
Cloudflare Workers V8 isolate runtime with `nodejs_compat_v2` flag, Durable Objects, KV namespaces, Queues, and Containers for the Helicone LLM proxy.
Description
This environment defines the Cloudflare Workers runtime that powers the Helicone proxy layer. The worker intercepts LLM API requests, applies rate limiting via Durable Objects, caches responses via KV namespaces, and forwards logs to the backend via Queues. The runtime uses V8 isolates (not Node.js) with the `nodejs_compat_v2` compatibility flag to enable Node.js APIs. The `compatibility_date` is set to `2025-08-03`, which determines which Workers runtime features are available.
Usage
Use this environment for developing and deploying the Helicone LLM proxy worker. It is required for request interception, response caching, rate limiting, and async log forwarding. Local development uses `npx wrangler dev --local`.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Runtime | Cloudflare Workers (V8 isolates) | Not a traditional Node.js runtime |
| CLI | Wrangler >= 4.27.0 | For local development and deployment |
| Node.js | >= 20 (for Wrangler CLI) | Wrangler runs on Node.js locally |
| Account | Cloudflare account with Workers plan | For deployment; local dev works without |
Dependencies
Wrangler Configuration
- `compatibility_date` = `2025-08-03`
- `compatibility_flags` = `["nodejs_compat_v2"]`
Durable Objects
- `InMemoryRateLimiter` (RATE_LIMITER)
- `RateLimiterDO` (RATE_LIMITER_SQL)
- `BucketRateLimiterDO` (BUCKET_RATE_LIMITER)
- `Wallet` (WALLET)
- `RequestBodyBufferContainer` (REQUEST_BODY_BUFFER)
KV Namespaces
- `RATE_LIMIT_KV` (rate limiting state)
- `CACHE_KV` (response caching)
- `INSERT_KV` (insertion tracking)
- `UTILITY_KV` (general utilities)
- `WALLET_KV` (credit wallet state)
- `REQUEST_AND_RESPONSE_QUEUE_KV` (queue fallback)
- `SECURE_CACHE` (secure cached data)
- `EU_SECURE_CACHE` (EU region secure cache)
Queue Producers
- `FALLBACK_QUEUE` (fallback log queue)
Containers
- `RequestBodyBufferContainer` (Docker container for request body buffering, max 10 instances)
Credentials
The following environment variables must be configured in `wrangler.toml` or via `wrangler secret`:
- `SUPABASE_SERVICE_ROLE_KEY`: Supabase service role JWT for auth
- `SUPABASE_URL`: Supabase API endpoint
- `EU_SUPABASE_SERVICE_ROLE_KEY`: EU region Supabase key
- `EU_SUPABASE_URL`: EU region Supabase endpoint
- `CLICKHOUSE_HOST`: ClickHouse HTTP endpoint
- `CLICKHOUSE_USER`: ClickHouse username
- `CLICKHOUSE_PASSWORD`: ClickHouse password
- `VALHALLA_URL`: Jawn backend URL (default `http://localhost:8585`)
- `WORKER_TYPE`: Worker variant (e.g., `OPENAI_PROXY`, `ANTHROPIC_PROXY`)
- `REQUEST_CACHE_KEY`: Encryption key for cache entries
Quick Install
# Install dependencies
cd worker && yarn install
# Start local development (OpenAI proxy mode)
npx wrangler dev --local --var WORKER_TYPE:OPENAI_PROXY --port 8787
# Run tests
npx vitest
Code Evidence
Wrangler configuration from `worker/wrangler.toml:1-4`:
name = "helicone-worker-dev"
main = "src/index.ts"
compatibility_date = "2025-08-03"
compatibility_flags = ["nodejs_compat_v2"]
Durable Object bindings from `worker/wrangler.toml:8-14`:
durable_objects.bindings = [
{ name = "RATE_LIMITER", class_name = "InMemoryRateLimiter" },
{ name = "RATE_LIMITER_SQL", class_name = "RateLimiterDO" },
{ name = "BUCKET_RATE_LIMITER", class_name = "BucketRateLimiterDO" },
{ name = "WALLET", class_name = "Wallet" },
{ name = "REQUEST_BODY_BUFFER", class_name = "RequestBodyBufferContainer" },
]
Worker type routing from `worker/src/routers/routerFactory.ts`:
// WORKER_TYPE determines which proxy router is activated
const WORKER_TYPE = env.WORKER_TYPE; // e.g., "OPENAI_PROXY", "ANTHROPIC_PROXY"
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Durable Object not found` | Missing Durable Object migration | Run `wrangler deploy` to provision Durable Objects |
| `KV namespace not found` | KV namespace ID mismatch | Verify KV namespace IDs in `wrangler.toml` match your account |
| `compatibility_date too recent` | Using features not yet available | Downgrade `compatibility_date` or update Wrangler CLI |
| `nodejs_compat_v2 not supported` | Wrangler version too old | Update to Wrangler >= 4.27.0 |
Compatibility Notes
- V8 Isolates vs Node.js: Workers run in V8 isolates, not full Node.js. The `nodejs_compat_v2` flag provides partial Node.js API compatibility but some APIs (filesystem, child_process) are unavailable.
- Durable Objects: Require a paid Workers plan for deployment. Local development via `wrangler dev --local` simulates them.
- Containers: The `RequestBodyBufferContainer` uses Workers Containers (a relatively new feature), which may require specific account flags.
- EU Data Residency: Separate KV namespaces (`EU_SECURE_CACHE`) and Supabase credentials (`EU_SUPABASE_*`) support EU data residency requirements.