Connect OpenCode#

Connect OpenCode to OptScale AI so agent chats use models from your organization catalog instead of a standalone vendor account.

In Chat, copy Base URL, API key, and Model name from Get connection values from Chat before you configure OpenCode.

For shared model naming rules and limitations, see External Tools overview.

Prerequisites#

Ensure the following prerequisites are met before configuring OpenCode:

• An organization exists and at least one Active provider is configured.
• Allowed providers are assigned to the user connecting OpenCode to OptScale AI.
• The OptScale AI deployment is accessible over HTTPS with a valid TLS certificate.
• For agent workflows that use tools, select models that support tool execution. For example, llama3:latest may not support tools.

Configure OpenCode#

1. Open File → Settings in OpenCode.

   

2. Go to Server → Providers, scroll to Custom provider, and click + Connect.

   

3. Enter the Provider ID and Display name. The Provider ID can contain only lowercase letters, numbers, hyphens (-), and underscores (_). For example, use optscale-ai as the Provider ID and OptScale AI as the Display name.

   

4. Enter the Base URL:

   • In OptScale AI Chat, select the provider and model you want to connect. Then go to Connect this model to external tools → OPENAI-COMPATIBLE and copy the Base URL value.

     

   • In OpenCode, paste the copied value into the Base URL field.

     

5. Enter the API key:

   • In the Connect this model to external tools → OPENAI-COMPATIBLE dialog in OptScale AI Chat, copy the API key value.

     

   • In OpenCode, paste the copied value into the API key field.

     

6. Configure the model in the Models section:

   • In the Connect this model to external tools → OPENAI-COMPATIBLE dialog in OptScale AI Chat, copy the Model name value.

     

   • In OpenCode, paste the copied value into the model-id field.

     

   • Enter a descriptive Display Name for the model, for example, OpenCode via OptScale AI.

     

7. Click Submit to save the provider configuration.

Models registered in OptScale AI are now available in the OpenCode chat.

Verify the OpenCode connection#

1. Open an OpenCode chat and select a configured model under your custom provider.
2. Send a test prompt and confirm that the model returns a response.
3. In the Admin UI, open Analytics → Traces or Analytics → Usage and Cost and confirm the request appears under your organization and user.

OpenCode setup notes#

• The Base URL from Chat must use HTTPS with a trusted certificate on your cluster (HTTP may appear only in local deployments).
• For OpenCode agent workflows that call tools, choose a model that supports tool execution.

See also#

• Get connection values from Chat — Shared Base URL, API key, and model values.
• External Tools — Overview and shared limitations.
• Connect Cursor — Point Cursor IDE at the gateway.
• Core Services — Traces — Verify requests after connecting.