# OpenCode

Source: https://staging-docs.aiand.com/integrations/opencode/

[OpenCode](https://opencode.ai) is an open source AI coding agent available as a terminal interface, CLI, IDE extension, and desktop app. The [ai& OpenCode plugin](https://github.com/aiandlabs/aiand-opencode-plugin) adds ai& as a first-class OpenCode provider backed by the OpenAI-compatible ai& gateway.

The plugin:

- routes requests to `https://api.aiand.com/v1`;
- adds an **ai&** login method for API keys;
- loads ai&'s live model catalog into OpenCode's model picker.

<Aside type="note">
  Use a model with the `tool_calling` capability from the [catalog](/models/catalog/) for coding-agent workflows. `zai-org/glm-5.2` and `deepseek-ai/deepseek-v4-pro` are good defaults to try.
</Aside>

## Quick install

The fastest path is the hosted one-line installer. It installs OpenCode if it isn't already on your `PATH`, adds the `@aiand/opencode-plugin` plugin to your global OpenCode config, and sets a default ai& model — leaving any model you've already chosen untouched. It backs up your config before editing and is safe to re-run.

<Tabs syncKey="os">
<TabItem label="macOS / Linux">

```bash
curl -fsSL https://opencode.aiand.com/install.sh | bash
```

</TabItem>
<TabItem label="Windows">

Run the installer inside WSL:

```bash
curl -fsSL https://opencode.aiand.com/install.sh | bash
```

</TabItem>
</Tabs>

When it finishes, continue with **Authenticate** and **Run OpenCode** below. Prefer to set things up by hand? Follow the manual steps instead.

## 1. Install OpenCode

For the terminal or one-shot CLI:

<Tabs syncKey="os">
<TabItem label="macOS / Linux">

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

Other supported installers include npm and Homebrew:

```bash
npm install -g opencode-ai
brew install anomalyco/tap/opencode
```

</TabItem>
<TabItem label="Windows">

OpenCode recommends WSL for the terminal experience. You can also install the Windows package:

```powershell
choco install opencode
```

or:

```powershell
scoop install opencode
```

</TabItem>
</Tabs>

For the desktop app, download **OpenCode Desktop (Beta)** from [opencode.ai/download](https://opencode.ai/download). On macOS, you can also install it with Homebrew:

```bash
brew install --cask opencode-desktop
```

## 2. Add the ai& plugin

Add the npm plugin to an OpenCode config file. Use a project config when only this repository should use ai&, or a global config when you want ai& available in the terminal and the Desktop app across projects.

- **Project:** `opencode.json` in your project root
- **Global:** `~/.config/opencode/opencode.json` or `~/.config/opencode/opencode.jsonc`

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@aiand/opencode-plugin"],
  "model": "aiand/zai-org/glm-5.2"
}
```

OpenCode installs npm plugins automatically on startup and caches them. To pin a version or force a cached upgrade, include the version explicitly:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@aiand/opencode-plugin@0.1.0"],
  "model": "aiand/zai-org/glm-5.2"
}
```

<Aside type="tip">
  Model names use `aiand/<model-id>`. The plugin fetches ai&'s public catalog at startup, so new ai& models appear in OpenCode without a plugin update.
</Aside>

## 3. Authenticate

Create an API key in the [ai& console](https://console.aiand.com), then choose one auth path.

### Terminal login

```bash
opencode auth login
```

Choose **ai&**, then paste your `sk-...` key. OpenCode stores the credential and reuses it for future sessions.

### Inside OpenCode

In the OpenCode TUI or Desktop app, run:

```text
/connect
```

Select **ai&**, choose the API key method, and paste your key.

### Environment variable

For CI, scripts, or non-interactive runs:

<Tabs syncKey="os">
<TabItem label="macOS / Linux">

```bash
export AIAND_API_KEY="sk-your-aiand-api-key"
```

</TabItem>
<TabItem label="Windows (PowerShell)">

```powershell
$env:AIAND_API_KEY = "sk-your-aiand-api-key"
```

</TabItem>
</Tabs>

<Aside type="caution">
  For the Desktop app, prefer `/connect` or `opencode auth login`. Environment variables only work when the desktop process is launched from an environment that already contains `AIAND_API_KEY`.
</Aside>

## 4. Run OpenCode

Interactive terminal UI:

```bash
opencode
```

One-shot CLI:

```bash
opencode run "say hi in one word"
```

Use the model picker when you want to switch models:

```text
/models
```

## Desktop App

The Desktop app uses the same OpenCode provider setup. For the smoothest setup:

1. Install **OpenCode Desktop (Beta)** from [opencode.ai/download](https://opencode.ai/download).
2. Put the plugin in your global config at `~/.config/opencode/opencode.json`.
3. Open a project folder in the Desktop app.
4. Run `/connect`, select **ai&**, and paste your API key.
5. Run `/models` and choose an `aiand/...` model, or rely on the `model` value in your config.

This keeps the Desktop app, terminal TUI, and `opencode run` using the same ai& provider and model catalog.

## Verify

Check that OpenCode can see ai& models:

```bash
opencode run -m aiand/zai-org/glm-5.2 "reply with only: ok"
```

You can also test the key directly against ai&:

<Tabs syncKey="os">
<TabItem label="macOS / Linux">

```bash
curl -sS https://api.aiand.com/v1/models \
  -H "Authorization: Bearer $AIAND_API_KEY"
```

</TabItem>
<TabItem label="Windows (PowerShell)">

```powershell
Invoke-RestMethod https://api.aiand.com/v1/models `
  -Headers @{ Authorization = "Bearer $env:AIAND_API_KEY" }
```

</TabItem>
</Tabs>

## Troubleshooting

- **No ai& provider appears** — confirm the config file contains `"plugin": ["@aiand/opencode-plugin"]`, then restart OpenCode so it loads the plugin.
- **Model picker is empty** — the plugin could not fetch `https://api.aiand.com/v1/api.json`. Check network access, proxy settings, or set `AIAND_BASE_URL` if you use a different ai& environment.
- **Unauthorized request** — run `opencode auth login` again or confirm `AIAND_API_KEY` is set in the process running OpenCode.
- **The Desktop app does not see your key** — authenticate with `/connect` in Desktop, or launch Desktop from a shell where `AIAND_API_KEY` is already exported.