Last verified 18 October 2026. OpenCode Desktop 2.0.32, Gitea 1.27.2 and gitea-mcp 1.9.0 are free. Our demo uses the free Space Bunny model with made-up data; for work, use your organisation's approved model route. Details for experts at the end of this book.

The idea in one page

• The assistant works with your rights. When OpenCode runs git push, it pushes as you. When it reads a file, it can read what you can. So its limits have to be tighter than yours.
• The limits live in the repository. opencode.json in the project folder is read by every colleague's OpenCode, whatever their own settings. It says which model provider the project may use, and what the assistant may read, edit and run: allow, ask or deny, rule by rule. When several rules match, the last one wins, so the general rule comes first and the exceptions after it.
• AGENTS.md asks, opencode.json enforces. Write the reasons in AGENTS.md; put the locks in opencode.json.
• MCP connects the assistant to other systems. MCP (Model Context Protocol) is a standard way to give an assistant tools, here: reading issues and pull requests on Gitea. An MCP server is a small program OpenCode starts on your computer to provide them. Give it the least it needs: a read-only server and a personal token that can only read.
• Agents are roles with their own rules. A reviewer agent can read and run the tests but never change a file. You call it with @reviewer.
• People still decide. OpenCode drafts, checks and commits on a branch; a person opens the pull request, and someone else approves it.

Watch it once (73 seconds)

No sound. A yellow dot points at each part while the caption explains it. Read the tour as text (opens in a new tab).

Worked example: the plate-reader repository becomes the group's

Our run used OpenCode Desktop 2.0.32 with the free Space Bunny model, our demo Gitea and made-up data. Your answers will be worded differently; what to look for is the same.

Step 1: Start from an up-to-date main. Open the project, start a New session in Build, and make sure your copy has everything from Gitea, as in T19-L02 · Work on a Shared Gitea Repository From Your Computer With OpenCode.

Structure it

Step 2: Write down who works here and what must never happen. Mia writes it for the group:

Understand it

Step 3: Find out what OpenCode may do here today. In Build, send:

.env is a file with settings and passwords, one NAME=value per line; ours holds the LIMS test login. A dry run goes through the motions of a push without sending anything.

You should see: Permission required before it reads .env. Click Deny. That stops the whole answer (Interrupted), so send the second question again on its own:

You should see: the read was asked, but the push ran without asking. Out of the box, OpenCode protects .env with a question and nothing more, and it may run any command, pushes included. One wrong click, or one colleague who clicks Allow always, and the login is in a chat.

Choose tools

• One opencode.json for the group, reviewed like code. Everyone's OpenCode follows it in this project.
• The approved model route only. In our demo that's OpenCode's free models; in yours it's the route IT names (see Details for experts for a gateway entry).
• gitea-mcp, Gitea's own MCP server, in read-only mode, with a personal token that can only read.
• A reviewer agent in .opencode/agents/, and the /check command from T08-L03.

Build it: the group's rules

Step 4: Write the rules. Save this as opencode.json in the project folder, replacing the one from T08-L03 (it still has the answer-file locks):

Read it from the top. policies: refuse every model provider, then allow the approved one; this works like the rules below, last match wins. model: which model to start with. Then the permissions, in order. external_directory: OpenCode stays inside the project, files and commands alike. read and edit: everything is allowed unless a rule says otherwise; here .env and the locked answers. shell, the commands it runs: ask for anything, then allow the harmless ones listed (python3 is for Mac colleagues); ask before any push; refuse a push that names main; refuse any command that mentions .env. * stands for any characters, slashes included, and a rule ending in a space and * also matches the command on its own. Use your own approved provider and model names.

Step 5: Run the same test again. Send:

You should see: All three refused, each with its rule, and no question to you. The rules took effect in the running session. cat .env is a second way to read the same file; a rule for the file alone would not have stopped it. Ours added two observations worth keeping: the push rule matches the whole command text, so it also refuses a dry run, and a branch named maintenance would be refused too. Treat command rules as a speed bump: the real protection is that the login never has to be in a chat.

Step 6: Check the model list. Click the model name under the message box.

You should see: only the approved provider's models. The dialog still offers to connect others, but in this project the policy hides their models. When we allowed only a provider we hadn't connected, the list was empty.

Step 7: Put the rules on a branch. Send:

.env.example tells a colleague which settings exist, without the values. Along the way OpenCode asks before commands that aren't on the allowed list, such as git ls-files. Read each one; if it only looks, click Allow once.

You should see: ours stopped. Our rule .env* also matched .env.example, the file the group needs. OpenCode refused to go around its own lock, explained why, and asked us to decide; it also noticed that the Git section of AGENTS.md still said main is pushed to. Click Dismiss: the rules are yours to change, by hand. There is a second hole it didn't mention: nothing stops it from editing opencode.json itself.

Step 8: Fix the rules by hand and finish. Replace the whole of opencode.json with this version:

The later, more precise rule wins: .env.example may be read and edited. For shell, every command that mentions .env stays refused, including cp .env .env.example, which would copy the login; the one exception is exactly git add .env.example, so the file can be committed. OpenCode's edit tool can no longer change opencode.json or .opencode/. A shell command could, but only after asking you: Deny any command that names opencode.json or .opencode. Then send:

You should see: a question before the push, naming the branch. It's not main, so click Allow once. The push rule refuses only a push whose text names main: a bare git push or git push origin HEAD while you're on main just asks. So read the branch in every push question; the real lock on main is on Gitea (step 9).

Step 9: Have the rules reviewed and merged. On Gitea, open a pull request from team-setup into main, as in T19-L03, and ask your reviewer to read opencode.json line by line: these are the rules their OpenCode will follow too. Protect main with one required approval if it isn't yet. Jonas approved and merged ours.

You should see: the pull request merged. From now on, everyone who pulls main gets the rules. Until they pull, they don't: OpenCode follows the opencode.json of the branch that is checked out.

Build it: Gitea through MCP

Step 10: Create a read-only token. A token is a password for programs, limited to what you tick. On Gitea, click your avatar, Settings, Applications, and click Generate New Token to open the form. Name it opencode-mcp, choose All (public, private, and limited), because the group's repository is private, set issue and repository to Read, leave everything else at No Access, and click Generate Token.

You should see: the token, once. Copy it.

Step 11: Save the token in your home folder. With the token still copied, open the terminal panel (Ctrl+**, **Cmd+ on a Mac, or /terminal) and type the line for your computer. It writes the clipboard into the file .gitea-mcp-token in your home folder, without showing the token.

Windows, if the line in the panel starts with PS (PowerShell):

Windows, if it ends with $ (Git Bash):

Mac:

Never in the project folder: the token is yours, the repository is everyone's. And never paste it into the message box.

Step 12: Install gitea-mcp. Ask IT to install it for everyone in the group, the same way as Git, so that typing gitea-mcp -v in the terminal panel prints a version. Installing it yourself is possible (see Details for experts), but a program the whole group depends on belongs with IT.

Step 13: Add the MCP server and a reviewer agent. In Build, send "Switch to main, get the latest from origin, and create a branch gitea-and-reviewer. Change no file." Then edit opencode.json by hand (since step 8, OpenCode can't) so the whole file reads:

New are the last rule, which refuses any command that names the token file, and the mcp block. -r makes the server read-only: it offers no tool that writes. {file:~/.gitea-mcp-token} tells OpenCode to read the token from each person's own home folder. Use your Gitea's address. Then create the folder for agents in the terminal panel (mkdir -p .opencode/agents) and save this as .opencode/agents/reviewer.md:

mode: subagent means the main assistant hands it a task and gets its answer back. Its own rules come after the project's, so they win: it may not edit, and it may run only the commands listed.

Step 14: Check the connection. Press Ctrl+; (or type /mcp). OpenCode 2.0.32 starts a new MCP server as soon as the file is saved; no restart needed.

You should see: gitea connected. If it says failed, check that gitea-mcp -v works in the terminal panel, and that the token file exists and holds only the token, with no empty line after it.

Step 15: Commit it, and read OpenCode's review. Send:

Ours committed, pushed after our Allow once, ran the new reviewer on its own commit, and then checked the reviewer's claims:

It was right three times. Our first reviewer read only uncommitted changes, so step 13 now has it read the branch too (git diff main...HEAD, and git log). AGENTS.md said no new tooling, so we added one line naming gitea-mcp as the agreed exception, and listed .opencode/. And git push origin HEAD on main would slip past the push rule: that's why main is protected on Gitea too. It also corrected its own reviewer: the token file is safe because of external_directory, not because of a read rule. We fixed the files by hand on the branch, committed and pushed. Then open a pull request from gitea-and-reviewer on Gitea, as in step 9; Jonas approved and merged ours.

Build it: Lena's issue through the new setup

Step 16: Read the issue from Gitea. Lena has reported on Gitea that the new plate reader software writes two lines above the table (Plate ID;P-2026-0412 and Read at;…), so every export stops at line 1. Start a New session, switch to Plan and send:

Use your repository's name and issue number. Ours is 3, because Gitea numbers issues and pull requests together.

You should see: the issue in OpenCode's words, read straight from Gitea, and the questions it raises. The grey line says Used 2 Execute: OpenCode calls MCP tools through its own execute tool. The biggest one: Lena wants the plate ID in the summary, but M1 in SPEC.md says the summary's columns must not change. That's the maintainer's decision.

Step 17: Decide, make the test file, and have the spec and tests written first. Save a test file tests/plate_meta.csv: the two plate lines from Lena's export (Plate ID;P-2026-0412 and Read at;2026-09-28 09:14), then the contents of test_input.csv. Save your expected tests/expected/plate_meta_plate.txt: the same two lines. Switch to Build and send your decisions. Ours:

You should see: one failing check, C10, failing with Lena's own error message. Under the team rules you'll answer more questions now: combined commands, and commands with a | that passes output to a second program, ask even when every part is on the allowed list. Read each one.

Step 18: Build it. Send:

You should see: 11 of 11, and a list of cases OpenCode checked by hand that no test covers yet. On the way, ours wanted to try its own test files. The team rules keep it inside the project, so it made a throwaway folder there, and asked to delete it afterwards:

Allow once a delete only when the path is exactly the throwaway folder OpenCode just told you it made. We were stricter: Deny, then we deleted the folder ourselves and told it so. A delete of anything else in your project, or anything that reads your home folder, gets Deny.

Step 19: Call the reviewer. Type @rev in the message box and choose @reviewer from the list, then write the rest and send:

You should see: a verdict first, then the findings. Ours said CHANGES NEEDED, and the first finding was a real regression nobody had asked about: a header with one extra column, as the same reader update might write, now got a vaguer message than in 1.1. It also listed what no test proves. Yours may word it differently; step 20 closes the gaps either way.

Step 20: Close the gaps, commit and push. First add a third line, Operator;L. Braun, after the two plate lines in tests/plate_meta.csv and in tests/expected/plate_meta_plate.txt. Then send:

You should see: 12 of 12, the commit and the push (after your Allow once). Then open .opencode/commands/check.md yourself and change C1 to C9 to C1 to C12, so /check covers the new checks; OpenCode may no longer edit .opencode/. Commit it on the branch as well.

Step 21: Try to let it open the pull request. Send:

You should see: it can't, because the MCP server is read-only, and it says so. Ours named the way around, reading your token file and calling Gitea directly, and refused it by itself, pointing to the rule from step 13. If yours offers it instead, say no: that would put your token in the chat. And it would fail anyway, because the token can only read (step 10): that's the second lock. Use the link it gives and open the pull request yourself on Gitea, with Fixes #3 in the description, and ask your reviewer.

Step 22: Watch the issue close. Jonas reviewed the pull request, approved it and merged it.

You should see: the issue Closed by the merge, with the commit and the pull request linked. Lena gets a notification. Then switch to main, get the latest from origin, and run the fix yourself in the terminal panel (python3 on a Mac):

Hand it over

Step 23: Bring a colleague onto the setup. For each new colleague, once:

1. Get the latest main, with opencode.json and .opencode/.
2. Create their own token (step 10) and token file (step 11).
3. Make sure gitea-mcp -v works (step 12).
4. Check gitea connected (step 14).
5. Copy .env.example to .env and fill in their own values, if they need them.

Their OpenCode then follows the group's rules, with their own token and their own rights. Keep one session per task, named after it: ours are Team rules for OpenCode and Issue 1: plate information (1.2).

Company: the returns report

An illustration of how the same steps play out; we ran the lab version.

• Steps 3 to 9: the same test finds the same gaps. The company's opencode.json names the company's AI gateway as the only provider (see Details for experts); the ERP login lives in .env and is denied the same way.
• Steps 10 to 15: the repository is on GitHub, so the MCP server is GitHub's own, in its read-only mode, with a fine-grained personal token that can only read the one repository.
• Steps 16 to 22: an analyst's issue about returns without a reason code goes through the same route: spec and tests first, the reviewer, a pull request, a colleague's approval.
• Where it stops: tests that run by themselves on every pull request, and an AI reviewer on the server, are T08-L05 · Run Automatic Checks, an AI Reviewer and Releases You Can Roll Back.

Working with OpenCode day to day

• Answer questions, don't skip them. Allow once for commands that only look, or that delete a temporary folder OpenCode told you it made; Deny for anything that touches secrets, main or your home folder. Allow always stops asking for that kind of command, so use it sparingly.
• Deny ends the answer (Interrupted). Send the request again with what it may do instead.
• Rules come from the checked-out branch. Pull main before you rely on new rules.
• Changes to opencode.json take effect at once, MCP servers included.
• One task per worktree. Local under the message box can start a New worktree: a separate working copy on its own branch, so two sessions can work on two issues without touching each other's files. Settings → Worktrees lists them.
• A second repository as reference. A references entry in opencode.json gives the assistant another repository to read, for example the group's shared analysis code, without making it part of this project.
• @reviewer before every commit; /check from T08-L03 for the tests.

Where your build stops

Rules in the repository, read-only access, a reviewer agent and a second person on every change are enough for a group's scripts. Bring in IT, or move on, when:

• The tests should run by themselves on every pull request: T08-L05 and T19-L04 · Check Every Change Automatically, Release Versions and Tell the Lab.
• The code runs without a person, on a schedule or a server, with its own login: a service account, created by IT, that can read only what the code needs.
• The assistant should write to other systems, not only read: that needs IT's sign-off for each tool it gets.
• Real personal or patient data is involved: see T12-L01 · Decide What You May Paste Into AI at Work before any of it reaches a model.

What goes wrong

Everyone has different settings. Symptom: one colleague's OpenCode pushes, another's uses a model nobody approved. Fix: one opencode.json in the repository, reviewed like code (steps 4 to 9).

A rule is too broad. Symptom: OpenCode refuses a file the group needs, like .env.example. Fix: deny the exact names, then allow the exception after them; the last matching rule wins (step 8).

The assistant can loosen its own rules. Symptom: opencode.json shows up in the Review panel. Fix: deny edits to opencode.json and .opencode/*, and Deny shell commands that name them; people change them by pull request.

The rules aren't there. Symptom: commands run without questions again. Fix: you're on a branch or an old main without the rules. Pull main.

A path that only works on your computer. Symptom: the MCP server fails for everyone but you. Fix: use plain gitea-mcp, installed on everyone's PATH (step 15).

The MCP server doesn't appear. Symptom: No MCPs configured or failed. Fix: check that opencode.json has the server under mcp, then servers; check gitea-mcp -v and the token file (step 14).

The token ends up in the chat or the repository. Symptom: the assistant offers to read the token file, or it shows up in git status. Fix: say no; keep the token in your home folder; if it leaked, delete it on Gitea (Settings, Applications) and make a new one.

Too many questions. Symptom: you click Allow once without reading. Fix: add the harmless commands your group sees every day to the allowed list, by pull request. A question you no longer read protects nothing.

Do it yourself (3 hours)

1. Structure it (10 min): step 2 for your repository.
2. Understand it (15 min): step 3 with a dummy value in .env.
3. Choose tools (10 min): the approved model route, the MCP server for your Gitea or GitHub, and who reviews.
4. Build it: the rules (45 min): steps 4 to 9, with the pull request reviewed by a colleague.
5. Build it: MCP and the reviewer (40 min): steps 10 to 15.
6. Build it: one real issue (50 min): steps 16 to 22.
7. Hand it over (10 min): step 23 with one colleague, at their computer.

Exit check

What you hand in: a repository whose opencode.json sets the approved provider only, .env unreadable, answer files and the rules themselves locked, pushes to main refused and other pushes asked; a read-only MCP server with a per-person token file; a reviewer agent; and one issue closed by a reviewed pull request made with this setup.

It passes when a colleague, after step 23 on their own computer, sees the same three refusals as step 5 and gitea connected, and nobody's token is in the repository.

Rule to remember

The assistant works with your rights, so give it fewer than you have, and let nothing reach main without a second person.

Details for experts

Checked on 18 October 2026. You don't need this to follow the book; it's for setting things up or answering a colleague.

Further reading and tools

• T08-L03 · Write the Spec First, So an AI Assistant Can Change Code Your Team Depends On: the spec, locked answers and /check every change here uses.
• T08-L05 · Run Automatic Checks, an AI Reviewer and Releases You Can Roll Back: tests and a reviewer that run on the server.
• T19-L03 · Propose, Review and Merge Changes With Pull Requests: pull requests and a protected main.
• T19-L05 · Run Your Organisation's Gitea: Teams, Safe Sign-In and a Restore You Have Tested: who may do what on the Gitea itself.
• T12-L01 · Decide What You May Paste Into AI at Work: what may reach a model at all.
• OpenCode: Taught. opencode.json permissions, providers, MCP, agents and @reviewer.
• Gitea: Taught. Access tokens, issues and pull requests.
• Git: Taught. Branches and .gitignore for secrets.
• GitHub: Catalogued. The same setup in the company variant.