Skip to content
← Setup kits and setup guides

Setup guide · last checked October 17, 2026

A backup coding environment that keeps you working when your AI coding quota runs out

When your coding assistant hits its quota, you continue the project with OpenCode on a separate Git branch: you connect a Gemini API key (the OpenCode documentation does not cover this entry separately; it is expected to appear in the list), have it do a small task and review the change yourself.

Compiled from the official documentation. The basis for each step is listed under it.

What you get

A coding environment that works on a separate branch of your project, uses the model of the provider you connect and shows you every change.

How it runs

You start it. You open the tool from the terminal and approve every change yourself. Nothing is set up to run on its own in the background.

Where it runs

Windows · macOS · Linux

What the cost depends on

API usage · No cost · Setup service

Who it is for

  • People who don't want work to stop when their coding assistant's usage quota runs out
  • Developers and small teams who are comfortable running commands in a terminal and whose project is tracked with Git

Who it is not for

  • People who want to send a client's confidential code or personal data to a free-tier model: the free tier may use your data to improve products (see step 3)
  • People who expect the chat history and the same results from the previous assistant to carry over: past chats do not move when you switch assistants
  • People looking for GitHub Models as a free option: the service was retired in July 2026 and is not an option in this guide
  • People who want to get around quotas with multiple accounts, a VPN or router tools that pool free quotas: this guide does not recommend it, and providers' terms may not allow it

How the system fits together

Separate project branch → OpenCode → Gemini API key (the OpenCode documentation does not cover the Google AI Studio entry separately; it is expected to appear in the list, and if it doesn't, use an alternative provider) → a model that shows up in the list that day → project instructions → small task → diff and project checks.

  • OpenCode required

    An agent that runs in the terminal and reads and changes code with the model you connect

    Tool guide

  • Google AI Studio / Gemini API required

    Model provider: the API key and the free tier live here

    Tool guide

  • Freebuff optional

    Alternative ready-made tool (limited tier)

    Alternative: If you want to try an ad-supported tool without getting an API key

    Tool guide

  • OpenRouter optional

    Alternative model provider

    Alternative: If you want to try many models with one key

    Tool guide

Connections between tools

  • OpenCode Gemini API · Automatic via API · HTTPS requests; the API key is entered with /connect and stored in a local auth.json file · permission: Model calls up to the key owner's quota
  • Project files OpenCode · Via a file · Project folder; instructions are read from the AGENTS.md file

Before you start

Computer and software

  • Operating system: Windows, macOS, Linux
  • Git: installed; your project is a Git repository
  • Node.js and npm: OpenCode is installed as an npm package; install Node.js from the official download page and confirm npm works with npm --version
  • A modern terminal app: Required for the OpenCode terminal interface; on Windows the documentation recommends using WSL

Accounts

  • Google account (for a Gemini API key in Google AI Studio) — The model provider you connect to OpenCode; Turkey is on the list of countries where this service is available. There is a free tier; you must be 18 or older and use it for professional or business purposes. On the free tier, content you send may be used by Google to improve products. The paid tier requires a billing account.

Step-by-step setup

Which one do you want to do?

The steps you check stay only in this browser; they do not confirm that the setup works. You finished 0/8 steps.

  1. Step 1 · In the terminal

    Create a separate branch of your project

    What for: Collect the changes on a separate branch so you can throw the branch away if you change your mind. A branch does not copy the folder: it uses the same working folder.

    1. In the terminal, go to your project folder. First check the state with git status. If you have uncommitted changes, save them (commit) with the two commands below. This matters so they don't get carried onto the new branch. Check that files like .env are in .gitignore; git add -A adds everything.
    2. If the project was just created with git init, make the first save (commit) once as well; creating a branch in a repository with no commits doesn't make sense.
    3. Create a new branch with the command below. The tool can also touch environment files like .env and files Git doesn't track; the branch does not protect those.
    4. If you want full isolation, copy the project folder somewhere else and work there. How to undo the trial is in step 6.
    Windows · macOS · LinuxFolder: Project root folder
    › git status
    Windows · macOS · LinuxFolder: Project root folder
    › git add -A
    Windows · macOS · LinuxFolder: Project root folder
    › git commit -m "before trial"
    Windows · macOS · LinuxFolder: Project root folder
    › git switch -c opencode-trial

    How you know it worked

    • The terminal reports that you switched to the new branch.
    If you get stuck: problems specific to this step
    • Git says this folder is not a repository
      Make sure you're in the project folder. If the project isn't tracked with Git, create a repository with git init and make the first save (commit), or work in a copy of the folder.
    Based on: Git: switch command, Git: status command, Git: add command, Git: commit command, Git: restore command, Git: clean command, Git: branch command
  2. Step 2 · In the terminal

    Install OpenCode pinned to a version

    What for: Get the terminal-based coding agent ready.

    1. On Windows the documentation recommends WSL; if WSL is set up, run the command there. The same command is also listed in the documentation for the Windows terminal.
    2. Install version 1.19.3 with the command below. This installs OpenCode's version 1 line; the version 2 line mentioned on the home page is a separate package, and since both use the same opencode command, don't install them together.
    3. After installing, type opencode in your project folder and check that the interface opens.
    4. If the npm command isn't found, Node.js isn't installed; install it from the Node.js link in the prerequisites, close and reopen the terminal, then try again.
    Windows · macOS · LinuxFolder: Any folder
    › npm install -g opencode-ai@1.19.3

    Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

    Windows · macOS · LinuxFolder: Project root folder
    › opencode

    How you know it worked

    • The terminal interface opens.
    If you get stuck: problems specific to this step
    • npm command not found
      Node.js isn't installed or the terminal session is stale. Install Node.js from the official download page, reopen the terminal and check with npm --version.
    • opencode command not found
      Close and reopen the terminal; check that npm's global package folder is on your PATH.
    • It was previously installed another way or with the version 2 line
      The OpenCode documentation says installation methods can conflict with version 2; remove the old one first, then install a single line.
    Based on: OpenCode: intro and installation, OpenCode: npm package registry, Node.js: download pageGet help with this step →
  3. Step 3 · In the browser

    Get a Gemini API key and connect it to OpenCode

    What for: Give OpenCode access to the model that will read and write code.

    You check this step yourself; the system should not move past it without your approval.

    1. Know this first: on the Gemini API free tier, the code and responses you send may be used by Google to improve products and may go through human review (check the 'Used to improve our products' row per model on the pricing page; the additional terms say not to send sensitive data to the free service). Don't use files containing client code, secret keys or personal data on this tier.
    2. Sign in on the API keys page of Google AI Studio and create a key. Don't share the key with anyone or put it in a repository.
    3. In the OpenCode interface, type /connect and pick the plain Google/Gemini entry from the list, not Vertex AI. The OpenCode documentation has no separate section for AI Studio (only Vertex AI); the entry is expected to appear in the list under the name Google or Gemini, which is inferred from the documentation. Then paste the key.
    4. According to the documentation, the key is stored in ~/.local/share/opencode/auth.json (this path is in Linux/macOS format; the location on native Windows is not stated in the documentation). Never add that file to any repository.
    5. Don't use a second account or a VPN to multiply your quota: limits are per project, and this guide does not recommend getting around quotas.

    How you know it worked

    • The connection completes without errors.
    • The models of the provider you connected appear in the /models list (according to the documentation, models are selected with /models).
    If you get stuck: problems specific to this step
    • The AI Studio page won't open in your country or shows an access block
      Turkey is on the official country list; if it still won't open, check Google's list of possible causes on that page and use the path for switching to another provider (step 7).
    • Google isn't in the /connect list
      Type google in the search; OpenCode takes its provider list from Models.dev, where the name is Google (not Vertex AI). If it's still missing, check your OpenCode version.
    • Only Vertex AI appears in the /connect list
      Vertex AI is a different Google Cloud service. Type gemini or google in the search; if the plain Google/Gemini entry doesn't show up, check your OpenCode version; if it's still missing, the main path of this guide won't work and you should look at the alternative providers.
    Based on: Gemini API: API keys, Gemini API: additional terms of service, OpenCode: providers, Gemini API: available regions, Gemini API: rate limitsGet help with this step →
  4. Step 4 · In the terminal

    Pick a model that is available that day

    What for: Select a model you can actually call on the free tier.

    1. In the OpenCode interface, type /models and pick one of the models from the provider you connected.
    2. On the Gemini pricing page, check which models are listed as free on the free tier; some models are not on the free tier (for example Gemini 3.1 Pro Preview). Don't use a model that isn't listed or returns an error.
    3. The OpenCode documentation says only a few models are good at writing code and calling tools; always check the result by eye on the first task.

    How you know it worked

    • The name of the model you picked appears in the interface; according to the documentation, the model is selected with /models.
    If you get stuck: problems specific to this step
    • I get a permission or quota error on the selected model
      Check on the pricing page that the model is offered on the free tier; pick another model.
    Based on: OpenCode: models, Gemini API: pricing and free tierGet help with this step →
  5. Step 5 · In the terminal

    Set up project instructions and permissions

    What for: Make sure the tool knows the project's rules and doesn't delete files or run commands without asking.

    1. If your project already has an AGENTS.md, OpenCode reads it. If not and there is a CLAUDE.md, the documentation says that one is read as a fallback; if both exist, only AGENTS.md is used.
    2. If neither exists, type /init in OpenCode; the tool examines the project and creates an AGENTS.md. Read the resulting file and fix any mistakes.
    3. Create an opencode.json file in the project root and set file editing and command execution to ask for approval (example below). According to the documentation, the default behavior is to allow all operations without approval.
    opencode.json · json
    {
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

    The format follows the permission example on the official configuration page.

    How you know it worked

    • AGENTS.md and opencode.json are in the project root.
    • The tool asks you before editing files and running commands.
    If you get stuck: problems specific to this step
    • The tool ignores the project's rules
      Check that AGENTS.md is in the project root and that you opened OpenCode from that folder.
    Based on: OpenCode: rules (AGENTS.md), OpenCode: configuration and permissionsGet help with this step →
  6. Step 6 · In the terminal

    Give it a small task, then review the change and the checks

    What for: See with low risk whether the tool is useful in your project.

    You check this step yourself; the system should not move past it without your approval.

    1. Ask for a small, well-bounded job, for example fixing a typo in a single file or adding a test for one small function.
    2. Each time the tool asks for permission, read what it is about to do, then approve or decline.
    3. When it's done, look with the two commands below: git status shows newly created files, git diff shows changes to existing files. Undo any change you don't understand or don't want.
    4. Run the project's own check commands (tests, linting, build) and look at the result. If something fails, review the change first, not the tool.
    5. If you abandon the trial, what you committed in step 1 is kept; only what the tool did is removed. If you committed, first go back to your old branch: git switch - returns to the previous branch, and if you forgot the name, list branches with git branch. Then delete the branch with git branch -D opencode-trial (you can't delete the branch you're on).
    6. Careful: git branch -D deletes everything you committed on that branch and didn't merge elsewhere.
    7. If you didn't commit, git restore . in the project root permanently deletes uncommitted changes and they can't be recovered; look with git diff first. If you already ran git add, you need git restore --staged . as well. For new files, git clean -n -d only lists them and deletes nothing; if your own file is on the list, leave it alone and delete the tool's files by hand.
    Windows · macOS · LinuxFolder: Project root folder
    › git status
    Windows · macOS · LinuxFolder: Project root folder
    › git diff

    How you know it worked

    • git status lists new and changed files; git diff shows the changed lines.
    • The project's own checks pass, or you see the error.
    If you get stuck: problems specific to this step
    • The tool changed unexpected files
      If you committed, go back to the old branch with git switch - (if you forgot the name, git branch), then run git branch -D opencode-trial; everything you committed on that branch and didn't merge is gone. If you didn't commit, git restore . in the project root permanently deletes uncommitted changes; look at git diff first. New files remain: git clean -n -d only lists them, it doesn't delete. Deleting or leaving a branch does not undo uncommitted changes by itself.
    Based on: Git: status command, Git: diff command, Git: switch command, Git: restore command, Git: clean command, Git: branch command, OpenCode: configuration and permissionsGet help with this step →
  7. Step 7 · In the terminal

    What happens when the quota runs out, and how to switch to another provider

    What for: Recognize a quota error and keep working through another permitted route.

    1. On the Gemini side, limits are per project; the daily request quota resets at midnight Pacific time. See your current limits in AI Studio. When you exceed a limit, you get a rate-limit error.
    2. When the error comes, you can wait or switch to another permitted provider you've set up under your own account: add it with /connect and pick its model with /models. Don't send confidential code to OpenRouter :free models: the training opt-out setting does not cover the exceptions or OpenRouter's own policy.
    3. Don't use a second account or a VPN for the same quota. And don't send confidential code to a provider with looser terms just because your quota ran out.

    How you know it worked

    • You see a quota or rate-limit message in the error.
    • You can add another provider with /connect and pick a model with /models.
    If you get stuck: problems specific to this step
    • I get a rate-limit error after a few requests
      You may have exceeded the per-minute or daily limit; check your limits in AI Studio and wait, or pick another model.
    Based on: Gemini API: rate limits, OpenCode: providers, OpenRouter: rate limits, OpenRouter: privacy and loggingGet help with this step →
  8. Step 8 · In the terminal

    Shortcut: try Freebuff on its limited tier

    What for: Try coding with a ready-made tool without getting an API key.

    1. First create the project branch (step 1). Install version 0.2.29 with the command below.
    2. Don't use confidential or client code with this tool: Freebuff uses your messages, agent traces and files to run the service and may analyze them to personalize ads; the note for a model or feature may also mention AI training.
    3. Because Turkey is not on the full-access list, you get the limited-access tier: the README states 5 hours a day (4 hours with a VPN or proxy). Read the session limits and data note the tool shows at startup.
    4. Whether an account or sign-in is required is not clearly stated in the sources (the README says no key, subscription or credits are needed; the product page has a sign-in link). Read whatever the tool asks for.
    Windows · macOS · LinuxFolder: Any folder
    › npm install -g freebuff@0.2.29

    Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

    How you know it worked

    • When you type freebuff in the project folder, the tool opens and shows the session limits.
    If you get stuck: problems specific to this step
    • The tool says the daily time is used up
      The limited tier's daily time has run out; try again the next day or go back to the Gemini API connection on the main path.
    Based on: Freebuff: README, Freebuff: full-access country list (source code)

Is the setup working? Check these

  • After connecting the provider in OpenCode with /connect, its models appear in the /models list. If the Google/Gemini entry doesn't appear, the main path won't work; look at an alternative provider.
  • After the small task you gave, git status and git diff show the change; the project's own checks report the result.
  • On a quota or rate-limit error, you can switch to another permitted provider with /connect and /models.

What you pay for

The items are separate, not a total; which ones you need depends on the path you set up. Prices change, so check the source of each item.

  • API usageModel usage, free tier

    Some models are listed as free on the free tier; limits are per project. The pricing page says content on the free tier may be used to improve products; check the 'Used to improve our products' row per model. source

  • API usageModel usage, paid tier

    The Gemini API only counts as paid through a cloud project with a linked billing account; check the price on Google's page. source

  • No costClient (OpenCode)

    The software is MIT-licensed and free; model costs are separate. source

  • Setup serviceSetup support

    If you like, you can get help with connecting providers, project instructions and permission settings; scope is agreed on a call.

Sources

You can set it up yourself; we can do the step you get stuck on together

Check the steps you want. The request form receives the system name and your selected steps as a visible summary that you can edit. There is no need to share any password or API key.

Steps you want help with
Discuss my setup needs Help is available with choosing a provider, installing OpenCode, the project instructions file, permission settings and a setup for switching to another provider when the quota runs out. The exact scope and price are set in a call.

If you are looking for another route

The guide is free and needs no sign-up; you can follow the steps here yourself. If you’d like professional support at some point, choose the option that fits your needs. This doesn’t affect the rankings in the guide.