# OpenCode

Set OpenCode up on OpenDunes once, with a default model and a small one.

[Coding agents](/docs/coding-agents) adds OpenDunes to OpenCode as a provider. This recipe names the model each session starts on, gives OpenCode's side tasks a smaller model, and runs a task from a script.

1. [Install OpenCode](#1-install-opencode).
2. [Write the provider and its models](#2-write-the-provider-and-its-models).
3. [Check the setup](#3-check-the-setup).
4. [Run it from a script](#4-run-it-from-a-script).

## 1. Install OpenCode

| With | Install line |
|---|---|
| the install script | `curl -fsSL https://opencode.ai/install \| bash` |
| npm | `npm install -g opencode-ai` |
| Homebrew | `brew install anomalyco/tap/opencode` |

Create an API key for OpenCode alone, and cap it on *API Keys* ([API keys](/docs/api-keys) shows how). Put it in your shell profile, `~/.zshrc` or `~/.bashrc`, as `export OPENDUNES_API_KEY="…"`.

## 2. Write the provider and its models

`~/.config/opencode/opencode.json` holds for every project. An `opencode.json` in a project is merged over it, key by key.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "opendunes": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OpenDunes",
      "options": {
        "baseURL": "https://opendunes.com/v1",
        "apiKey": "{env:OPENDUNES_API_KEY}"
      },
      "models": {
        "anthropic/claude-sonnet-4.5": {
          "name": "Claude Sonnet 4.5",
          "limit": { "context": 1000000, "output": 64000 }
        },
        "anthropic/claude-haiku-4.5": {
          "name": "Claude Haiku 4.5",
          "limit": { "context": 200000, "output": 64000 }
        }
      }
    }
  },
  "model": "opendunes/anthropic/claude-sonnet-4.5",
  "small_model": "opendunes/anthropic/claude-haiku-4.5"
}
```

| Key | Holds |
|---|---|
| `npm` | `@ai-sdk/openai-compatible`: OpenCode sends each request to [`POST /v1/chat/completions`](/docs/reference/chat-completions) |
| `options.apiKey` | `{env:OPENDUNES_API_KEY}`: OpenCode reads the key from the environment, and the file never holds it |
| `models` | each model OpenCode offers, by its ID in [Models](/docs/models), with how much it reads and writes |
| `model` | the model a session starts on: the provider, a slash, then the model ID |
| `small_model` | the model for side tasks, such as a session's title |

Each model is charged at its own rate, shown on its page in Models.

<div class="dont">
<p>Don't write the key itself into an <code>opencode.json</code> in a project. The file is committed, and the key goes with it.</p>
</div>

<div class="do">
<p>Keep <code>{env:OPENDUNES_API_KEY}</code>: the file can be shared, and each person runs it on their own key.</p>
</div>

## 3. Check the setup

```bash
opencode models opendunes
```

It lists the two models. Start `opencode` in your project: it opens on Claude Sonnet 4.5, and `/models` switches to another model for the session. Send one task, then open *Activity*, in the app on opendunes.com: each request is there, with its charge in DA.

## 4. Run it from a script

`opencode run` sends one task without the interface, prints the answer and exits:

```bash
opencode run "List the functions in src/ that have no test."
```

`-m opendunes/anthropic/claude-haiku-4.5` runs it on another model. In CI, set `OPENDUNES_API_KEY` from the CI's secrets, and give that job a key and a cap of its own.

## Errors

| Status | Means | Do |
|---|---|---|
| 401 | the key is missing, wrong, paused, revoked or expired | check `OPENDUNES_API_KEY` in the terminal OpenCode starts from |
| 402 | the balance is at zero or below, cannot pay the request's hold, or the key's cap is spent | make a deposit, or raise the cap |
| 404 | the model ID is not on sale | copy the ID from Models into `models` |

Every other status: [Errors and retries](/docs/errors-and-retries).

Next: [Cursor](/docs/cookbook/cursor) · [MCP servers](/docs/cookbook/mcp-servers)
