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

# OpenCode

> Use NoMask with OpenCode configuration files.

Connect OpenCode to NoMask for terminal chat and code editing.

## Before you start

* Create a key on the [API Keys page](https://nomask.ai/api/keys) and add funds to your API balance.
* Choose a text model with **Function calling** and streaming on the [Models page](https://nomask.ai/models). Copy its exact model ID.
* Use the connection values below. Replace key placeholders locally; keep secrets out of project files and source control.

| Setting | Value |
| - | - |
| **API base URL** | `https://api.nomask.ai/v1` |
| **Model ID** | `your-model-id` |
| **API key** | Your NoMask API key |

> [!NOTE]
>
> Replace `your-model-id` throughout the examples with the exact ID of a text model that supports function calling and streaming. Check the [Models page](https://nomask.ai/models) for current availability and limits.

Examples use your selected model. If you change it, also update context, output and image settings to match that model. These guides cover text models; Image Studio models use separate image endpoints.

## Install and configure

### 1. Choose your OpenCode version

OpenCode 1 and 2 use different configuration formats and share the `opencode` command. Use the install and configuration for one version.

> [tab] OpenCode 2 · macOS / Linux / WSL
>
> ```bash theme={"system"}
> npm install -g @opencode/cli
> opencode --version
> ```

> [tab] OpenCode 1
>
> ```bash theme={"system"}
> npm install -g opencode-ai
> opencode --version
> ```

For native Windows with OpenCode 2, download the Windows CLI binary from the [official install page](https://opencode.ai/v2/docs/#cli), extract it and add its folder to your PATH. Windows package-manager installation is not supported for version 2.

### 2. Set your API key

> [tab] macOS / Linux / WSL
>
> ```bash theme={"system"}
> export NOMASK_API_KEY="YOUR_NOMASK_API_KEY"
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={"system"}
> $env:NOMASK_API_KEY = "YOUR_NOMASK_API_KEY"
> ```

### 3. Save the matching configuration

Create `opencode.json` in your project directory. Merge these settings if you already have one.

> [tab] OpenCode 2
>
> ```json theme={"system"}
> {
>   "$schema": "https://opencode.ai/config.json",
>   "model": "nomask/your-model-id",
>   "providers": {
>     "nomask": {
>       "name": "NoMask",
>       "env": [
>         "NOMASK_API_KEY"
>       ],
>       "package": "@opencode/ai/providers/openai-compatible",
>       "settings": {
>         "baseURL": "https://api.nomask.ai/v1"
>       },
>       "models": {
>         "your-model-id": {
>           "name": "Your NoMask model",
>           "capabilities": {
>             "tools": true,
>             "input": [
>               "text"
>             ],
>             "output": [
>               "text"
>             ]
>           }
>         }
>       }
>     }
>   }
> }
> ```

> [tab] OpenCode 1
>
> ```json theme={"system"}
> {
>   "$schema": "https://opencode.ai/config.json",
>   "model": "nomask/your-model-id",
>   "small_model": "nomask/your-model-id",
>   "provider": {
>     "nomask": {
>       "name": "NoMask",
>       "npm": "@ai-sdk/openai-compatible",
>       "options": {
>         "baseURL": "https://api.nomask.ai/v1",
>         "apiKey": "{env:NOMASK_API_KEY}"
>       },
>       "models": {
>         "your-model-id": {
>           "name": "Your NoMask model"
>         }
>       }
>     }
>   }
> }
> ```

The compatible package uses Chat Completions. `nomask/` is OpenCode’s connection prefix; the remaining value is the exact NoMask model ID, including any slashes.

> [!NOTE]
>
> These examples enable text input and tools. Add images only when the selected model supports vision. If you change the model, update its context and output limits from its model card.

## Launch and test

For OpenCode 2, `--standalone` starts a fresh local session with the environment from this terminal. For version 1, launch normally.

> [tab] OpenCode 2
>
> ```bash theme={"system"}
> cd path/to/your-project
> opencode --standalone
> ```

> [tab] OpenCode 1
>
> ```bash theme={"system"}
> cd path/to/your-project
> opencode
> ```

* Run `/models` and select `nomask/your-model-id` under **NoMask**.
* Ask: `Reply with exactly NOMASK_OK. Do not edit files.`
* Ask it to create `nomask-test.txt` containing `NOMASK_OK`. Review the file changes and any requested permissions.

If the model is unavailable, confirm the configuration matches your installed major version and the terminal has `NOMASK_API_KEY`. A model selected in an existing session can override the configured default; select it again with `/models`.

## Troubleshooting

* **401:** check that your key is active and available to the process running the tool. Restart the tool after changing environment variables.
* **402:** add funds to your API balance or reduce the requested output.
* **404:** check the exact model ID and base URL. Direct connections use Chat Completions, not Responses or Anthropic Messages.
* **429:** wait for `Retry-After`. API keys share account limits; creating another key does not reset usage. Check the key's monthly spending cap too.
* **Context or tool errors:** start a shorter task, lower the output limit and confirm the model supports function calling. A plain text reply alone does not confirm file-editing tools work.

Check [API Overview](https://nomask.ai/api/overview) for usage and recent errors. Include the request ID when contacting support; never send your key. See [Errors](https://docs.nomask.ai/errors.md) and [Rate Limits](https://docs.nomask.ai/rate-limits.md).

## Official references

Setup checked against the documentation below. Tool versions may change their settings or configuration format.

* [OpenCode 2 installation](https://opencode.ai/v2/docs/)
* [OpenCode 2 custom connections](https://opencode.ai/v2/docs/providers)
* [OpenCode 2 model capabilities and selection](https://opencode.ai/v2/docs/models)
* [OpenCode 2 configuration and environment variables](https://opencode.ai/v2/docs/config)
* [OpenCode 1 installation](https://opencode.ai/docs/)
* [OpenCode 1 compatible configuration](https://opencode.ai/docs/providers/#custom-provider)
* [OpenCode 1 model and helper settings](https://opencode.ai/docs/config/#models)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.