> For the complete documentation index, see [llms.txt](https://thegrid.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thegrid.ai/docs/integrations-and-best-practices/integrations/opencode.md).

# OpenCode Integration with The Grid | Provider Setup

OpenCode ships with a `/connect` flow that adds The Grid as a provider in one step. No JSON to edit, no config scope to choose. Run `opencode auth /connect`, pick The Grid, paste your consumption key, and the agent loop runs on market-priced inference.

## Prerequisites

* OpenCode installed (`opencode --version` to check).
* A Grid account at [app.thegrid.ai](https://app.thegrid.ai).
* Credits in your account. The Grid is prepaid; zero credits returns 402.
* A Grid consumption API key from **Settings → API Keys → Create Consumption Key**.

## Setup

### 1. Get your Grid consumption API key

Log into [app.thegrid.ai](https://app.thegrid.ai). Go to **Settings → API Keys → Create Consumption Key** and copy it.

### 2. Run `opencode auth /connect`

```bash
opencode auth /connect
```

Select **The Grid** from the provider list. Paste your Grid consumption key when prompted. OpenCode persists the credential for you.

### 3. Pick your `model` and `small_model`

OpenCode separates a primary `model` from a cheaper `small_model` used for title generation, summaries, and utility calls. Map both to Grid instruments. A useful default for coding agents:

* `model`: `code-prime`
* `small_model`: `code-standard`

Set them in the TUI with `/model thegrid/code-prime` and the equivalent setting for `small_model`. Instrument tiers and use cases live in the [current instruments list](/docs/instrument-specifications/current-instruments.md).

### 4. Set token limits to avoid context overflow

OpenCode decides how much of the conversation to send from each model's `limit.context` and `limit.output`. When `limit.input` is set, it uses that as the input budget; when it isn't, it derives the budget as context minus output. On long coding turns with large file context and tool results, a missing or wrong limit makes OpenCode pack a request that overruns the window and returns a 400.

If you connected through `auth /connect` and The Grid's models come from the shared registry, the limits travel with them. If you wired The Grid as a custom provider, set the limits yourself per instrument:

```json
{
  "provider": {
    "thegrid": {
      "models": {
        "code-prime": {
          "limit": { "context": 128000, "input": 120000, "output": 32000 }
        },
        "code-max": {
          "limit": { "context": 1000000, "input": 922000, "output": 128000 }
        }
      }
    }
  }
}
```

Keep `output` below `context` so input plus output fits in one request. Use 120,000 for input on Standard and Prime instruments and 922,000 on the Max instruments. For an instrument not shown here, get its context window from the [current instruments list](/docs/instrument-specifications/current-instruments.md).

### 5. Launch OpenCode

```bash
opencode
```

The Grid's instruments appear in the `/model` picker.

## Verification

Run a quick non-interactive check against both tiers:

```bash
opencode run --model thegrid/code-prime "Reply with OK only."
opencode run --model thegrid/code-standard "Reply with OK only."
```

If both return `OK`, the provider is wired up, the key is valid, and both tiers route correctly.

## Troubleshooting

{% hint style="warning" %}
**401 on the first request.** Your key is a Grid trading key, not a consumption key. Trading keys authorize the order book, not inference. Generate a new consumption key and run `opencode auth /connect` again.
{% endhint %}

{% hint style="warning" %}
**402 Payment Required.** Your credits are at zero. Top up at [app.thegrid.ai](https://app.thegrid.ai), or enable Auto Buy so long agent runs do not stall.
{% endhint %}

{% hint style="info" %}
**The Grid's instruments don't appear in `/model`.** Restart OpenCode after `auth /connect`. If the providers list still excludes The Grid, run `auth /connect` again to re-register.
{% endhint %}

{% hint style="info" %}
**Token counts don't match the Grid dashboard.** OpenCode's built-in counter is provider-agnostic and does not see Grid market pricing. Real spend is in the Grid dashboard.
{% endhint %}

{% hint style="warning" %}
**400 "input length too long" or context errors on big turns.** OpenCode packed more than the instrument's window because the input or output limit isn't set right. Add the `limit` block from Setup step 4, keeping `output` below `context`. If you connected through the shared registry and still see this, set the limits explicitly as a custom provider.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://thegrid.ai/docs/integrations-and-best-practices/integrations/opencode.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.