---
title: "Connect OpenCode to AI Gateway or an AI Agent | Hostman Docs"
description: "Learn how to install OpenCode and connect it to Hostman AI Gateway or a custom AI agent via the TUI/CLI config file or the desktop app provider settings."
---

> For the complete documentation index for AI agents, see [llms.txt](https://hostman.com/llms.txt).

OpenCode is an AI coding assistant that lets you ask questions about your project, edit code, and run commands—all without leaving your current workflow.

You can connect either an AI agent or an AI Gateway to OpenCode. With an AI agent, you work with a pre-configured agent setup; with AI Gateway, you call the model directly.

## Installing OpenCode

OpenCode runs on Windows, Linux, and macOS, and is available as a TUI/CLI tool or a desktop app.

### Installing the TUI/CLI Version 

Use your preferred method:

#### curl

```shell
curl -fsSL https://opencode.ai/install | bash
```

#### npm

```shell
npm i -g opencode-ai
```

#### bun

```shell
bun add -g opencode-ai
```

#### Homebrew

```shell
brew install anomalyco/tap/opencode
```

#### paru

```shell
paru -S opencode
```

### Installing the Desktop App

Use Homebrew:

```shell
brew install --cask opencode-desktop
```

Alternatively, download the binary directly from the [OpenCode website](https://opencode.ai/download) and install it manually.

## Connection Requirements

You can connect either an AI agent or an AI Gateway to OpenCode.

To connect an AI agent, you'll need:

-   [The agent's base URL](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/#base-url)
-   [An API key](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/)

To connect AI Gateway, you'll need:

-   Base URL: `https://ai-api.hostman.com/v1`
-   [An API key](https://hostman.com/docs/ai-agents/ai-gateway/connection/#creating-an-api-key)

## Configuring the Connection

### TUI/CLI

Use this method if you're running the TUI/CLI version of OpenCode.

1.  Create or edit the `opencode.json` configuration file. You can place it in one of two locations:
    

-   Project root: settings apply to that project only
    
-   `~/.config/opencode/opencode.json`: settings apply globally across all projects
    

3.  Add the following configuration:
    

```shell
{
 "$schema": "https://opencode.ai/config.json",
 "provider": {
   "hostman": {
     "npm": "@ai-sdk/openai-compatible",
     "name": "Hostman",
     "options": {
       "baseURL": "https://ai-api.hostman.com/v1"
     },
     "models": {
       "openai/gpt-5-mini": {
         "name": "openai/gpt-5-mini"
       }
     }
   }
 },
 "model": "openai/gpt-5-mini"
}
```

Adjust the values to match your setup:

-   -   `baseURL`: if you're connecting an AI agent, replace this with your agent's base URL. For AI Gateway, leave it as-is.
        
    -   `models`: the list of models that will be available in OpenCode.
        
    -   `model`: for AI Gateway, specify the model name—for example, `openai/gpt-5-nano`. For an AI agent, use the model name from your agent settings. [Check the **Check the Connection tab** tab](https://hostman.com/docs/ai-agents/ai-gateway/connection/#getting-connection-details) for the correct identifier.
        
    -   `name`: optional; change the provider display name if needed.
        

3.  Save and close the file.
    
4.  Set your API key. Start OpenCode in the terminal:
    

```shell
opencode
```

5.  In the TUI, run:
    

```shell
/connect
```

6.  Scroll down through the provider list and select **Other**.
    
7.  Enter the provider ID. This must match the provider key in `opencode.json` —in this example, `hostman`.
    
8.  Paste your API key.
    

OpenCode saves the key to an encrypted global auth file.

You can now use OpenCode. If you exited the TUI, restart it, then select your model by running:

```shell
/model
```

Search for the provider name you set earlier, then verify the connection by sending a message in the chat.

### Desktop App

1.  Click the gear icon to open settings.
    
2.  Go to the **Providers** tab.
    
3.  Scroll down and select **Custom provider**.
    
4.  Click **Connect**.
    
5.  Fill in the connection details:
    

-   **Provider ID**: a unique identifier you'll use to find this provider later
    
-   **Display name**: how the provider appears in the interface
    
-   **Base URL**: your agent's base URL or the AI Gateway URL
    
-   **API key**: the key for your agent or AI Gateway
    
-   **Models**: the list of models available for selection
    

7.  For AI Gateway, model names must follow the AI Gateway format—for example, `openai/gpt-5-nano`. [Check the Connection tab](https://hostman.com/docs/ai-agents/ai-gateway/connection/#getting-connection-details) for the correct identifier. For an AI agent, you can use any name.
    
8.  Click **Submit** to save.
    

Find and select your model in the chat, then verify the connection by sending a test message.