# OpenCode

Source: https://cicora.ai/en/docs/opencode

## Choose installer or manual setup

In OpenCode, a **provider** is a named API connection with its models and connection settings. The installer configures an existing OpenCode installation; it does not install OpenCode. It authenticates `GET /v1/models`, adds or refreshes the `cicora` provider, and carries the returned names, limits, capabilities, modalities, and public prices into the local configuration.

Use the installer for catalog-driven setup. Use the manual provider only when you need to review and merge every field yourself.

## Run the installer




macOS and Linux



Windows PowerShell




```bash
export CICORA_API_KEY="sk_..."

curl -fsSL https://app.cicora.ai/install/opencode.sh | \
  CICORA_API_KEY="$CICORA_API_KEY" sh
```



```powershell
$env:CICORA_API_KEY = "sk_..."
irm https://app.cicora.ai/install/opencode.ps1 | iex
```



The installer stores the key separately in `~/.config/opencode/cicora-api-key` and adds a `{file:~/.config/opencode/cicora-api-key}` reference to the config. Keep the key file out of repositories and shared backups.

Set `OPENCODE_CONFIG` before the command to target a non-default file. Otherwise the installer checks `~/.config/opencode/opencode.json`, then `opencode.jsonc`, and creates `opencode.json` when neither exists.

Both installers validate the generated config and back up an existing file before replacing it. The installer does not select a default model; choose the model you want through `/models` after installation.

## Configure a provider manually

First export the key and use `GET /v1/models` to choose an available exact ID. Then replace every `model-id-from-GET-v1-models` string below with that ID, and paste the current key value where the example names `CICORA_API_KEY`.

```bash
export CICORA_API_KEY="sk_..."
```

**Manual setup stores the key unencrypted**


The `apiKey` value is written directly to the local OpenCode configuration. Protect the file because it contains the key, keep it out of repositories and shared backups, and prefer a dedicated key with an appropriate spend limit.


```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "cicora/model-id-from-GET-v1-models",
  "provider": {
    "cicora": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "cicora.ai",
      "options": {
        "baseURL": "https://api.cicora.ai/v1",
        "apiKey": "paste-value-from-CICORA_API_KEY"
      },
      "models": {
        "model-id-from-GET-v1-models": {
          "name": "model-id-from-GET-v1-models"
        }
      }
    }
  }
}
```

Save the example as `~/.config/opencode/opencode.json`, then restrict the directory and credential file to the current user. If `OPENCODE_CONFIG` points elsewhere, apply equivalent owner-only permissions to that file:

```bash
chmod 700 ~/.config/opencode
chmod 600 ~/.config/opencode/opencode.json
```

The manual example defines only the connection. The installer is preferable when you want OpenCode to receive current context/output limits, reasoning, tools, image input, and prices from catalog metadata.

## Verify the current configuration

List the models OpenCode loaded for the provider:

```bash
opencode models cicora
```

Select one through `/models`, or run a current catalog ID directly:

```bash
export CICORA_MODEL="model-id-from-GET-v1-models"
opencode run --model "cicora/$CICORA_MODEL" "Reply with ok"
```

## Recover or refresh

On macOS/Linux, the installer prints the timestamped backup path. If the merged file no longer loads, stop OpenCode, preserve the failed file for comparison, restore the printed backup, and rerun only after checking `OPENCODE_CONFIG`.

If an installer cannot merge safely or preserve JSONC comments, it leaves the original file unchanged and writes a standalone `cicora-opencode-provider.jsonc` snippet beside it for review. PowerShell also prints the backup path after successfully updating an existing file. Rerunning the installer refreshes the live catalog; it is not necessary to copy new model IDs from this page.

A **public error code** is the client-facing `error.code` from the API response. Record it with the HTTP status, exact model ID, time, OpenCode version, config path, and masked key prefix. See [API authentication](/en/docs/authentication) for safe key handling and [Chat Completions](/en/docs/chat-completions) for the request format.

## Troubleshooting


**OpenCode does not show the cicora provider**


Run `opencode models cicora`, then confirm the active file is `~/.config/opencode/opencode.json` or set `OPENCODE_CONFIG` explicitly. Restart OpenCode after changing the file.


**The installer cannot load models**


Verify the same key with `GET /v1/models`, confirm the active workspace has an available model, and check that `CICORA_API_KEY` is visible to the installer process without printing it.


**The configuration stopped loading after installation**


Restore the macOS/Linux backup printed by the installer or your manual Windows copy. If a standalone provider snippet was written, review and merge it instead of replacing the whole configuration.


**A configured model is missing or stale**


Rerun the installer to refresh the provider from the current catalog, or replace all manual occurrences with one exact available ID. Do not retain copied limits or capabilities from an older model record.


**The config or backup exposed the API key**


Revoke the key in the cabinet, create a replacement, and update protected configuration copies. Removing the file alone does not revoke the exposed key.

## FAQ

### What is cicora.ai?

cicora.ai is a multi-model AI workspace and compatible API for chat, text, images, video, coding tools, and teams. Start with the [overview](/en.md), [documentation](/en/docs.md), or [model catalog](/en/models.md).

### How is usage billed?

Confirmed usage is charged in USD from the active workspace's prepaid balance. Use the live catalog for current model prices and the [usage guide](/en/docs/usage-costs.md) for settlement details.

### Which protocols and integrations are available?

Documentation covers OpenAI-compatible Chat Completions and Responses, Anthropic Messages, image interfaces, Claude Code, OpenCode, and Codex CLI. Compatibility does not imply support for every upstream parameter.

### Which sources are authoritative and current?

For model IDs, availability, capabilities, limits, and prices, use the [live catalog](/en/models.md). For API behavior, use the matching [documentation page](/en/docs.md). Never include API keys, private workspace data, or preview URLs in public documents.