| 1 | # OpenCode |
| 2 | |
| 3 | Install and authenticate OpenCode on the machine running your environment, then |
| 4 | enable it in **Settings > Providers**. See [provider setup](./install.md#providers). |
| 5 | T3 Code requires OpenCode 1.14.19 or newer, including when you connect an existing |
| 6 | OpenCode server. |
| 7 | |
| 8 | ## OpenCode 2 |
| 9 | |
| 10 | T3 Code supports OpenCode 2.0.18 and newer. It detects the version on its own, so |
| 11 | the same provider settings work for OpenCode 1.x and 2.x. OpenCode 1.x shows |
| 12 | **Limited support** in its provider settings. |
| 13 | |
| 14 | OpenCode 2 is a separate package, `@opencode/cli`. To move from 1.x, install it |
| 15 | yourself, for example `npm install -g @opencode/cli`. Then refresh provider status. |
| 16 | T3 Code's update button updates whichever package you have installed. It never |
| 17 | switches a 1.x install to 2.x. |
| 18 | |
| 19 | OpenCode 2 converts the shared OpenCode database to its own format the first time it |
| 20 | runs. Don't run OpenCode 1.x and 2.x side by side on the same machine. Threads you |
| 21 | started on 1.x continue on 2.x. |
| 22 | |
| 23 | Plan mode uses OpenCode's `plan` agent. |
| 24 | |
| 25 | ## Local or external server |
| 26 | |
| 27 | Leave **Server URL** empty to let T3 Code start OpenCode locally. A password in |
| 28 | provider settings applies to both that server and T3 Code's connection. With no |
| 29 | password setting, the local server uses `OPENCODE_SERVER_PASSWORD` from its |
| 30 | environment. |
| 31 | |
| 32 | To use an existing OpenCode server, set **Server URL** and its password in provider |
| 33 | settings. T3 Code uses only that configured password for an external server; it |
| 34 | does not forward a local `OPENCODE_SERVER_PASSWORD`. If connection or version checks |
| 35 | fail, check the URL, credentials, and OpenCode version, then refresh provider status. |
| 36 | |
| 37 | After a lost connection, send another prompt to reconnect to the same OpenCode |
| 38 | session. |
| 39 | |
| 40 | ## Approvals |
| 41 | |
| 42 | OpenCode follows the shared [permission modes](./permission-modes.md). **Auto** has |
| 43 | the same rules as **Supervised** because OpenCode has no AI approval reviewer. |
| 44 | Environment files such as `.env` and `.env.local` need approval in restricted |
| 45 | modes even though normal file reads do not; `.env.example` is allowed. |
| 46 | |
| 47 | **Allow for workspace** applies to matching requests in other OpenCode sessions |
| 48 | using the same workspace. It is broader than the current thread, especially on a |
| 49 | shared external server. Use **Allow once** for a single request. Denying an action |
| 50 | does not stop the whole turn. |
| 51 | |
| 52 | ## Refresh models, commands, and skills |
| 53 | |
| 54 | After changing an OpenCode login or configuration, use **Refresh provider status** |
| 55 | in **Settings > Providers** for that environment. On mobile, use **Refresh models** |
| 56 | in the thread settings. Reconnecting also refreshes the catalog; periodic provider |
| 57 | health checks do not. |
| 58 | |
| 59 | Credential changes are read on refresh. Native OpenCode configuration can remain |
| 60 | cached while the local helper is running. Let it sit for 30 seconds without model |
| 61 | refreshes or text-generation work, then refresh again to reload the files. Repeated |
| 62 | refreshes keep the helper alive. An external server may need its own reload or |
| 63 | restart before T3 Code can see configuration changes. |
| 64 | |
| 65 | Existing threads keep their selected model and options even when it disappears |
| 66 | from the catalog. If OpenCode rejects that model, select an available one and retry. |