Connect official subscription accounts
Connect ChatGPT / Codex, Claude, Gemini CLI / Code Assist, and Antigravity through OAuth, configure models, and grant gateway access.
Prepare an account and administrator access
Use an eligible upstream account and a console account allowed to manage the channel. Super administrators manage public channels; organization administrators manage their organization’s private channels. Subscription channels follow organization bindings, model permissions, gateway keys, quotas, and usage recording.
The account holder can sign in through an authorization link copied by the administrator without accessing BOS Admin. Application developers continue to use a BOS API gateway key; administrators maintain the upstream subscription authorization in the channel.
Continue when the localhost callback cannot open
OpenAI may redirect to localhost:1455/auth/callback; Antigravity uses localhost:8085/callback. ERR_CONNECTION_REFUSED usually means there is no local callback listener and alone does not establish an OAuth denial. Copy the entire address, including code and state, paste it into the original BOS form, and save.
This flow does not require publishing a callback port on the deployment server and does not return to BOS automatically. The account is connected only after BOS successfully exchanges the code and saves the channel.
Discover models and grant request access
- OpenAI, Claude, and Antigravity use the authorized account’s official model catalogs. A discovery failure preserves the saved account; retry from the model drawer or edit the channel to add model names manually. A channel without configured models cannot serve model requests.
- Gemini CLI / Code Assist has no equivalent model catalog here. Discovery checks account connectivity and retains manually configured models without inventing models or token limits. Add only models the account can actually use.
- Explicitly bind and enable a public channel for the organization; private channels follow their organization’s permissions. Issue a gateway key authorized for the models. Test a small request using the matching protocol, then streaming and tool calls, and verify usage and the Request ID.
Choose the protocol for each account
| Account | Primary interface and support | Limits |
|---|---|---|
| ChatGPT / Codex | Responses JSON / SSE and existing Codex WebSocket and compaction routes. | Chat / Messages compatibility is limited to plain non-streaming conversations. Use Responses for Codex tools and streaming. Subscription OAuth does not grant OpenAI embeddings or image API access. |
| Claude | Messages JSON / SSE, count_tokens, and existing Chat conversion. | Use an authorized model with the Anthropic protocol; existing cross-protocol limits still apply. |
| Gemini CLI / Code Assist | Gemini generateContent JSON, streamGenerateContent SSE, and existing Chat / Messages conversion. | Token counting depends on access to Google’s generative-language endpoint. Code Assist embeddings are unsupported. A consumer Gemini subscription does not guarantee Code Assist or all model access. |
| Antigravity | Gemini generateContent JSON, streamGenerateContent SSE, and existing Chat / Messages conversion. | Uses its own OAuth client and project identity. Token counting is unavailable and returns a capability error. |
Gemini project discovery and troubleshooting
Gemini first resolves a managed project through loadCodeAssist. Eligible new users can be onboarded automatically while BOS waits for asynchronous operations. If no project is returned, BOS queries existing ACTIVE Google Cloud projects with the same account token, preferring a unique Code Assist / companion project, then a unique default project, then the sole remaining project. It does not create Cloud projects, enable APIs, or change billing.
If there is no accessible project or multiple equally suitable candidates, enter the account’s Google Cloud Project ID in the authorization form and authorize again. Google permission and operation errors are reported directly; inspect the error and account eligibility rather than treating a missing project as success. Antigravity also accepts a project ID in its authorization form.
Deployment and optional OAuth clients
The updated backend includes separate default OAuth clients for Gemini CLI and Antigravity. When both variables for a platform are empty or unset, the built-in default requires no extra configuration. Set both only to use another compatible client. An incomplete pair causes authorization and refresh configuration errors; the platforms do not share clients.
BOS_GEMINI_OAUTH_CLIENT_ID=
BOS_GEMINI_OAUTH_CLIENT_SECRET=
BOS_ANTIGRAVITY_OAUTH_CLIENT_ID=
BOS_ANTIGRAVITY_OAUTH_CLIENT_SECRET=For Compose, edit the server’s existing private deploy/stack.env, preserving database passwords and encryption keys. These values identify the OAuth application and differ from upstream API keys, user access tokens, and callback authorization codes.
./deploy/stack.sh startRun in the application deployment directory after updating the backend and Compose definition. This uses existing images and recreates containers whose environment changed. docker restart or docker compose restart does not inject new environment values. Rebuild and deploy source changes first.
- A custom Gemini client must register https://codeassist.google.com/authcode; Antigravity must register http://localhost:8085/callback.
- The deployed stack does not read backend/.env.example. For a directly launched backend, set variables in the process environment and restart it.
- Pending OAuth sessions are in memory and are lost on restart. Use one application instance or sticky routing while authorizing across replicas. Saved account credentials persist in MySQL.
Refresh, reauthorize, and verify
Access tokens, refresh tokens, account / project identity, and expiry use the existing encrypted credential field and are excluded from provider API responses. When less than one minute remains, the gateway refreshes under a database row lock and saves rotated tokens. Requests and replicas sharing the database reuse the refreshed credential. A refresh failure preserves the stored credential and fails the request.
For expired, revoked, or replacement authorization, edit the existing channel, choose Restart official account sign-in, and save after completion to retain the channel ID and bindings. This feature requires no new schema migration or background service. Verify live sign-in, account eligibility, upstream availability, and inference in your deployment.
Match capabilities and procedures to your deployment version. Read the documentation scope