This guide is the natural sequel to OpenRouter in 15 minutes: the key you created there, with its spending cap, becomes the engine of an agent working in your files. End of the road: a real task completed by OpenCode under your eyes.

Step 1 · Install

Two equivalent routes, from the official documentation: the script (curl -fsSL https://opencode.ai/install | bash) or, if you have Node, npm install -g opencode-ai. Verify with opencode --version: if it answers with a number, you’re in.

Step 2 · Connect the model

Create a dedicated working folder and launch opencode inside it. On first start use the /connect command: search for OpenRouter in the provider list, paste the key. Then pick the model: for the first run a mid-size model is perfectly fine, and if you want to spend zero there are :free variants of several open models (with the per-minute limit documented in the OpenRouter sheet).

Step 3 · Fence the field

An agent that reads, writes and executes should be treated like a new collaborator: clear perimeter before the first task. The practical rule: always work in a dedicated folder containing only the task’s material, never in your home directory or in folders with unrelated documents. Inside that fence the agent can do limited, recoverable damage.

Step 4 · The first real task

Put a file in the folder the agent can work on (a CSV to analyse, a handful of notes to reorganise, a script to comment) and describe the task as you would to a person: what’s there, what you want, how you recognise a good result. Then watch it work: OpenCode shows the steps and the changes, and you supervise. The formative moment is exactly this: seeing the read-act-verify loop happen in your files, with your content.

The typical mistakes

The vague task. «Fix these files for me» produces vague results with any agent. Objective, material, success criterion: the three things you’d give a colleague, you give here too.

The skipped fence. The temptation to run it «just for a second» in the folder with the real documents. Copying three files into a clean folder costs thirty seconds; the alternative is supervising while holding your breath.

The wrong model for the task. If results disappoint, before condemning the agent try a more capable model: with OpenCode the switch is one command, and this is exactly the kind of experiment the pairing with a gateway exists for.

---

Testing status: installation and version actually verified on 19/07/2026 (v1.18.3, via npm). The full run of step 4 was executed on the same date, with a real key and model, by the site’s testing workflow: OpenCode read the course materials’ CSV inside a dedicated fence, produced the analysis with the total and the 4 anomalies the material contains on purpose, and left the original file untouched. Exactly the read-act-verify loop described above.