🔄 Gateway Lifecycle
GATEWAY LIFECYCLE
1. Self-Register
→Bridge starts, loads adapter, calls Convex with gateway name, URL, capabilities, token
2. Health Monitor
→Convex pings every 60s. Updates status: healthy, degraded, or offline.
3. Dispatch
→Interpreter routes steps. Governance checks health before every dispatch.
4. Deregister
Graceful shutdown. InstanceId prevents races.
HEALTH STATUS
Healthy
Dispatch proceeds normally
Degraded
Dispatch + logged warning
Offline
Dispatch blocked by gate
Registration Fields
| Field | Purpose |
|---|---|
gatewayId | Stable identifier from Bridge (deduplication key) |
name | Human-readable display name |
environment | production, staging, dev, or custom label |
url | Gateway HTTP endpoint |
token / tokenHash | Authentication credential (SHA-256 hash for secure storage) |
instanceId | Per-process UUID to prevent deregister races during rolling deploys |
registrationSource | self (auto-registered) or manual (operator-configured) |
capabilities | Declared gateway capabilities (see below) |
💚 Health Checking
A cron job runs every 60 seconds (gateway health check) and pings all registered gateways:
| Status | Meaning | Dispatch behavior |
|---|---|---|
| healthy | Gateway responded within timeout | Dispatch proceeds normally |
| degraded | Gateway responded with warnings | Dispatch proceeds with a logged warning |
| offline | Gateway did not respond | Dispatch blocked by gatewayHealthGate |
gatewayHealthHistory table and retained for 90 days.
The governance pipeline’s first gate (
gatewayHealthGate) checks the gateway’s current status before every dispatch. An offline gateway blocks all step execution — no step can bypass this gate.🧩 Gateway Capabilities
Each gateway declares its capabilities at registration time. The platform uses these for routing decisions and feature availability.| Capability | Type | Description |
|---|---|---|
streaming | boolean | Can emit events during execution (tool calls, partial output) |
sessionResume | boolean | Can resume a prior conversation/session via resume token |
fileIO | boolean | Agent can read/write files on the host filesystem |
mcpServers | boolean | Supports Model Context Protocol tool servers |
sandboxing | boolean | Provides built-in execution isolation |
subagents | boolean | Supports native subagent orchestration |
costTracking | boolean | Reports cost per execution in the result |
structuredOutput | boolean | Supports structured/JSON output mode |
management | boolean | Supports the RuntimeManager interface (agent sync, management) |
maxConcurrent | number | Maximum concurrent executions |
outputStrategies | string[] | Supported output capture methods: file, stream, structured |
costTier | string? | Cost classification: low, medium, high |
latencyProfile | string? | Latency classification: fast, moderate, variable |
Capability Comparison
| Capability |  OpenClaw |  Claude Agent SDK | Vercel AI | Gloo AI |
|---|---|---|---|---|
| Streaming | Yes | Yes | No | Yes |
| Session Resume | Yes | Yes | No | No |
| File I/O | Yes | No | No | No |
| MCP Servers | Yes | No | No | No |
| Sandboxing | Yes | No | No | No |
| Subagents | No | Yes | No | No |
| Cost Tracking | Yes | Yes | No | Yes |
| Structured Output | No | Yes | Yes | No |
| Management | Yes | No | No | No |
| Auto-Routing | No | No | No | Yes |
| Grounded Completions | No | No | No | Yes (opt-in) |
| Tradition | No | No | No | Yes (opt-in) |
🔌 Multi-Gateway Support
Forge supports multiple gateways simultaneously. The interpreter routes steps to specific gateways based on deployment configuration. With multi-adapter Bridge, multiple gateways can share a single Bridge URL — Bridge loads all configured adapters and routes each dispatch to the correct one by provider name.Gloo AI’s unique feature is intelligent model routing. It analyzes each request and selects the optimal model tier automatically — simple tasks get fast, cost-effective models while complex tasks get more powerful ones. Agents deployed to a Gloo AI gateway do not need hard-coded model assignments.
- Routing
- Trust Levels
- Environment Eligibility
Steps are routed to gateways through the deployment binding. When a workflow is deployed, it specifies which gateway to use. The interpreter resolves the gateway at dispatch time via
resolveRoutingCandidates() and routeExecution().🔐 The Ownership Boundary
The most important architectural principle in Forge’s gateway model:OWNERSHIP BOUNDARY
Convex OwnsWhat to executeWhether to executeWhat happenedHow much it costWho did it
Durable state, audit trail, governance
Gateway Owns
How to executeLive execution stateRuntime environmentAgent workspace
Ephemeral — nothing is lost if gateway crashes
🔑 Token Rotation
Gateways authenticate with Convex using tokens. Forge supports zero-downtime token rotation:- A new token is generated and set as the current token. The previous token is stored in
previousTokenwith an expiration timestamp. - During the rotation window, both tokens are accepted.
- After
previousTokenExpiresAt, only the new token is valid. - Callbacks include a
tokenVersionheader for version tracking.