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

# Use A2Agent with OpenCode CLI

> OpenCode CLI defines custom providers in opencode.json. Add an A2Agent entry with your base URL and key to make every account model selectable in the CLI.

This guide covers **OpenCode CLI / TUI only**. It includes OpenCode installation, creating or editing `opencode.json`, adding the provider, configuring the API key, selecting a model, and troubleshooting common connection errors. It does not cover other clients or desktop applications.

## Prerequisites

OpenCode CLI is installed. Download it from [opencode.ai](https://opencode.ai/). On Linux/WSL, use the official installer:

```bash theme={null}
curl -fsSL https://opencode.ai/install | bash
```

Or install with npm:

```bash theme={null}
npm install -g opencode-ai
```

* You have an A2Agent API key. Register at [a2agent.me/register](https://a2agent.me/register), then create a key in the [A2Agent dashboard](https://a2agent.me/login).
* A model ID listed on the [A2Agent Models page](https://a2agent.me/models)

## A2Agent connection values

| Setting | Value |
| - | - |
| Provider ID | `a2agent` |
| SDK package | `@ai-sdk/openai-compatible` |
| Base URL | `https://api.a2agent.me/v1` |
| API protocol | OpenAI Chat Completions |
| API key | Your A2Agent API key |
| Model | An exact model ID currently available in A2Agent |

For an OpenAI-compatible `/v1/chat/completions` endpoint, OpenCode's provider documentation uses `@ai-sdk/openai-compatible` with the provider's `options.baseURL` setting.

## Setup

<Steps>
  <Step title="Go to your project directory">
    In a terminal, enter the project where you want to use OpenCode:

    ```bash theme={null}
    cd /path/to/your/project
    ```
  </Step>

  <Step title="Open or create `opencode.json`">
    From the project root, run:

    ```bash theme={null}
    nano opencode.json
    ```

    If the file does not exist, `nano` creates it. If it exists, `nano` opens it for editing.
  </Step>

  <Step title="Paste the A2Agent provider configuration">
    If this is a new `opencode.json`, paste the following:

    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "a2agent": {
          "npm": "@ai-sdk/openai-compatible",
          "name": "A2Agent",
          "options": {
            "baseURL": "https://api.a2agent.me/v1",
            "apiKey": "YOUR_A2AGENT_API_KEY"
          },
          "models": {
            "YOUR_MODEL_ID_1": {
              "name": "A2Agent Model 1"
            },
            "YOUR_MODEL_ID_2": {
              "name": "A2Agent Model 2"
            },
            "YOUR_MODEL_ID_3": {
              "name": "A2Agent Model 3"
            }
          }
        }
      }
    }
    ```

    Replace:

    * `YOUR_A2AGENT_API_KEY` with your real A2Agent API key.
    * `YOUR_MODEL_ID_1`, `YOUR_MODEL_ID_2`, and `YOUR_MODEL_ID_3` with exact model IDs listed on the [A2Agent Models page](https://a2agent.me/models)
    * `A2Agent Model 1` and the other display names if desired.

    Then save `opencode.json`
  </Step>

  <Step title="Start OpenCode CLI">
    Still in the project directory, run:

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

    Inside the OpenCode session, enter:

    ```text theme={null}
    /models
    ```

    Select a model under `a2agent`.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    Check that:

    * The key came from the A2Agent dashboard.
    * The key was pasted completely, without leading/trailing spaces or line breaks.
    * You did not enter a login password, an OpenCode key, or a key from another provider.
    * If you use an environment variable, `A2AGENT_API_KEY` exactly matches `{env:A2AGENT_API_KEY}`.
  </Accordion>

  <Accordion title="The provider does not appear in /models">
    Check:

    ```bash theme={null}
    test -f opencode.json && echo "Configuration file found"
    python -m json.tool opencode.json >/dev/null && echo "JSON is valid"
    ```

    Confirm that:

    * The top-level field is `provider`, not `providers`.
    * The provider ID is `a2agent`.
    * `npm` is `@ai-sdk/openai-compatible`.
    * `options.baseURL` is `https://api.a2agent.me/v1`.
    * `models` contains at least one model ID.
    * You start OpenCode from the directory that contains this `opencode.json`.
  </Accordion>

  <Accordion title="`404` or endpoint path errors">
    Use this standard Base URL:

    ```text theme={null}
    https://api.a2agent.me/v1
    ```

    For an OpenAI Chat Completions-compatible endpoint, use:

    ```json theme={null}
    "npm": "@ai-sdk/openai-compatible"
    ```

    Do not use a Markdown-formatted URL or duplicate `/v1` in the address.
  </Accordion>

  <Accordion title="Model not found">
    Copy the current model ID from [A2Agent Models](https://a2agent.me/models), replace the corresponding key under `models`, restart OpenCode, and run:

    ```text theme={null}
    /models
    ```

    Model IDs are examples only. Model availability, limits, and pricing can change; when adding or replacing a model, use the exact ID currently shown in your A2Agent account.
  </Accordion>
</AccordionGroup>

## Official references

* [OpenCode CLI documentation](https://opencode.ai/docs/)
* [OpenCode providers](https://opencode.ai/docs/providers/)
* [OpenCode configuration](https://opencode.ai/docs/config/)
* [A2Agent Quickstart](https://docs.a2agent.me/quickstart)
* [A2Agent Models](https://a2agent.me/models)