OpenCode setup guide
Provider config in opencode.jsonc, model IDs per plan, and how to check common errors.
You run opencode serve and open the Web UI, only to hit an endless HTTP Basic Auth dialog or an infinite loading spinner returning 401. Stepping through env vars, curl, DevTools, and your reverse proxy isolates the exact cause.
When you start opencode serve or opencode web in OpenCode 2.x and open it in a browser, it is surprisingly easy to get stuck in one of two loops: either you never set a password yet the Web UI spins forever on 401 Unauthorized, or you did set a password, typed it in, and the browser still pops up the HTTP Basic Auth dialog every few seconds.
Re-entering credentials in the browser rarely tells you what is wrong. Stepping out of the browser and checking the environment, curl, the Network tab, and any reverse proxy in front of OpenCode narrows it down in minutes.
Two details trip people up right away: setting OPENCODE_SERVER_PASSWORD="" is not the same as unsetting it, and whenever server auth is active, OpenCode expects the default username opencode.
OPENCODE_SERVER_PASSWORDWhen OPENCODE_SERVER_PASSWORD is completely unset, opencode serve is meant to run without authentication. However, leaving OPENCODE_SERVER_PASSWORD="" in .env or a shell profile—or hitting the unset-password regression tracked in anomalyco/opencode#50370—makes endpoints return 401 Unauthorized without a working auth prompt, leaving the Web UI stuck on an infinite loading spinner.
If you are running locally or on a trusted network without auth, clear both variables rather than leaving them blank:
unset OPENCODE_SERVER_PASSWORDunset OPENCODE_SERVER_USERNAMEopencode servecurl before blaming the browserIf you want password protection enabled, the easiest detail to miss in the browser dialog is the username. When OPENCODE_SERVER_PASSWORD is set, OpenCode defaults OPENCODE_SERVER_USERNAME to opencode—not your macOS/Linux username, and not empty.
Export both explicitly before starting the server:
export OPENCODE_SERVER_USERNAME="opencode"export OPENCODE_SERVER_PASSWORD="your-password"opencode serveThen hit /global/health directly from a second terminal to bypass browser caches and password managers:
curl -i -u opencode:your-password http://127.0.0.1:4096/global/healthcurl returns 200, your credentials and server are fine; the loop is coming from the browser or a proxy.curl also returns 401 on v2 serve, your installed build is likely affected by the auth validation regression in #45856; upgrade OpenCode and retest.Sometimes the first login succeeds, only for the Basic Auth dialog to come right back when you reload the page. In DevTools Network, secondary requests such as /site.webmanifest or /global/health can return 401 and re-trigger the browser prompt (#18325). Native Basic Auth dialogs also clash with browser password managers, which frequently autofill the wrong username and turn a single retry into a loop.
opencode attach flagsAnother common trap is double authentication: if opencode serve sits behind Nginx, Caddy, or Cloudflare Access that already handles login, leaving OPENCODE_SERVER_PASSWORD enabled makes both layers emit conflicting WWW-Authenticate headers. Bind opencode serve to 127.0.0.1 with OPENCODE_SERVER_PASSWORD unset so only the proxy challenges the browser.
If the 401 happens in a second terminal (opencode attach) or an external SDK rather than a browser (#31254), pass -p explicitly (plus -u if you changed the username):
opencode attach http://localhost:4096 -p your-password| Symptom | What to check first |
|---|---|
| Infinite loading / 401 with no password set | Make sure OPENCODE_SERVER_PASSWORD="" is not exported; run unset before starting |
| Browser keeps rejecting the right password | Use username opencode and verify with curl -u opencode:... |
| Looping behind Nginx / Caddy / Cloudflare Access | Unset OPENCODE_SERVER_PASSWORD on OpenCode so only the proxy handles auth |
opencode attach or SDK gets 401 | Pass -p <password> or send Basic Auth headers explicitly |
One last distinction: OPENCODE_SERVER_PASSWORD only guards OpenCode's local HTTP server and has nothing to do with your model API key. For CodingPass, set your model key separately via opencode service set env CODINGPASS_API_KEY cp-live-... as covered in the OpenCode setup guide.
Keep opencode serve local and point your provider config at CodingPass for pay-as-you-go access to Claude, GPT, and open models without fighting server auth.