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

# OpenCode

> Point OpenCode at FlexInference with config only.

OpenCode reads a provider entry out of a JSON file, with no source change and no fork.

OpenCode can set `start_within` in config, so an agent key is optional here. The key is still the simpler path, because it changes without a restart. See [agent keys](/agent-keys).

## Set this up with an agent

Open the block below and copy it into any coding agent. The prompt never asks for your API key: the agent configures everything else, then prints the one export line for you to run yourself.

<Accordion title="Copy agent setup prompt">
  ```text theme={null}
  Configure OpenCode to send its requests to FlexInference. This is config only: no source change, no fork, no patch.

  You will never see or handle my API key. The provider entry stores only the `{env:FLEXINFERENCE_API_KEY}` template, and I export the value myself. Do not ask me for the key, and do not read it from my environment.

  Ask me whether this should apply to every project or one project, then write the provider entry to the matching file. Global is `~/.config/opencode/opencode.json`. Per project is `opencode.json` in the project root. Project config wins over global. Create the file if it does not exist, and merge into it rather than overwriting anything already there.

  The entry:

  {
    "$schema": "https://opencode.ai/config.json",
    "model": "flexinference/gpt-5.6-sol",
    "provider": {
      "flexinference": {
        "name": "FlexInference",
        "env": ["FLEXINFERENCE_API_KEY"],
        "npm": "@ai-sdk/openai-compatible",
        "options": {
          "apiKey": "{env:FLEXINFERENCE_API_KEY}",
          "baseURL": "https://api.flexinference.com/v1"
        },
        "models": {
          "gpt-5.6-sol": {
            "name": "GPT-5.6 Sol",
            "reasoning": true,
            "tool_call": true,
            "limit": { "context": 400000, "output": 128000 }
          }
        }
      }
    }
  }

  Then print this line for me to run in the shell I start OpenCode from. Do not run it and do not ask for the value:

      export FLEXINFERENCE_API_KEY=<paste your key here>

  Rules that matter, do not deviate:
  - Keep `options.apiKey` as the literal `{env:FLEXINFERENCE_API_KEY}` template. Never inline my key.
  - The top-level `model` field is what selects the provider. Without it OpenCode stays on its built-in default and never reaches FlexInference.
  - `options.baseURL` must end in `/v1`.
  - Every key under `models` is a slug sent verbatim on the wire, so it must be one FlexInference serves. `gpt-5.6-sol` is a safe default.
  - Do not put `seed`, `stop`, `presence_penalty`, `frequency_penalty`, `logit_bias`, `logprobs`, `top_logprobs`, `prediction`, `audio`, `modalities`, or `web_search_options` in any model's `options`. FlexInference refuses those Chat Completions parameters, and they also conflict with a key that carries a flex duration.
  - Do not add `start_within` unless I ask. My agent key already carries the deadline, and a key duration falls back safely on models that cannot race while a config duration errors.
  - If I mention working in repositories I do not control, tell me to set `OPENCODE_DISABLE_PROJECT_CONFIG`. A project config wins over the global one and can repoint `baseURL` while still reading my exported key. `OPENCODE_CONFIG` does not prevent that, because project config loads after it.

  Verify the file is valid JSON, then report what you changed and which file you wrote.
  ```
</Accordion>

## Configure OpenCode

1. Export the key in the shell that starts OpenCode.

   ```bash theme={null}
   export FLEXINFERENCE_API_KEY=flex_live_...
   ```

2. Write the provider entry to `opencode.json`.

   ```json theme={null}
   {
     "$schema": "https://opencode.ai/config.json",
     "model": "flexinference/gpt-5.6-sol",
     "provider": {
       "flexinference": {
         "name": "FlexInference",
         "env": ["FLEXINFERENCE_API_KEY"],
         "npm": "@ai-sdk/openai-compatible",
         "options": {
           "apiKey": "{env:FLEXINFERENCE_API_KEY}",
           "baseURL": "https://api.flexinference.com/v1"
         },
         "models": {
           "gpt-5.6-sol": {
             "name": "GPT-5.6 Sol",
             "reasoning": true,
             "tool_call": true,
             "limit": { "context": 400000, "output": 128000 }
           }
         }
       }
     }
   }
   ```

3. Start OpenCode against that file.

   ```bash theme={null}
   OPENCODE_CONFIG=/path/to/opencode.json opencode
   ```

Four fields hold the integration. `npm` picks the OpenAI-compatible package. `options.baseURL` sends requests to the router. `options.apiKey` reads the key from the environment. Each key under `models` is a slug we run.

Add a model by adding a key under `models`. Everything else in the entry is display and limits.

## Global or per project

Put the provider entry in one of two places, depending on how widely you want it.

| Scope       | Path                                | Applies to                    |
| ----------- | ----------------------------------- | ----------------------------- |
| Global      | `~/.config/opencode/opencode.json`  | every project on this machine |
| Per project | `opencode.json` in the project root | that project only             |
| One run     | any path, via `OPENCODE_CONFIG`     | the launch you pass it to     |

**Project config wins over global.** OpenCode looks for `opencode.json` in the working directory and walks up to the nearest Git directory, so a repo can override your machine-wide provider without touching it.

Put the provider entry in the global file and the deadline stays the same everywhere. Put it in a project file and only that repo routes through us.

Set `OPENCODE_DISABLE_PROJECT_CONFIG` to stop the upward search.

Two more sources exist for bundles and automation. `OPENCODE_CONFIG_DIR` names a directory OpenCode reads config out of, and `OPENCODE_CONFIG_CONTENT` holds the JSON inline. Use `OPENCODE_CONFIG` for a file you opt into per run.

```bash theme={null}
OPENCODE_CONFIG=/path/to/opencode.json opencode
```

## Set the deadline in config instead

OpenCode can send `start_within` itself. Both places are plain JSON, and both beat the key.

Set it per model. The `options` block goes into the request body for that model.

```json theme={null}
"gpt-5.6-sol": {
  "name": "GPT-5.6 Sol",
  "options": { "start_within": "00h-00m-30s", "reasoningEffort": "medium" }
}
```

Set it per variant instead, to switch without changing model. Pick one with `--variant` on `opencode run`, or cycle them in the TUI with `ctrl+t`.

```json theme={null}
"gpt-5.6-sol": {
  "name": "GPT-5.6 Sol",
  "variants": {
    "patient": { "start_within": "00h-05m-00s", "reasoningEffort": "high" },
    "now": { "start_within": "priority", "reasoningEffort": "low" }
  }
}
```

A duration here fails on a model that can't race. The same duration on the key falls back instead. That's the reason to prefer the key.

## Confirm the key applied

Every response comes with `x-flexinference-defaults-applied`. OpenCode doesn't show response headers in the TUI, so read the request in the dashboard under **Logs** instead.

## Troubleshooting

**Requests never reach us.** The top-level `model` field is what selects the provider, so defining a provider without naming it there leaves OpenCode on its built-in default. Set `"model": "flexinference/<slug>"`.

**[`401 invalid_api_key`](/errors#invalid_api_key).** `FLEXINFERENCE_API_KEY` is unset in the shell that started OpenCode. Export it before launching, since `options.apiKey` reads it from the environment.

**[`400 unsupported_parameter`](/errors#unsupported_parameter).** A Chat Completions parameter we don't translate was in a model's `options`, such as `seed` or `stop`. Remove it from the entry.

**[`400 key_default_not_applicable`](/errors#key_default_not_applicable).** Your key holds a duration and one of those parameters came beside it. Edit the key to a tier, or remove the parameter.

**[`400 flex_unsupported_for_anthropic`](/errors#flex_unsupported_for_anthropic).** A duration in `options` reached a `claude-*` model on your own Anthropic key. The [race](/deadline-routing#claude-durations-need-a-longer-window) a Claude duration runs takes managed keys. Remove the duration and let the key hold the deadline, since a key duration falls back instead.

**A config edit changed nothing.** A later config source overrode it. Check the search order above, and prefer `OPENCODE_CONFIG` to opt into one file per run.

See [errors](/errors) for every refusal we return, and [agent keys](/agent-keys#troubleshooting-faq) for the ones that are not specific to OpenCode. [OpenWork](/openwork) and [OpenScience](/openscience) read the same provider entry.