run command for scripts and CI, and desktop builds. It reads and edits your code, runs commands, and can be extended with agents, skills, commands, plugins, and MCP servers. Its provider and model catalog comes from models.dev, so every provider listed there shows up in OpenCode’s /connect and /models pickers without extra configuration. ZeroGPU is listed on models.dev, which means you can run OpenCode on ZeroGPU’s models with nothing but an API key.
ZeroGPU is a compute-efficient inference provider for apps and agents. We run purpose-built small and nano language models across an edge network for the high-volume tasks you run constantly - classification, extraction, moderation, routing, summarization - at ~10x lower latency and 50%+ lower cost than frontier-model workflows. Auto-scaling, with zero GPU infrastructure to manage. Plug in and you’re live.
Overview
This guide covers running OpenCode v2 on ZeroGPU, for developers who want a low-cost model provider behind their coding agent. You’ll connect your ZeroGPU key, pick a ZeroGPU model, and run your first prompt, then work through every surface OpenCode exposes for a provider:/connect and opencode auth, environment variables and the background server, /models and opencode models, opencode run, the default model, per-agent models, reasoning variants, provider overrides, and adding ZeroGPU models that models.dev doesn’t list yet. By the end you’ll have OpenCode writing features on ZeroGPU for fractions of a cent per task.
Cookbook
For a runnable, real-world example, see Add Search to a React Store with OpenCode and ZeroGPU. It connects ZeroGPU in OpenCode, picks DeepSeek V4.1 Flash, and has the agent add a working product search box to a small React store in about 20 seconds for under a cent. Check it out to see/connect, /models, and a real agent run end to end.
For more worked examples, browse the cookbook index for
end-to-end walkthroughs of classification, extraction, and PII workflows on
ZeroGPU’s small models.
Video walkthrough
Quickstart
Prerequisites
- A ZeroGPU API key (starts with
zgpu-api-). - OpenCode v2. This guide uses the v2 configuration format (
providers,settings,agents). - A project directory to run OpenCode in.
- A chat model from the model catalog. This guide uses
deepseek-v4.1-flash, which handled OpenCode’s file edits cleanly in our tests.
Get your ZeroGPU API key
- Sign in to the ZeroGPU dashboard.
- Open API Keys and click Create key.
- Copy the key (starts with
zgpu-api-). You’ll paste it into/connect, or export it asZEROGPU_API_KEY, the variable models.dev lists for ZeroGPU.
Install OpenCode
Your first request
Start OpenCode in your project, connect ZeroGPU, and pick a model. This is the flow from the video:zero, pick ZeroGPU, paste your key, and press Enter. Then:
deepseek and pick DeepSeek V4.1 Flash marked ZeroGPU. Type a prompt and press Enter. The line under the reply reads DeepSeek V4.1 Flash · ZeroGPU, and the sidebar shows what the session has cost so far.
To check the connection from a shell without opening the interface:
https://api.zerogpu.ai/v1, the endpoint models.dev lists for ZeroGPU.
Usage
Every section below follows the same shape: what the surface does, what it reads or calls on ZeroGPU, its parameters, a runnable example, and what you get back.How OpenCode finds ZeroGPU
OpenCode builds its provider list from the models.dev catalog. ZeroGPU’s listing gives OpenCode everything it needs, so there’s no provider block to write:
These nine ZeroGPU models appear in
/models. Prices are USD per 1M tokens, and variants are explained in Reasoning variants.
All nine support tool calling, which OpenCode needs to read files, edit code, and run commands. For cache prices, input types, and the full metadata, see the Models.dev integration guide. ZeroGPU models that models.dev doesn’t list yet can be added by hand; see Add unlisted ZeroGPU models.
/connect
Connects ZeroGPU and stores your API key in OpenCode’s credential store, from inside the interactive interface.
/models right away. The stored key is shared by every OpenCode client on your machine, so you only connect once.
opencode auth
The command-line side of /connect, for managing stored credentials from a shell.
stored means the key came from /connect or auth login. A key read from ZEROGPU_API_KEY shows environment instead. To remove a stored ZeroGPU key:
opencode auth export output like a password file: it contains your key in plain text.
Environment variable and the background server
OpenCode runs one shared background server per user, and every OpenCode window and command connects to it. The server, not your current shell, is what readsZEROGPU_API_KEY, so the variable only counts if the server can see it.
ZEROGPU_API_KEY, and opencode auth list shows ZeroGPU with the source environment. If a stored key and the variable both exist, check auth list to see which one is active.
/models
Picks the model for the current session. Once ZeroGPU is connected, its nine models appear, each labeled ZeroGPU. The choice applies to this session and doesn’t change your config.
deepseek also matches deepseek-v4.1-flash-free from OpenCode Zen, so check for the ZeroGPU label before you pick.
opencode models
Lists every model reference available to you from a shell, which is the quickest way to copy an exact ID for --model or config.
opencode run
Runs one prompt without opening the interface, for scripts and CI. The agent works through the task with as many POST /v1/chat/completions calls to ZeroGPU as it needs, editing files in place.
Default model
Sets a ZeroGPU model as the default for new sessions. Put it inopencode.json(c) at your project root (or in .opencode/), or in ~/.config/opencode/opencode.json(c) for every project. Project files override the global one.
opencode.jsonc
/models never rewrites the file.
Agents
Gives individual agents their own ZeroGPU model. OpenCode’s built-ins arebuild and plan (primary agents) and general and explore (subagents). A subagent uses its configured model, or inherits the session’s model when none is set, so you can keep a capable model on build and send read-only searching to a cheaper one.
opencode.jsonc
.opencode/agents/reviewer.md
zerogpu/gpt-5.6-luna#high, while the main session stays on DeepSeek V4.1 Flash.
Reasoning variants
Variants are named presets for one model, selected by adding#variant to a model reference. OpenCode builds them from each model’s reasoning controls on models.dev: a thinking toggle adds a none variant that turns reasoning off, and effort levels add one variant per level. The model table lists the variants for every ZeroGPU model.
body (thinking.type for DeepSeek, chat_template_kwargs.enable_thinking for Qwen):
opencode.jsonc
--thinking.
Provider and model overrides
Customizes how OpenCode calls ZeroGPU without redefining the provider. The models.dev entry still supplies the endpoint, package, models, and prices;providers.zerogpu only adds or overrides.
opencode.jsonc
/models. OpenCode applies provider values first, then model values, then the selected variant.
Add unlisted ZeroGPU models
ZeroGPU serves more chat models than models.dev lists. Add any of them underproviders.zerogpu.models and they appear in /models next to the catalog ones. For a model that isn’t in the catalog, OpenCode assumes tool support, text and image input, a 200,000-token context, and 32,000 output tokens unless you say otherwise, so set the real values.
opencode.jsonc
opencode models and /models under ZeroGPU and are billed at ZeroGPU’s rates. The gpt-oss-20b entry sets only context because the model catalog lists only its context window. The Llama 3.2 and LFM2.5 entries set tools: false: these small models are built for fast chat and summarization rather than multi-step agent loops, so use them for questions and explanations, not for sessions that edit files. Prices here are from the model catalog in November 2026; check it for current values. When models.dev adds one of these models, delete its entry so the catalog’s data takes over.
Patterns and recipes
Capable build agent, cheap explorer. Keepzerogpu/deepseek-v4.1-flash as the default model and set the explore subagent to zerogpu/gpt-5.4-nano, as in Agents. Code search and file reading are the bulk of an agent’s tokens, and they don’t need the bigger model.
Think on demand. Leave DeepSeek V4.1 Flash on its fast, thinking-off default for everyday edits, and reach for the think variant from Reasoning variants only on the hard bug: opencode run --model zerogpu/deepseek-v4.1-flash#think "...". You pay for reasoning tokens only on the runs that need them.
Headless runs in CI. Combine --worktree so the agent works on a separate checkout, --auto so it never waits for approval, --archived to keep scripted sessions out of your list, and --format json for a parseable log:
15,000 x $0.30/1M + 1,000 x $1.20/1M = $0.0057, in line with the cookbook’s $0.0047 to $0.0060. Cached prefixes bring repeat turns down further on models with a cache price.
At a glance
Troubleshooting
ZeroGPU doesn’t appear in/connect or /models. Your OpenCode build predates ZeroGPU’s models.dev listing, or an old background server is still running. Run opencode upgrade, then opencode service stop, and start opencode again.
You exported ZEROGPU_API_KEY but ZeroGPU still isn’t connected. The shared background server started before you exported the key, and it’s the server that reads the environment. Run opencode service stop and then opencode from the shell that has the variable, use --standalone, or store the key with /connect.
ZeroGPU stays connected after you remove the key. A stored key and an environment variable are separate sources. Run opencode auth list to see which is active, opencode auth logout zerogpu ZeroGPU to remove a stored key, and unset ZEROGPU_API_KEY and restart the background server to remove the other.
/models shows two DeepSeek V4.1 Flash rows. The other one is deepseek-v4.1-flash-free from OpenCode Zen. Pick the row marked ZeroGPU, or pass --model zerogpu/deepseek-v4.1-flash. Setting OPENCODE_DISABLE_FREE_MODELS=1 on the server hides free models.
Model unavailable: zerogpu/<id>. The ID doesn’t match the catalog, or ZeroGPU isn’t connected in this project. Catalog IDs are lowercase and exact, such as zerogpu/qwen3.6-35b-a3b. For a model you added in config, the reference uses the models map key, not modelID. Run opencode models | grep zerogpu for valid references.
A #variant fails with a model-resolution error. Variant names come from each model’s catalog data, so #medium exists on gpt-5.6-luna but not on deepseek-v4.1-flash, and gpt-oss-120b has none. Check the model table or define the variant yourself.
401 Unauthorized on the first message. The key is wrong, revoked, or picked up a stray space when pasted. Create a fresh key in the dashboard and run /connect again.
An added LFM2.5 model returns a model-not-found error. ZeroGPU model IDs are case-sensitive. Keep the lowercase key for OpenCode, but set modelID to the exact LFM2.5-1.2B-Instruct or LFM2.5-1.2B-Thinking.
The agent’s file edits fail and it retries. Some models handle OpenCode’s file-edit tool better than others. In our tests DeepSeek V4.1 Flash edited cleanly every time, while GPT-5.6 Luna’s edits failed twice before it recovered. Switch models in /models if edits keep failing.
The sidebar cost reads $0.00 or $0.01. OpenCode rounds the session cost to the cent, and a small task on ZeroGPU costs a fraction of one. Multiply the session’s token counts by the prices in the model table for the exact figure.
No thinking blocks appear on a reasoning model. ZeroGPU doesn’t return reasoning text on the chat completions API, so there’s nothing for OpenCode to display. The reasoning still happens and is billed as output tokens.
Conclusion
OpenCode reads ZeroGPU straight from models.dev, so going from install to a coding agent on ZeroGPU is one/connect and one /models pick. With per-agent models, reasoning variants, and headless runs, you can put cheap, fast models on the routine work and keep deeper reasoning for the tasks that need it, at a fraction of a cent per feature.
Model Catalog
Browse every model available on ZeroGPU and pick the best fit.
API Reference
Explore the full OpenAI-compatible API surface.
Cookbook
Add a search box to a React store with OpenCode on ZeroGPU.
Join Discord
Ask questions and share what you’re building.

