> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.asi1.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.asi1.ai/_mcp/server. # Set Up ASI:One in OpenCode > Add asi1-ultra and the other ASI:One models to OpenCode as a custom OpenAI-compatible provider. ## Overview ASI:One is [OpenAI-compatible](/documentation/build-with-asi-one/openai-compatibility), so [OpenCode](https://opencode.ai) can use it as a custom provider through the OpenAI-compatible runtime package. You declare the provider, its endpoint, and its models in `opencode.json`, then store your API key with OpenCode's credential commands. Custom providers like ASI:One are not loaded from ASI:One's [`GET /v1/models`](/documentation/models). OpenCode reads the model list and context limits from your config. Built-in providers on [Models.dev](https://models.dev) can pull metadata from that catalog; your `asi` block is the source of truth for ASI:One. ## Prerequisites * OpenCode v2 installed and on your `PATH`. * An ASI:One API key. Create one at [asi1.ai/developer](https://asi1.ai/developer). Keys start with `sk_`. * An ASI:One plan that includes `asi1-ultra`. The same key also works for `asi1` and `asi1-mini`. ## Add the provider Create or edit `opencode.json` or `opencode.jsonc` at the root of your project. OpenCode v2 expects a `providers` object. Each provider needs `settings.baseURL`. Without it, sessions fail with an error about the route missing an endpoint. ```json { "$schema": "https://opencode.ai/config.json", "model": "asi/asi1-ultra", "providers": { "asi": { "name": "ASI:One", "package": "aisdk:@ai-sdk/openai-compatible", "settings": { "baseURL": "https://api.asi1.ai/v1" }, "models": { "asi1": { "name": "ASI1", "limit": { "context": 300000, "output": 40000 }, "capabilities": { "tools": true, "input": ["text", "image"], "output": ["text"] } }, "asi1-ultra": { "name": "ASI1 Ultra", "limit": { "context": 800000, "output": 40000 }, "capabilities": { "tools": true, "input": ["text", "image"], "output": ["text"] } }, "asi1-mini": { "name": "ASI1 Mini", "limit": { "context": 160000, "output": 40000 }, "capabilities": { "tools": true, "input": ["text", "image"], "output": ["text"] } } } } } } ``` To make ASI:One available in every project, put the same `providers.asi` block in `~/.config/opencode/opencode.json` instead. Older configs that used `provider`, `npm`, and `options` still load on OpenCode v2 through migration. New setups should use `providers`, `package`, and `settings` as above. OpenCode uses each model's `limit` to decide when to compact the conversation. `context` is the [working window](/documentation/models) ASI:One publishes for tools like OpenCode (not the raw API maximum). `output` is how much room OpenCode reserves for the assistant reply. Both fields are required whenever a model has a `limit` block. If you omit `limit`, OpenCode falls back to generic defaults that are too small for `asi1-ultra`, so always set the limits above. The sample uses 40,000 for `output` as a safe default; raise it if replies feel cut off before compaction should kick in. ### Optional: reasoning depth `asi1` and `asi1-ultra` support configurable [reasoning](/documentation/build-with-asi-one/reasoning) depth. To expose effort levels in OpenCode, replace the existing `asi1-ultra` entry under `providers.asi.models` with the object below (same fields work on `asi1`; not needed for a first successful run): ```json { "asi1-ultra": { "name": "ASI1 Ultra", "compatibility": { "reasoningField": "reasoning" }, "settings": { "reasoningEffort": "high" }, "variants": [ { "id": "low", "settings": { "reasoningEffort": "low" } }, { "id": "medium", "settings": { "reasoningEffort": "medium" } }, { "id": "high", "settings": { "reasoningEffort": "high" } } ], "limit": { "context": 800000, "output": 40000 }, "capabilities": { "tools": true, "input": ["text", "image"], "output": ["text"], "reasoning": { "supported": true, "effort": ["low", "medium", "high"] } } } } ``` Pick a variant when you start a session, for example `opencode -m asi/asi1-ultra#high`. ## Store the API key Add the provider block to your config file (`opencode.json` or `opencode.jsonc`) first so OpenCode knows about the `asi` integration. Then connect your key: ```bash opencode auth login asi --method key ``` OpenCode prompts for the key without echoing it. The key is stored in OpenCode's local credential store, not in your project. > **Warning** > > Keep the key out of project config when that file lives in a git repository. > Use `opencode auth login` instead of pasting the key into config. To see saved integrations: ```bash opencode auth list ``` ## Verify List models that come from your config (look for the `asi/` prefix): ```bash opencode models | grep '^asi/' ``` You should see: ```text asi/asi1 asi/asi1-mini asi/asi1-ultra ``` To confirm OpenCode merged the provider block and endpoint: ```bash opencode debug config ``` Then send a request to each model you plan to use: ```bash opencode run -m asi/asi1-mini "Reply with exactly: OK" opencode run -m asi/asi1-ultra "Reply with exactly: OK" ``` Each should reply with `OK`. ## Run it Because the config sets `"model": "asi/asi1-ultra"`, plain `opencode` starts on `asi1-ultra`. To pick a model for one session: ```bash opencode -m asi/asi1-mini ``` ## Troubleshooting | Symptom | Cause and fix | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Route.model(openai-compatible-chat) requires an endpoint baseURL` | The `asi` provider is missing `settings.baseURL`, or OpenCode is not reading the file you edited. Set `"baseURL": "https://api.asi1.ai/v1"` under `providers.asi.settings`, use `opencode debug paths config` to see which config file loads, and run `opencode debug config` to confirm the merged provider. | | `failed to authenticate` or `401` | No key is stored for `asi`, or the key is wrong or revoked. Run `opencode auth login asi --method key` again. Create a new key at [asi1.ai/developer](https://asi1.ai/developer) if needed. | | No `asi/` models in `opencode models` | The provider block is missing, JSON is invalid, or the config path is wrong. Put `opencode.json` at the project root or in `~/.config/opencode/`, and ensure every `limit` block has both `context` and `output`. | | `404` model not found | The model name after `asi/` is misspelled. Use `asi1`, `asi1-ultra` or `asi1-mini`. | | Context compacts too early | `limit.context` is missing or too low for the model you use. Match the values in the sample config above. | ## Next steps 1. **[OpenWork](/documentation/everyday-work/openwork)**: use the same models in OpenWork's task UI 2. **[Codex](/documentation/coding/codex)**: the same models in the Codex CLI 3. **[Cursor](/documentation/coding/cursor)**: the same models in the Cursor editor 4. **[Zed](/documentation/coding/zed)**: the same models in the Zed editor 5. **[ASI:One Models](/documentation/models)**: choosing between `asi1`, `asi1-ultra` and `asi1-mini` 6. **[Chat Completions API](/documentation/build-with-asi-one/chat-completions)**: the endpoint OpenCode talks to