How to Install and Configure OpenCode as a Terminal Coding Agent

OpenCode is an open-source coding agent you run from a terminal. It can inspect project files, suggest or make changes, and run tools such as shell commands. Its terminal user interface, or TUI, is an interactive, full-screen interface. You can also send a single prompt with opencode run without opening the TUI.

The setup has two main parts: install OpenCode and connect it to a model provider. A provider is the service or local runtime that supplies a language model; the model is the specific model you choose through that provider. The steps below use the current OpenCode 2 instructions. OpenCode 1 has different installation and permission settings, and both versions use the opencode command, so do not mix their instructions.

Install OpenCode 2

The simplest documented installation on supported Unix-like systems uses the OpenCode 2 install script:

curl -fsSL https://opencode.ai/v2/install | bash

The OpenCode installation page also lists package managers and standalone binaries, which you download and run directly. Its current instructions say Windows package managers are not supported and direct Windows users to standalone binaries. Choose an OpenCode 2 option from the current instructions; the older OpenCode 1 script and package names install a different release.

After installing OpenCode, change to the repository you want it to work with and start the interactive interface:

cd ~/code/my-project
opencode

When you start OpenCode from the project directory, it uses that directory as its working context. You can also pass a project directory to the command, or send a one-off prompt without starting the full-screen interface:

opencode run "Explain this repository"

The CLI documentation describes these command modes and additional options.

Connect a provider and choose a model

In the TUI, enter /connect and follow the prompts to choose a provider and sign in or provide credentials. Then enter /models to choose an available model. OpenCode’s provider and model instructions recommend selecting a model from the picker rather than guessing its identifier. The available choices depend on which provider you connect and whether it is enabled for the current project.

For a one-time command, specify a model with --model:

opencode run --model provider/model "Explain this repository"

Replace provider/model with an identifier available through your provider. To make it the project default, add that identifier to the configuration as described below. OpenCode also documents local runtimes, including Ollama, LM Studio, and vLLM. Check the instructions for your selected runtime and model; their tool support and discovery behavior can differ.

Add project settings and instructions

A project configuration lets you set a default model and control agent actions. OpenCode supports opencode.jsonc, a JSON format that also permits comments and trailing commas. Add the following file to the repository as a starting point:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "provider/model",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" }
  ]
}

Replace provider/model with the exact identifier shown in /models. The rules above prompt you before shell commands. They allow routine Git status and diff checks. They deny Git pushes. OpenCode evaluates the rules in order, with the last matching rule taking precedence. Put broad rules before specific exceptions, as in this example. The configuration documentation covers project and user-level configuration locations.

You can also create project-specific guidance in an AGENTS.md file. In the TUI, /init creates or updates that file based on the repository. Review the generated instructions for accuracy before relying on them, and commit the file if you want future sessions to use the same guidance.

Set approval boundaries and review changes

Permission rules control whether OpenCode allows an action, asks you first, or denies it. They are useful controls, but they do not make OpenCode a security sandbox. The built-in build agent has access to tools and access outside the workspace by default; the OpenCode permissions documentation describes these defaults and the available controls.

Keep changes in Git so you can inspect what the agent changed. Review proposed file edits and inspect shell commands before approving them, especially commands that modify files or affect external services. OpenCode also supports a read-only reviewer agent with file edits and shell commands denied, as described in its agent guidance.

Use the TUI for a first task

First, ask OpenCode to inspect the project or explain a file. Then ask it to make changes. In the TUI, type a prompt and press Enter. Type @ to search for and attach a file to a prompt, or / to find commands such as /connect and /models. To enter shell mode, where you can run shell commands, type ! at the start of an empty prompt.

For a single task that does not need an interactive session, use opencode run "your prompt" instead. Check a command’s available flags with its --help option; the command reference documents options for run and other CLI commands.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com