Skip to content
Bindings / Configuration

Bindings

Binding configuration

Which Wrangler bindings run on OpenOrange as is, which need a service that you supply, and which are not supported.

OpenOrange reads your bindings from the same wrangler.jsonc as wrangler dev. Each binding runs as is, needs a service that you set, or is not supported, in which case it loads and its calls throw.

Quickstart

You need the orange CLI.

  1. Add the bindings

    Use the same keys as on Cloudflare.

    {
      "name": "my-worker",
      "main": "src/index.ts",
      "compatibility_date": "2026-09-03",
      "kv_namespaces": [{ "binding": "CACHE", "id": "cache" }],
      "ai": { "binding": "AI" },
      "images": { "binding": "IMAGES" }
    }
  2. Check them

    orange doctor lists each binding, what it runs on, and what it needs from you.

    orange doctor
      Binding      Resource       On Rivet          Runs on
    ! env.IMAGES   Images         not supported     stub · calls throw
                   Orange has no backend for this binding. Call the service's HTTP API with fetch(), or
                   keep this code off Orange.
                   https://github.com/rivet-dev/open-orange/blob/main/docs/modules/bindings.mdx
      env.AI       Workers AI     needs a service   OpenAI-compatible API
                   Set OPENROUTER_API_KEY, or ORANGE_AI_BASE_URL for another provider.
                   https://github.com/rivet-dev/open-orange/blob/main/docs/modules/workers-ai.mdx
      env.CACHE    KV Namespace   runs as is        Rivet Actor
                   https://github.com/rivet-dev/open-orange/blob/main/docs/modules/kv.mdx
    
      1 of 3 bindings run as is, 1 needs a service, 1 is not supported
  3. Set up each service

    Put the variable that orange doctor names in .dev.vars, next to wrangler.jsonc, and check again.

    echo 'OPENROUTER_API_KEY=<your key>' >> .dev.vars
    orange doctor
    ✓ Workers AI    env.AI · OpenRouter
    
    ● Ready for orange dev
  4. Start the Worker

    When it starts, orange dev lists each binding and what it runs on.

    orange dev

Replace a binding that is not supported

The Worker still starts, and only the calls to that binding throw. Move those calls to a service that the Worker reaches with fetch(). The reference below names one for Vectorize, Images, and Analytics Engine.

Set the variables on a deploy

orange deploy keeps .dev.vars out of the image. Pass it as secrets instead. See Variables and secrets.

orange deploy --secrets-file .dev.vars
AI context Compatibility, limits and details

Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.

Compatibility

BindingWrangler keyKindRuns onNotes
VariablesvarsRuns as isThe Worker processStrings and JSON values.
Local secrets.dev.vars, .envRuns as isThe Worker processLoaded like wrangler dev. See Variables and secrets.
Secrets Storesecrets_store_secretsRuns as isThe Worker processLocal values come from .dev.vars or the process environment. See Secrets Store.
Version metadataversion_metadataRuns as isThe Worker processSee Version metadata.
unsafe_evalunsafe.bindingsRuns as isThe Worker process
Static assetsassetsRuns as isLocal filesSee Static assets.
Durable Objectsdurable_objectsRuns as isOne Rivet Actor for each objectPartial. Same-Worker classes from new_sqlite_classes and new_classes migrations. See Durable Objects.
Durable Objects from another Workerdurable_objects with script_nameRuns as isThe other Worker’s Rivet ActorsBoth Workers run in one orange dev. See Multiple Workers.
Service bindings to this WorkerservicesRuns as isThe Worker processfetch(), JS RPC, named entrypoints, props, and ctx.exports.
Service bindings to another WorkerservicesRuns as isThe other Worker’s processPartial. Run both Workers in one orange dev with repeated -c. WebSocket upgrades throw. See Multiple Workers.
Dispatch namespacesdispatch_namespacesRuns as isThe Workers of the orange dev sessionPartial. See Multiple Workers.
KVkv_namespacesRuns as isOne Rivet Actor for each namespaceSee KV.
D1d1_databasesRuns as isOne Rivet Actor for each databaseSee D1.
Rate Limitingratelimits, unsafe.bindingsRuns as isOne Rivet Actor for each namespaceSee Rate Limiting.
R2r2_bucketsRuns as isOne Rivet Actor for each bucket, or your S3-compatible storeSet ORANGE_R2_<BUCKET>_S3_* to use Amazon S3, Cloudflare R2, Google Cloud Storage, or Backblaze B2. See R2.
Queuesqueues.producers, queues.consumersRuns as isOne Rivet Actor for each queueSee Queues.
WorkflowsworkflowsRuns as isCloudflare’s own Workflows engine, with one Rivet Actor for each instancePartial. See Workflows.
Tail Workerstail_consumersRuns as isRivet Durable StreamsPartial. See Tail Workers.
Worker Loaderworker_loadersRuns as isOne Node.js process for each dynamic Worker, in an agentOS VMPartial. See Worker Loader.
Workers AIaiNeeds a serviceAn OpenAI-compatible providerSet OPENROUTER_API_KEY, or ORANGE_AI_BASE_URL for OpenAI, Groq, Together AI, or Fireworks AI. See Workers AI.
Send Emailsend_emailNeeds a serviceYour SMTP serverSet ORANGE_EMAIL_SMTP_URL to Amazon SES, Resend, Postmark, SendGrid, or Mailgun. Without it, the binding throws. See Email.
Browser RenderingbrowserNeeds a serviceA hosted browser or your Chrome, through its DevTools Protocol endpointSet ORANGE_BROWSER_CDP_URL to Browserbase, Browserless, or Steel. Without it, the binding throws. See Browser Rendering.
HyperdrivehyperdriveNeeds a serviceYour database, with a direct connectionSet the local connection string, as for wrangler dev, such as PlanetScale, Amazon RDS, Neon, or Supabase. No pooling or query cache. See Hyperdrive.
Analytics Engineanalytics_engine_datasetsNot supportedNothingSee Analytics Engine.
VectorizevectorizeNot supportedNothingSee Vectorize.
Images, Media, Streamimages, media, streamNot supportedNothingSee Images.
PipelinespipelinesNot supportedNothingSee Pipelines.
AI Searchai_search, ai_search_namespacesNot supportedNothingSee AI Search.
mTLS certificatesmtls_certificatesNot supportedNothingSee mTLS certificates.
VPCvpc_networks, vpc_servicesNot supportedNothingSee VPC.
Legacy blobstext_blobs, data_blobs, wasm_modulesNot supportedNothingSee Legacy blobs.
Other binding typesNot supportedNothingIncludes other unsafe binding types.

Kinds

  • Runs as is: OpenOrange implements the Cloudflare API. You set nothing.
  • Needs a service: OpenOrange implements the Cloudflare API on a service that you supply, such as your SMTP server. You set one variable that points to it.
  • Not supported: Orange has no backend for the binding. The Worker loads, and env.NAME exists. Each method call throws an error that names the binding and suggests an alternative. Analytics Engine is the exception: it accepts writes and drops them.

orange doctor reports each binding of your project as one of these kinds. It does not list variables (vars, .dev.vars, and .env), because they need nothing on Rivet. A binding that is not supported does not fail orange doctor, also with --strict.

Where the data goes

  • Under orange dev, Rivet Actors run on a local Rivet Engine, and the data stays on your machine.
  • Under orange deploy, they run on your Rivet cluster.
  • A binding that needs a service sends its data to the service that you set.

Configuration that stops orange dev

Configuration that changes how the Worker runs, not what env contains, stops orange dev with Unsupported Wrangler configuration: <keys>. The keys are cloudchamber, connect, define, exports, legacy_assets, pages_build_output_dir, site, streaming_tail_consumers, triggers.events, and any unsafe setting other than unsafe.bindings.

These load instead:

  • orange dev accepts containers with a warning, and runs @cloudflare/sandbox classes on a sandbox provider, such as E2B, Daytona, or Freestyle. See Sandbox.
  • orange dev runs triggers.crons (see Cron Triggers), and delivers queues.consumers to the Worker’s queue() handler (see Queues).

Stubs

orange dev marks each binding that is not supported in its binding table at startup, with what to use instead on the next line:

  Binding        Resource            Runs on
! env.IMAGES     Images              stub · calls throw
                                     See the OpenOrange bindings documentation for supported bindings.

The binding is a stub, and it is safe to pass around. typeof env.IMAGES is "object", reading a property returns a function, and awaiting the stub does not call it. Calling any method throws an Error with the same message:

await env.IMAGES.info(stream);
// Error: Images binding "IMAGES" is not supported by OpenOrange. See the OpenOrange bindings documentation for supported bindings.

The message’s second sentence is the alternative for that binding type, such as a vector database for Vectorize, or an import for a Wasm module. orange doctor prints its own hint for each stub, with a link to this page.

Variables and secrets

orange dev resolves variables with Wrangler’s own wrangler dev logic:

  1. It starts with vars from the Wrangler configuration.
  2. It loads .dev.vars.<env> or .dev.vars next to the configuration file.
  3. If neither file exists, it loads .env, .env.local, .env.<env>, and .env.<env>.local. Set CLOUDFLARE_INCLUDE_PROCESS_ENV=true to also load the process environment.
  4. Loaded values become string bindings that replace vars with the same name.
  5. If secrets.required is set, only the listed keys load, and orange dev warns about missing keys with Missing required secrets: <keys>. Add them to .dev.vars, .env, or set as environment variables.
  • A .dev.vars entry named after another binding, such as a Secrets Store binding, stays that binding’s local value and does not replace it.
  • Secret values never become part of the version metadata ID.

Bindings without a page

Orange has no backend for these bindings. Each card’s status, migration path, and checks come from the conformance data.

Vectorize
Stub

Runs on Stub binding

Works
The configuration loads, and env.NAME is a stub that the Worker can pass around
Missing
Every method. Each call throws, and the error names a vector database to use instead.
Migration
Not supported orange migrate does not move Vectorize indexes. Copy the data yourself.
Configure
vectorize
Checks
1 fail

The error’s alternative reads: Call a vector database, such as Qdrant Cloud or Pinecone, with fetch(), or use pgvector through Hyperdrive. For a few thousand vectors, store the embeddings in SQLite and rank them by cosine similarity in JavaScript.

Use insteadHow the Worker reaches it
pgvector on Neon or SupabaseA Hyperdrive binding and a Postgres driver
Qdrant Cloudfetch() to https://<cluster host>:6333, with the api-key header
Pineconefetch() to the index host, with the Api-Key header
SQLite in a Durable Object, for a few thousand vectorsStore the embeddings, and rank them by cosine similarity in JavaScript
Images
Stub

Runs on Stub bindings

Works
The images, media, and stream configuration loads, and each binding is a stub
Missing
Every method of Images, Media Transformations, and Stream. Each call throws.
Migration
Not supported The bindings are stubs. Images and videos stored on Cloudflare stay there.
Configure
imagesmediastream
Checks
1 fail
Use insteadHow the Worker reaches it
Cloudinaryfetch() to its upload and transformation URLs
imgproxy that you runfetch() to its processing URLs
Pipelines
Stub

Runs on Stub binding

Works
The configuration loads, and the binding is a stub
Missing
send() and every other method. Each call throws.
Migration
Not supported orange migrate does not move Pipelines. Copy the data yourself.
Configure
pipelines
Checks
1 fail
Stub

Runs on Stub binding

Works
The ai_search and ai_search_namespaces configuration loads, and each binding is a stub
Missing
Every method, and env.AI.autorag() and env.AI.aiSearch() on the Workers AI binding. Each call throws.
Migration
Not supported orange migrate does not move AI Search instances. Copy the data yourself.
Configure
ai_searchai_search_namespaces
Analytics Engine
Partial

Runs on A dataset that drops every data point, as Miniflare does

Works
writeDataPoint() accepts data points, as wrangler dev does
Differs
Orange stores nothing. It drops every data point, and orange doctor shows the binding as drops writes.
Missing
The SQL API that queries a dataset
Migration
Not supported orange migrate does not move Analytics Engine datasets. Copy the data yourself.
Configure
analytics_engine_datasets

To keep the data, send each data point to your own analytics store with fetch() to its ingest API.

mTLS certificates
Stub

Runs on Stub binding

Works
The configuration loads, and the binding is a stub
Missing
fetch() with the certificate. Each call throws.
Migration
Not supported The binding is a stub. Certificates uploaded to Cloudflare stay there.
Configure
mtls_certificates
Checks
1 fail
VPC
Stub

Runs on Stub bindings

Works
The vpc_networks and vpc_services configuration loads, and each binding is a stub
Missing
Every call through a VPC network or service. Each call throws.
Migration
Not needed A VPC binding holds no data.
Configure
vpc_networksvpc_services

Use fetch() to reach the host network directly.

Legacy blobs
Stub

Runs on Stub bindings

Works
The text_blobs, data_blobs, and wasm_modules configuration loads, and each binding is a stub
Missing
The file contents. env.NAME is a stub, and each call on it throws.
Migration
Not needed Blobs are files in the project.
Configure
text_blobsdata_blobswasm_modules

Import the file from the Worker source instead. For a Wasm module, the error reads Import the WebAssembly module from the Worker source instead.

Conformance

Recorded results from the conformance run of 2026-11-10 (Orange ea40348), 1,670 of 1,851 tests passing across every area. Each check is works when every result passed and partial when some did. The full feature matrix is on the compatibility page.

Vectorize
Check Status Results
Vectorize, Images, Pipelines, mTLS Does not work
  • Fail: stub-bindings: Vectorize: query() runs
  • Fail: stub-bindings: Images: info() runs
  • Fail: stub-bindings: Pipelines: send() runs
  • Fail: stub-bindings: mTLS certificates: fetch() runs
Images, Media, Stream
Check Status Results
Vectorize, Images, Pipelines, mTLS Does not work
  • Fail: stub-bindings: Vectorize: query() runs
  • Fail: stub-bindings: Images: info() runs
  • Fail: stub-bindings: Pipelines: send() runs
  • Fail: stub-bindings: mTLS certificates: fetch() runs
Pipelines
Check Status Results
Vectorize, Images, Pipelines, mTLS Does not work
  • Fail: stub-bindings: Vectorize: query() runs
  • Fail: stub-bindings: Images: info() runs
  • Fail: stub-bindings: Pipelines: send() runs
  • Fail: stub-bindings: mTLS certificates: fetch() runs
AI Search
Check Status Results
Analytics Engine
Check Status Results
mTLS certificates
Check Status Results
Vectorize, Images, Pipelines, mTLS Does not work
  • Fail: stub-bindings: Vectorize: query() runs
  • Fail: stub-bindings: Images: info() runs
  • Fail: stub-bindings: Pipelines: send() runs
  • Fail: stub-bindings: mTLS certificates: fetch() runs
VPC
Check Status Results
Legacy blobs
Check Status Results