OpenCode's free tier can only be used from within OpenCode: fix
Why OpenCode refuses its free models with this 403 on a server: version 1 from the short installer, a read deny in your config, or another tool.
“OpenCode’s free tier can only be used from within OpenCode” is the refusal OpenCode’s free-model service sends when it does not accept a request as coming from current OpenCode. On a server it usually has one of three causes: the machine runs OpenCode 1, which the short install line opencode.ai/install still installs and which no longer gets the free models; a permission config that denies the read tool outright, which makes free-model requests fail, unattended opencode run included; or a request that is not from OpenCode at all, but from another tool pointed at OpenCode’s free models. opencode --version, one opencode run on a free model and opencode debug config tell them apart. It is not the daily limit, which has messages of its own.
The message and its siblings
The full text is:
OpenCode's free tier can only be used from within OpenCode. Download it at https://opencode.ai and keep building.CopiedIt arrives as an HTTP 403 that is not retried, printed as Error: … or Error from provider (Console): …. The maintainers’ pinned thread for free-tier problems lists two more messages from the same check: “OpenCode 1.18.0 or newer is required to use the free tier” and “This version of OpenCode Desktop no longer supports free models”. Whichever you see, the causes below are the ones to check. The download link in the message is no help on a server: it leads to the same installers, and one of them still gives you version 1.
Three commands that tell the causes apart
opencode --version
opencode run -m opencode/big-pickle "say hi"
opencode debug configCopied- A version starting with 1 (version 2 prints
opencode v2.…): the version is the cause. Upgrade, as below. - Version 2, and the run fails with the message: something in your configuration.
opencode debug configlists the configuration sources in effect, your global file and any project’s own; look in each for areaddeny. - The run answers, but another tool still gets the message: OpenCode, the machine and its network are fine, and the other tool is the cause.
Big Pickle is one of OpenCode’s free models as of mid-November 2026; if it has left the list, use any model opencode models prints with no provider connected.
OpenCode 1 from the short install line
Two install lines are in circulation, and the shorter one gives you the older version. On November 14, 2026, https://opencode.ai/install redirected to the install script on the repository’s v1 branch, which accepts only version 1 releases (its own comment: “GitHub’s Latest release may be OpenCode 2, so it’s never used”). Run on November 13, it installed 1.19.5. Tutorials written before version 2 give that line, so a server set up from one is on version 1. The maintainers’ thread is plain about version 1: “v1 no longer supports free models and only gets fixes for critical bugs.”
Version 1 can move itself to 2, or you can install 2 over it:
opencode upgrade --major
# or
curl -fsSL https://opencode.ai/v2/install | bashCopiedOn 1.19.5, a plain opencode upgrade says it is already current and suggests --major. After either route, opencode --version should print opencode v2.…. The rest of moving to version 2, and the PATH line a script or cron job does not see, are in installing OpenCode on Linux.
A stored credential is not what the free models need. On OpenCode 2.3.0 with no account signed in and no key, run on November 13, 2026, opencode run "say hi" answered on Big Pickle, and a report on 2.1.2 found that a missing OpenCode Console credential alone did not produce this message. The same report’s opener, on 2.0.22, recovered by signing in with opencode auth login opencode, so on an early version 2 build that is worth one try after upgrading.
A permission config that denies read
Locking an agent down on a server is a reasonable instinct, and with OpenCode’s free models it backfires. A report on 1.19.0 is titled “Top-level permission: {"read": "deny"} makes every headless opencode run fail with a misleading free-tier 403”, and the open issue it was merged into reproduces it on version 2 with rules in the new shape:
{ "action": "read", "resource": "*", "effect": "deny" }CopiedOn early builds a blanket deny of the shell did the same; a report on 2.1.2 found that only read still triggered it there, from the global config or a project’s own opencode.json. The explanation offered in the issue, by contributors and not confirmed by OpenCode’s team, is that a tool denied everywhere is left out of the request, and the free service refuses a request without it. Narrow denies are not reported to trip it. Three ways through:
- Deny only what you mean to protect. OpenCode’s permissions docs show the pattern: allow
readon*and deny it on*.env. A narrow pattern in place of the blanket deny is the workaround reporters found. - Use
askinstead ofdeny. The docs sayaskwaits for a decision from the client, so an unattended run needs one:opencode run --autoapproves every permission that is not explicitly denied, which leaves the agent much less locked down than before. - Keep the lock-down and use another model. The refusal is about OpenCode’s free models. A locked-down agent on a Go model, the pay-as-you-go catalogue or your own key does not meet it.
While you are in the config sources, look for a provider entry that points OpenCode’s own provider at https://opencode.ai/zen/v1, a hand-made override some older setups carry. One report’s fix was deleting it, and another found it made no difference, so treat it as a leftover worth removing rather than a sure cause.
Another tool pointed at OpenCode’s free models
OpenCode’s inference docs state the rule: “Free-tier chat models are only available from within OpenCode; other clients receive HTTP 403, even with an API key.” So another coding agent, a proxy, a script calling the API, or a different front end configured with an opencode/…-free or Big Pickle model gets this message however it is set up. The fix is on that tool’s side: give it a paid model, a Go subscription’s models or another provider’s key, or send the work through OpenCode itself with opencode run.
When none of these is it
OpenCode does not document what the free service checks, so a case outside these causes has no published answer. The maintainers close new free-tier reports into the pinned thread, which is where to post one, with the output of the three commands above. A message about free usage or today’s free messages is the daily allowance instead, which OpenCode’s free usage limit covers, and OpenCode’s models covers which free models there are and what else you can connect.