<!-- Token4AI Cloud Attribution Developed by the commercial cloud service company represented by https://token4ai.cloud. Author: jamesduan (X: https://x.com/JamesDuanL) Created: 2026-06-11 description: Token4AI Cloud, FerroGate AI Gateway, TypeScript on Cloudflare Workers, agent-native AI traffic infrastructure. -->

FerroGate

Language: English | 简体中文

FerroGate is an open-source AI gateway that runs entirely on Cloudflare Workers. It is a control point for AI traffic: OpenAI-compatible and Anthropic-native inference APIs, multi-vendor provider routing with canary and shadow rollouts, virtual API keys with scopes and tenant isolation, policy and guardrail screening, rate limits, quotas and prepaid wallets, durable token metering and billing, an asset closed loop, an MCP server, agent runs, and a ~250-operation admin API.

It is written in TypeScript end to end and deploys as a fleet of Workers backed by D1, R2, KV, Durable Objects, Queues and Analytics Engine.

The project is developed as the open-source gateway foundation behind Token4AI Cloud.

Architecture at a glance

Six deployables live under apps/. Five are Workers; the sixth is a CLI binary.

Deployable	Worker name	What it is
apps/gateway	ferrogate-gateway	The data plane. A Hono streaming proxy for inference, plus the asset surface. Owns 31 contract operations.
apps/control-plane	ferrogate-control-plane	The admin API — 197 contract operations (192 under /admin/v1/**, plus the /admin pages and /metrics), and the admin-console session surface, SAML, OIDC and SCIM.
apps/mcp	ferrogate-mcp	Model Context Protocol server: JSON-RPC ingress, OAuth flow, sessions, governed tool execution. 6 contract operations.
apps/agent-runtime	ferrogate-agent-runtime	Agent runs and jobs, A2A agent upstreams, and the self-hosted worker plane. 15 contract operations.
apps/telemetry	ferrogate-telemetry	OTLP receiver that writes to Analytics Engine. Owns no contract route; the other Workers feed it over a service binding.
apps/cli	—	ferrogate, the management CLI. A Bun-compiled binary, not a Worker.

/healthz and /readyz are implemented in every Worker.

The gateway request path

A request to apps/gateway passes through one table-driven chain, in this order:

1. Request id and request metrics.
2. Network gate — pre-auth IP allow/deny, so a flood never pays for a credential lookup.
3. Contract auth — one guard for all 251 operations, driven by the route contract's auth.kind / auth.scope / rbac_action.
4. Admission — rate limit (Durable Object counter), quota, monthly budget, prepaid wallet hold.
5. Guardrails — request-stage screening.
6. Drain gate — 503 node_draining on spend-producing operations when the fleet is drained.
7. Response cache — exact-match or opt-in semantic (in-tree feature-hashing embedder and cosine similarity; no vector database), over the Cache API.
8. Zod validation, then the model registry (logical models, fallback, canary and shadow splits).
9. Upstream dispatch — provider adapters with a circuit breaker Durable Object, retry and failover; SSE framing is preserved byte-for-byte and a client disconnect aborts the upstream.
10. Durable metering — the ledger row and the billing-outbox row commit in the same D1 batch(), then publish onto a Queue.

Per-tenant D1 routing sits behind the auth step, so tenant state can live in an isolated database per tenant.

Shared packages

Fifteen packages under packages/. Each exports src/*.ts directly — there is no per-package build step.

Package	Responsibility
core	Request identity, tenant/workspace attribution, tool primitives, approval policy, redaction guard, boundary errors.
schemas	Zod wire envelopes and the OpenAPI contract registry.