|
| 1 | +--- |
| 2 | +title: Factory Droid bridge |
| 3 | +description: Connect Factory Droid models to opencodex through a local Responses-compatible bridge. |
| 4 | +--- |
| 5 | + |
| 6 | +Factory Droid is an agent runtime, not a documented OpenAI-compatible inference endpoint. If a |
| 7 | +custom provider pointed at an internal Factory LLM URL returns `403 Forbidden`, changing only the |
| 8 | +opencodex adapter or adding provider headers does not make that private route a supported public API. |
| 9 | + |
| 10 | +The working integration is: |
| 11 | + |
| 12 | +```text |
| 13 | +Text-only Responses client |
| 14 | + -> opencodex (http://127.0.0.1:10100/v1/responses) |
| 15 | + -> local Responses bridge (http://127.0.0.1:11435/v1/responses) |
| 16 | + -> official droid exec command |
| 17 | + -> Factory account and selected model |
| 18 | +``` |
| 19 | + |
| 20 | +This keeps the Factory credential inside the official Droid client. OpenCodex receives a separate, |
| 21 | +local-only bridge token. |
| 22 | + |
| 23 | +## What failed and why |
| 24 | + |
| 25 | +| Symptom | Cause | Fix | |
| 26 | +| --- | --- | --- | |
| 27 | +| `403 Forbidden` from a Factory LLM URL | The URL is not a documented general-purpose OpenAI endpoint for third-party clients | Invoke Factory through the official Droid CLI or SDK | |
| 28 | +| `404` at `/models/models` | The provider base URL already ended in `/models` | Use an API root as `baseUrl`; never include the discovery path | |
| 29 | +| Model search fails | The bridge does not expose a complete live catalog | Set `liveModels: false` and provide a static `models` list | |
| 30 | +| Loopback provider is rejected | Private-network access is denied by default | Set `allowPrivateNetwork: true` only for the loopback bridge | |
| 31 | +| `${DROID_BRIDGE_TOKEN}` is unresolved | The variable is missing from the opencodex service environment | Inject it into the service process, not only an interactive shell | |
| 32 | +| `OutputTextDelta without active item` | The bridge emitted a text delta before opening an output item and content part | Emit the complete Responses SSE lifecycle in order | |
| 33 | + |
| 34 | +The same Factory credential can therefore work in `droid exec` while a direct request to an |
| 35 | +undocumented LLM URL still returns `403`. Those results test different products and should not be |
| 36 | +treated as contradictory. |
| 37 | + |
| 38 | +## Prerequisites |
| 39 | + |
| 40 | +1. Install and sign in to the [Droid CLI](https://docs.factory.ai/droid-cli/quickstart). |
| 41 | +2. Confirm a bounded headless request works: |
| 42 | + |
| 43 | + ```bash |
| 44 | + droid exec --model glm-5.2 --output-format json "Reply with DROID_OK only." |
| 45 | + ``` |
| 46 | + |
| 47 | +3. Run a local bridge that invokes `droid exec` (or the official Droid SDK) and exposes: |
| 48 | + |
| 49 | + - `GET /healthz` |
| 50 | + - `GET /v1/models` |
| 51 | + - `POST /v1/responses` |
| 52 | + |
| 53 | +Factory documents `droid exec` as its non-interactive automation surface and recommends JSON output |
| 54 | +for scripts. For a longer-lived integration, Factory also documents stream JSON-RPC and official |
| 55 | +TypeScript and Python SDKs in the |
| 56 | +[Droid Exec guide](https://docs.factory.ai/droid-exec/overview). |
| 57 | + |
| 58 | +## Bridge contract |
| 59 | + |
| 60 | +Bind the bridge to `127.0.0.1`, require a randomly generated bearer token, cap request sizes, and |
| 61 | +allowlist model IDs. The minimal bridge accepts only these Responses `input` shapes: |
| 62 | + |
| 63 | +- a non-empty string; or |
| 64 | +- an array containing only `message` items. Each message must have a `user`, `developer`, `system`, |
| 65 | + or `assistant` role and either string content or text-only content parts (`input_text` for input |
| 66 | + roles and `output_text` for assistant history). |
| 67 | + |
| 68 | +Validate the complete request before invoking Droid. If an input part is an image or file, `tools` |
| 69 | +contains any tool definition, or `input` contains a tool call or result (`function_call`, |
| 70 | +`function_call_output`, `custom_tool_call`, or `custom_tool_call_output`), return HTTP `400` with a |
| 71 | +Responses-style `invalid_request_error`. Use a stable bridge-specific code such as |
| 72 | +`unsupported_bridge_input` and identify the rejected field in the message. Do this before starting |
| 73 | +SSE, even when `stream: true`; never discard, stringify, or flatten unsupported content into the |
| 74 | +prompt. |
| 75 | + |
| 76 | +```json |
| 77 | +{ |
| 78 | + "error": { |
| 79 | + "type": "invalid_request_error", |
| 80 | + "code": "unsupported_bridge_input", |
| 81 | + "param": "tools", |
| 82 | + "message": "The minimal Droid bridge does not accept tool definitions." |
| 83 | + } |
| 84 | +} |
| 85 | +``` |
| 86 | + |
| 87 | +For an accepted request, the bridge should: |
| 88 | + |
| 89 | +1. Convert the accepted Responses `input` to a prompt. |
| 90 | +2. invoke `droid exec --model <id> --output-format json <prompt>`; |
| 91 | +3. parse the final `result` and `session_id`; |
| 92 | +4. return an OpenAI Responses envelope; and |
| 93 | +5. map `previous_response_id` to the Droid session ID when continuation is required. |
| 94 | + |
| 95 | +For streaming responses, emit this lifecycle in order: |
| 96 | + |
| 97 | +```text |
| 98 | +response.created |
| 99 | +response.output_item.added |
| 100 | +response.content_part.added |
| 101 | +response.output_text.delta |
| 102 | +response.output_text.done |
| 103 | +response.content_part.done |
| 104 | +response.output_item.done |
| 105 | +response.completed |
| 106 | +``` |
| 107 | + |
| 108 | +Do not expose the bridge on `0.0.0.0` and do not reuse the Factory credential as the bridge bearer |
| 109 | +token. |
| 110 | + |
| 111 | +## OpenCodex provider configuration |
| 112 | + |
| 113 | +Create the custom provider with the explicit provider ID `droid`: |
| 114 | + |
| 115 | +```bash |
| 116 | +ocx provider add droid \ |
| 117 | + --adapter openai-responses \ |
| 118 | + --base-url http://127.0.0.1:11435/v1 \ |
| 119 | + --default-model glm-5.2 \ |
| 120 | + --allow-private-network |
| 121 | +``` |
| 122 | + |
| 123 | +This creates the `providers.droid` config entry. In the dashboard, open **Providers → droid → Edit |
| 124 | +JSON** and replace that provider's value with: |
| 125 | + |
| 126 | +```json |
| 127 | +{ |
| 128 | + "adapter": "openai-responses", |
| 129 | + "baseUrl": "http://127.0.0.1:11435/v1", |
| 130 | + "responsesPath": "/responses", |
| 131 | + "allowPrivateNetwork": true, |
| 132 | + "authMode": "key", |
| 133 | + "apiKey": "${DROID_BRIDGE_TOKEN}", |
| 134 | + "liveModels": false, |
| 135 | + "models": ["glm-5.2", "glm-5.2-fast", "kimi-k3"], |
| 136 | + "defaultModel": "glm-5.2" |
| 137 | +} |
| 138 | +``` |
| 139 | + |
| 140 | +The model IDs are examples. Keep only models that `droid exec` can use for the signed-in Factory |
| 141 | +account. Do not add Factory-specific inference headers to this provider: its upstream is the local |
| 142 | +bridge, not a Factory HTTP endpoint. |
| 143 | + |
| 144 | +After saving a provider or changing its static catalog, synchronize and restart the Codex |
| 145 | +app-server so new sessions read the updated catalog: |
| 146 | + |
| 147 | +```bash |
| 148 | +ocx sync --restart-codex |
| 149 | +ocx doctor |
| 150 | +``` |
| 151 | + |
| 152 | +Restarting Codex app-server processes interrupts active Codex work. Run the restart only after |
| 153 | +finishing or saving those sessions. |
| 154 | + |
| 155 | +## Verify the complete route |
| 156 | + |
| 157 | +Check each boundary separately: |
| 158 | + |
| 159 | +```bash |
| 160 | +curl -fsS http://127.0.0.1:11435/healthz |
| 161 | +ocx doctor |
| 162 | +ocx access test droid/glm-5.2 --protocol responses |
| 163 | +``` |
| 164 | + |
| 165 | +A provider row or model-picker entry proves only catalog visibility. The integration is working only |
| 166 | +after the Responses probe returns through the `droid/<model>` route. |
| 167 | + |
| 168 | +## Current limitation |
| 169 | + |
| 170 | +The minimal bridge above translates text and the Responses SSE lifecycle. It does **not** implement |
| 171 | +the full bidirectional Codex function/tool-call protocol. Codex App and `codex exec` normally send |
| 172 | +tool definitions even when a prompt says not to call tools, and the current Codex CLI has no general |
| 173 | +flag that removes those definitions. The minimal bridge must reject those requests with the `400` |
| 174 | +contract above. Tool definitions, tool calls, tool results, permissions, cancellation, and rich |
| 175 | +Droid events require a stateful bridge built on Factory's stream JSON-RPC mode or an official Droid |
| 176 | +SDK. Treat `ocx access test` success as text-path verification, not Codex agent or tool-path |
| 177 | +verification. |
0 commit comments