Skip to content

Getting Started & Multi-Platform Deployment ​

AI Translation Notice

This page is an English translation of the authoritative Chinese deployment documentation. Refer to the Chinese version in case of discrepancies.

ModelBridge serves OpenAI, Anthropic, and Gemini client endpoints from a single shared gateway core (_worker.js), ships a Primer-styled portal / and admin console /admin, and adapts across Cloudflare Workers, EdgeOne Makers, Alibaba Cloud ESA, and a self-hosted Node.js 24 + SQLite state service.

Capability Scope & Boundaries ​

AreaImplemented BehaviorExplicit Boundaries
OpenAI IngressGET /v1/models, POST /v1/chat/completions, POST /v1/completions, POST /v1/embeddingsDoes not implement /v1/responses, image generation/editing, or audio TTS/STT endpoints
Anthropic IngressPOST /v1/messages (with tool calling and SSE delta translation)Rejects unrepresentable cross-protocol parameters pre-flight instead of silently dropping them
Gemini Ingress/v1beta/models/<id>:* and /v1/models/<id>:* (:generateContent, :streamGenerateContent, :embedContent, :batchEmbedContents):countTokens returns 501; no exact cross-provider token counting
State AuthoritySelf-hosted SQLite (WAL + BEGIN IMMEDIATE) or Cloudflare AppConfigStore DOSingle authority per deployment; no dual-write or silent runtime fallback
Presets & Reference Usagecloudflare-model-map.json (65 @cf/... aliases) + 5-minute cached Neurons indicatorDiscovery and display helpers only; not a hard server-side billing cap

Want interactive schemas and runnable requests for OpenAI, Anthropic, Gemini, /api/*, and /_modelbridge/state? Jump to the API & Component Reference.

Local Verification & Quick Build ​

Requires Node.js 24+ at the repository root (zero third-party runtime npm dependencies):

sh
pnpm run check
node --test tests/*.test.mjs
node tools/build-platforms.mjs
  1. Start the Node.js 24 + SQLite state service (local example):
sh
MODELBRIDGE_STATE_TOKEN="$(openssl rand -hex 32)" \
DB_PATH=./data/modelbridge.sqlite \
MODELBRIDGE_STATE_PUBLIC_ORIGIN=https://state.example \
MODELBRIDGE_STATE_ORIGINS=https://gateway.example \
pnpm run start:state
  1. Front with HTTPS reverse proxy: Expose fixed path /_modelbridge/state over TLS (see deploy/self-hosted-state/Caddyfile) while keeping Node bound to 127.0.0.1:8788.
  2. Deploy stateless gateway bundle: Deploy dist/cloudflare-remote/, dist/edgeone/, or dist/esa/ with runtime secrets ADMIN_PASSWORD, MODELBRIDGE_STATE_URL (https://state.example/_modelbridge/state), and the matching MODELBRIDGE_STATE_TOKEN.
  3. Configure /admin: Sign in with ADMIN_PASSWORD, add upstream accounts (cloudflare, openai, anthropic, gemini, antigravity), and issue client apiKeys.

Multi-Platform Deployment Matrix ​

node tools/build-platforms.mjs generates six standalone projects under dist/:

Bundle (dist/)Target RuntimeState AuthorityInjected Platform Limits (src/platforms/)Template & Manifest
self-hosted-stateLinux container / Node.js 24Local SQLite (WAL, synchronous=FULL, APPLICATION_ID=0x4d425331)2 MiB request / 16 MiB response; usageTimeoutMs = 15000deploy/self-hosted-state/README.md (compose.yaml + Caddyfile)
cloudflare-remoteCloudflare Workers (stateless)Remote HTTPS state service (/_modelbridge/state)16 MiB request bodydeploy/cloudflare-remote/ (no KV or DO binding)
edgeoneTencent Cloud EdgeOne MakersRemote HTTPS state service (/_modelbridge/state)1 MiB request body capdeploy/edgeone/edgeone.json (outputDirectory: "./public")
esaAlibaba Cloud ESA Edge RoutineRemote HTTPS state service (/_modelbridge/state)16 MiB body, 4 outbound fetches, 9000ms first byte, 115000ms totaldeploy/esa/esa.jsonc (entry: "./worker.js")
state-serviceCloudflare Workers state hostCloudflare AppConfigStore DOSame 2 MiB / 16 MiB state RPC limitsdeploy/state-service/wrangler.toml (CONFIG_STORE)
cloudflareCloudflare Workers nativeEmbedded AppConfigStore DO (one-time KV import)16 MiB request bodywrangler.toml / deploy/cloudflare/

Caddy Proxy Requirement: Keep protocols h1 and lb_retries 0 in deploy/self-hosted-state/Caddyfile so proxy retries never replay upstream generation or state mutations.

Native Cloudflare DO & Pages Compatibility ​

The root _worker.js + wrangler.toml setup (name = "aigateway", compatibility_date = "2026-06-30", compatibility_flags = ["global_fetch_strictly_public", "enable_request_signal"], observability.redact_query_string = true) runs natively with:

  • CONFIG_STORE -> AppConfigStore: SQLite-backed Durable Object (new_sqlite_classes, singleton name app-config-v1). KV is read at most once on initial DO bootstrap.
  • Cloudflare Pages: When binding a DO exported by an external Worker, explicitly add script_name under durable_objects.bindings in your Pages wrangler.toml.
  • cloudflare-model-map.json: Provides 65 default @cf/... model aliases aligned with DEFAULT_MODEL_MAP in _worker.js.

Environment Variables & Secrets Matrix ​

Gateway Platform Variables ​

VariableModesRequiredConstraints
ADMIN_PASSWORDAll gateway modesYesAdmin /admin password; /api/* fails closed with 503 if unset
MODELBRIDGE_STATE_URLcloudflare-remote, edgeone, esaRemote onlyExact https://<host>/_modelbridge/state URL without query, fragment, or userinfo
MODELBRIDGE_STATE_TOKENRemote gateways & state hostsRemote only32–512 printable non-space ASCII characters shared across gateway and state host
KV / CONFIG_STORENative Cloudflare DODO mode onlyWrangler bindings required for DO initialization and state storage

Self-Hosted State & CLI Variables ​

VariableScopeNotes
DB_PATHself-hosted-stateSQLite path; checks nlink === 1 and APPLICATION_ID = 0x4d425331 on existing files
MODELBRIDGE_STATE_PUBLIC_ORIGINself-hosted-stateExact HTTPS origin (e.g., https://state.example, no trailing slash)
MODELBRIDGE_STATE_ORIGINSself-hosted-state & state-serviceComma-separated exact HTTPS gateway origins; no wildcards or trailing slashes
MODELBRIDGE_STATE_TOKEN / _FILEself-hosted-stateSpecify exactly one (_FILE mounts /run/secrets/state_token in Compose)
HOST / PORTself-hosted-stateBind host and port (defaults: 127.0.0.1, 8788)
STATE_DOMAINcompose.yamlBare hostname used by Compose to construct MODELBRIDGE_STATE_PUBLIC_ORIGIN
MODELBRIDGE_STATE_EXPORT_ORIGINtools/state-admin.mjs export-remoteHTTPS origin sent during remote config export; must appear in MODELBRIDGE_STATE_ORIGINS
ANTIGRAVITY_* / OAUTH_CLIENT_*Worker env fallbackOptional fallback (ANTIGRAVITY_REFRESH_TOKEN, ANTIGRAVITY_API_KEY, ANTIGRAVITY_ACCOUNTS, ACCOUNTS_JSON, ANTIGRAVITY_EMAIL, ANTIGRAVITY_PROJECT_ID, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET)

Next Steps ​