GuidesHosting choices

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.

November 14, 2026The Everpod team
The short answer

“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.
Copied

It 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 config
Copied

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 | bash
Copied

On 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" }
Copied

On 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:

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.

Run OpenCode on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.