> ## Documentation Index
> Fetch the complete documentation index at: https://sambanova-systems.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode integration guide

[OpenCode](https://opencode.ai/) is an open-source coding assistant that works across terminals, IDEs, and desktop apps. It supports automatic LSP setup, multiple parallel sessions, and session sharing for collaboration or debugging.

## Prerequisites

Before starting, ensure you have:

* A [SambaCloud](https://cloud.sambanova.ai/?utm_source=opencode\&utm_medium=external\&utm_campaign=cloud_signup) account and API key
* Node.js 18 or later (if installing via npm)

## Installation and setup

<Steps>
  <Step title="Install OpenCode">
    <Tabs>
      <Tab title="curl">
        ```bash theme={null}
        curl -fsSL https://opencode.ai/install | bash
        ```
      </Tab>

      <Tab title="npm">
        ```bash theme={null}
        npm install -g opencode-ai
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Open the web UI">
    ```bash theme={null}
    opencode web
    ```
  </Step>

  <Step title="Add a custom provider">
    Go to **Settings > Providers** and click to add a new custom provider.

    <Frame>
      <img src="https://mintcdn.com/sambanova-systems/Uu2D5xFHXnhf5KrO/images/docs/integrations/opencode/opencode1.png?fit=max&auto=format&n=Uu2D5xFHXnhf5KrO&q=85&s=1b5997725e1d6a78068ad6a09c94fd13" alt="OpenCode settings showing the Providers section" style={{ maxWidth:"100%" }} width="1948" height="1237" data-path="images/docs/integrations/opencode/opencode1.png" />
    </Frame>
  </Step>

  <Step title="Configure SambaNova credentials">
    Enter the following details:

    * **URL**: `https://api.sambanova.ai/v1`
    * **API Key**: Your SambaCloud API key
    * **Model Name**: For example, `MiniMax-M2.7`

    Get your API key from the [SambaCloud portal](https://cloud.sambanova.ai/apis).

    <Frame>
      <img src="https://mintcdn.com/sambanova-systems/Uu2D5xFHXnhf5KrO/images/docs/integrations/opencode/opencode2.png?fit=max&auto=format&n=Uu2D5xFHXnhf5KrO&q=85&s=c7d737d16e583b013ec50b9e1732a032" alt="OpenCode provider configuration form with SambaNova credentials" style={{ maxWidth:"100%" }} width="1416" height="1167" data-path="images/docs/integrations/opencode/opencode2.png" />
    </Frame>
  </Step>

  <Step title="Start using SambaNova models">
    You can now use SambaNova models in your OpenCode workflows.

    <Frame>
      <img src="https://mintcdn.com/sambanova-systems/Uu2D5xFHXnhf5KrO/images/docs/integrations/opencode/opencode3.png?fit=max&auto=format&n=Uu2D5xFHXnhf5KrO&q=85&s=3f1a406827b6410d9adbc189aa77f231" alt="OpenCode chat interface using a SambaNova model" style={{ maxWidth:"100%" }} width="3563" height="1732" data-path="images/docs/integrations/opencode/opencode3.png" />
    </Frame>
  </Step>
</Steps>

<Note>
  After finishing the configuration, if you want to add more models, modify the `models` key in the file `~/.config/opencode/opencode.json`:

  ```json theme={null}
    "models": {
      "MiniMax-M2.7": {
        "name": "MiniMax-M2.7"
      },
      "gemma-4-31B-it": {
        "name": "gemma-4-31B-it"
      }
    }
  ```
</Note>

## Additional resources

* [OpenCode documentation](https://opencode.ai/docs/)

## How to use sub-agents in OpenCode with SambaNova

Out of the box, OpenCode ships with two **primary agents** — `plan` (read-only / ask-to-edit) and `build` (full tools) — and you can point each one at a different model. That makes opencode a natural fit for SambaNova's **planner / executor** pattern: a frontier reasoning model writes the plan, and [MiniMax-M2.7](https://sambanova.ai/blog/build-faster-coding-agents-with-sambanovas-responses-api) (fast and cheap) does the 50–200 turns of file edits and test runs.

### Prerequisites

* **opencode** installed: `curl -fsSL https://opencode.ai/install | bash`
* **SambaNova API key** exported as `SAMBANOVA_API_KEY`.
* **Anthropic API key** exported as `ANTHROPIC_API_KEY` — used by the frontier planner in Demos 2 & 3. opencode auto-discovers it from the env when set, so no provider block is needed in `opencode.json`.

Sanity check:

```bash theme={null}
  # Required for all demos:
  opencode --version && [ -n "$SAMBANOVA_API_KEY" ] && echo OK

  # Demos 2 & 3 also need a frontier planner key:
  [ -n "$ANTHROPIC_API_KEY" ] && echo "planner key OK"
```

### Wire up SambaNova

opencode reads `opencode.json` from the project root (or `~/.config/opencode/opencode.json` globally). Create one demo workspace and drop a config in it:

```bash theme={null}
mkdir -p ~/sambanova-opencode-demo && cd ~/sambanova-opencode-demo
```

**`opencode.json`** — registers SambaNova as a provider and assigns models to the two built-in agents:

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "sambanova": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "SambaNova",
      "options": {
        "baseURL": "https://api.sambanova.ai/v1",
        "apiKey": "{env:SAMBANOVA_API_KEY}"
      },
      "models": {
        "MiniMax-M2.7":   { "name": "MiniMax M2.7" },
        "gemma-4-31B-it":   { "name": "gemma-4-31B-it" }
      }
    }
  },
  "agent": {
    "build": { "model": "sambanova/MiniMax-M2.7" },
    "plan":  { "model": "anthropic/claude-sonnet-4-6" }
  }
}
```

> The `@ai-sdk/openai-compatible` package talks to SambaNova's OpenAI-compatible `/v1/chat/completions` endpoint. `{env:…}` substitution keeps the key out of the file. The `anthropic/claude-sonnet-4-6` planner is auto-discovered from `ANTHROPIC_API_KEY` — no `provider.anthropic` block needed.
>
> Want a SambaNova-only setup with no frontier dependency? Swap the planner to `"sambanova/gemma-4-31B-it"`.

Launch opencode in this folder:

```bash theme={null}
opencode
```

Hit **Tab** to cycle between `build` and `plan` — you should see the model name change in the status bar.

***

### Demo 1 — SambaNova end-to-end

A pet-friendly "hello world" landing page, built and verified entirely by `MiniMax-M2.7`.

Launch opencode in `~/sambanova-opencode-demo` and stay in **`build`** agent (MiniMax-M2.7). Prompt:

> Create a minimalist, pet-friendly "hello world" landing page in this directory. One `index.html`, one `style.css`, no JS frameworks. Soft pastel palette, a friendly paw-print emoji, a short tagline ("Hello, friend"), and a single call-to-action button. Keep it under 80 lines of HTML+CSS combined. Open the file when done so I can preview it.

Verify:

```bash theme={null}
open index.html        # or: python3 -m http.server 8000
```

That's the **SN-only** baseline. Fast, cheap, no frontier model in the loop.

***

### Demo 2 — Frontier plans, SambaNova executes

The architect/builder split. **Plan** agent (Claude Sonnet 4.6, per the `opencode.json` above) writes a precise `PLAN.md`; **build** agent (MiniMax-M2.7) executes it. The plan is the artifact that crosses the boundary — reproducible, swappable, reviewable.

**Step 1 — switch to `plan` agent (Tab)** and prompt:

> Read `index.html` and `style.css` in this directory. Elaborate a plan describing how to extend this landing page into a "pet adoption finder" demo:
>
> * A gallery of 6 placeholder pet cards (name, species, one-line bio) in CSS grid
> * A search input that filters cards by name (vanilla JS, no frameworks)
> * A dark-mode toggle that persists in `localStorage`
>
> Include exact file layout, the JS event handlers needed, and a verification checklist a human can run in the browser. Don't modify any code yet.

Review the plan. Edit it if needed — that's the point of the artifact.

**Step 2 — switch to `build` agent (Tab)** and prompt: Since, Build and Plan share the same session, they also share the same historical context, this is why by just pressing Tab transitioning from Plan to Build agent, the builder is capable to complete the following prompt:

> Write the plan into `PLAN.md` and proceed with the execution of every step. After each step, list which acceptance criteria from the plan are now satisfied. Open `index.html` at the end so I can verify in the browser.

**Step 3 — verify:**

```bash theme={null}
open index.html
```

You should see the gallery, working search, and a working dark-mode toggle.

Since the plan doesn't allow writing files, then the executor writes the plan into `PLAN.md` and executes it. Tweak `PLAN.md` and re-run `build`, or swap the executor model without rewriting the plan.

***

### Demo 3 — MCP-fed planning with live library docs

Demo 2, plus an MCP server. The planner uses [**Context7**](https://github.com/upstash/context7) to fetch *current* docs for a library, bakes them into `PLAN.md`, and MiniMax executes. Solves the "model trained on stale docs" problem without writing custom retrieval.

#### Install Context7

Free API key from [context7.com/dashboard](https://context7.com/dashboard), then:

```bash theme={null}
export CONTEXT7_API_KEY=ctx7sk-…
```

Add a top-level `mcp` key to your existing `opencode.json` (alongside `provider` and `agent`):

```json theme={null}
{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" }
    }
  }
}
```

Restart opencode and confirm with `/mcps` — `context7` should show `resolve-library-id` and `query-docs`.

> No API key works too (free tier, lower rate limits). Drop the `headers` block.

#### The task

Stamp each pet card from Demo 2 with a human-readable "Added *X* days ago" label, computed at page load with [date-fns](https://date-fns.org/) (`formatDistanceToNow`). date-fns is a good Context7 target: its v2→v3 rewrite changed how it's imported (tree-shakeable named exports, a new UMD `cdn.min.js` build) and v4 added time-zone support — so models routinely emit stale default-import patterns that don't run.

#### Step 1 — `plan` agent fetches current docs and writes the plan

Switch to **`plan`**:

> Use the `context7` MCP server to look up current docs for the `date-fns` library — specifically `formatDistanceToNow` with the `addSuffix` option, and how to load date-fns in a plain browser page via its UMD CDN build (the `dateFns` global) vs ESM named imports. Elaborate a plan for "Phase 2: relative date labels" describing how to give each pet card a fixed `data-added` ISO date and render an "Added X days ago" label from it on load. Use the up-to-date API from Context7 — not what you remember. Quote the exact `<script>` CDN tag, the global function call, and `addSuffix` usage verbatim from the docs, and include a verification step.

The planner calls `resolve-library-id` → `query-docs`, gets today's API, and writes a plan grounded in current docs.

#### Step 2 — `build` agent executes

Switch to **`build`**:

> Update PLAN.md to include the "Phase 2" part and execute it. After loading, open `index.html` and confirm each card shows an "Added X days ago" label.

The executor doesn't need MCP — `PLAN.md` already contains the resolved API. MCP access stays on the (more expensive) planner side, where it pays off.

#### Step 3 — verify

```bash theme={null}
open index.html
```

Each of the 6 cards should show an "Added *X* days ago" label (e.g. "Added 3 days ago").

#### Why this matters

**MCP-fed planning** keeps the frontier planner well-informed and the SambaNova executor cheap and tool-light. The boundary is `PLAN.md`.

***

### Tips

* **Tab cycles primary agents.** Watch the status bar to confirm which model is active.
* **`@plan` / `@build`** in your prompt lets you hand off without switching the active agent.
* **Tell the executor to verify** ("open `index.html` and confirm…") or it will edit files and stop.
* **Per-project `opencode.json` overrides global config** — handy for pinning a SambaNova model on one repo without touching others.

### Common gotchas

**"Model not found."** opencode model ids are `provider/model` — always `sambanova/MiniMax-M2.7`, never the bare id. The bare id only appears as a key inside `provider.sambanova.models`.

**API key not picked up.** `{env:SAMBANOVA_API_KEY}` is resolved at opencode startup. Export the var in your shell, then launch opencode from that shell — not from a stale tmux pane.

**Frontier model can't be found.** opencode auto-discovers Anthropic/OpenAI models when the env key is set; if you use a non-default model id, register it under `provider.anthropic.models` the same way you registered SambaNova's.

### Composing with MCP servers

opencode's two agents sit on opposite sides of a useful boundary:

| Agent                                                       | Best for                            | Tools                        |
| ----------------------------------------------------------- | ----------------------------------- | ---------------------------- |
| **plan** (Claude Sonnet 4.6, or `sambanova/gemma-4-31B-it`) | reading, reasoning, calling MCP     | full read + MCP, edits gated |
| **build** (MiniMax-M2.7)                                    | the 50–200 file edits and test runs | full edit + shell            |

Three patterns fall out:

**1. MCP-fed planning.** Planner pulls external context (docs, Jira, GitHub), bakes it into `PLAN.md`, hands to build.

**2. MCP-driven handoff.** After `build` finishes, switch back to `plan` and use a GitHub or Slack MCP server to open a PR / post a summary — the executor never needs those credentials.

**3. Shell-CLI tools inside `build`.** The build agent has `bash` access. Any CLI on PATH (`gh`, `git`, `aws`, …) is fair game — tell it in the prompt.

### References

* opencode docs — [opencode.ai/docs](https://opencode.ai/docs/)
* opencode providers — [opencode.ai/docs/providers](https://opencode.ai/docs/providers/)
* opencode agents — [opencode.ai/docs/agents](https://opencode.ai/docs/agents/)
* SambaNova Cloud — [cloud.sambanova.ai](https://cloud.sambanova.ai/)
* SambaNova Responses API blog — [build faster coding agents](https://sambanova.ai/blog/build-faster-coding-agents-with-sambanovas-responses-api)
* Context7 MCP — [github.com/upstash/context7](https://github.com/upstash/context7)
* Model Context Protocol — [modelcontextprotocol.io](https://modelcontextprotocol.io/)