---
name: arka-provider
description: Manage the custom Arka-AI (arka-ai.ru) LLM provider in opencode config. Use when the user needs to add, refresh, or fix the arka-ai.ru provider, sync its model catalog, change the Arka-AI default model, or when arka models are missing from /models.
---

# Arka-AI provider

arka-ai.ru is **not** in models.dev, so opencode ships no built-in config for it.
It is wired up locally with a plugin + a static `provider` block in
`~/.config/opencode/opencode.json`.

## How it works

- Plugin: `~/.config/opencode/plugins/arka-ai.ts`
  - On startup it loads the published chat catalog
    `https://git.arka-ai.ru/arka/public/raw/branch/main/opencode/catalog.json`
    (no API key; refreshed daily at 05:00 Europe/Moscow).
  - If that fetch fails, it falls back to `https://api.arka-ai.ru/v1/models`
    and filters out non-chat models (TTS/ASR/image/video/OCR/embedding/reranker/…)
    via a heuristic regex so the `/models` picker stays clean.
  - Caches the result at `~/.cache/opencode/arka-ai-models.json` (TTL 24h).
  - Injects the provider into config via the `config` hook, layered over the
    static block in `opencode.json`.
- Static block (`opencode.json` → `provider["Arka-AI"]`) holds
  `name`, `api`, `env`, and a small fallback `models` map that is used when the
  catalog is unreachable.
- Inference uses `ARKA_API_KEY` (env) or `~/.config/opencode/.arka-api-key`
  (so OpenCode Desktop / Windows GUI works without a login shell).

## Refresh the model list

Catalog ~216 raw models / ~116 chat; the public snapshot updates at 05:00
Europe/Moscow. Changes land in opencode only after cache expiry + restart
(config is not hot-reloaded).

1. `rm -f ~/.cache/opencode/arka-ai-models.json`
2. Restart opencode (or run `opencode` again) — the plugin re-fetches on the
   next cold start.

Optionally inspect the live API (no key required for listing):

```bash
curl -sS https://api.arka-ai.ru/v1/models | python3 -m json.tool
curl -sS https://git.arka-ai.ru/arka/public/raw/branch/main/opencode/catalog.json | python3 -m json.tool
```

## Change default model

Edit `opencode.json` → `"model": "Arka-AI/<model-id>"`. Use the IDs exactly as
returned by the catalog (e.g. `Arka-AI/DeepSeek-V4-Pro`,
`Arka-AI/qwen3.8-max`, `Arka-AI/kimi-k3`).

## Adjust filtering

Edit `NON_CHAT` (regex) or `FORCED_MODELS` in the plugin file **and** the same
lists in `scripts/sync-catalog.py` in `arka/public`, then re-run the installer
and restart. `FORCED_MODELS` keeps must-have chat models even if the heuristic
would drop them.