Install and first session
Getting OpenCode running, authenticating a provider, and the first commands worth learning.
Install and authenticate
# macOS / Linux
curl -fsSL https://opencode.ai/install | bash
# or with a package manager
npm install -g opencode-ai
brew install sst/tap/opencode
# verify the binary is on your PATH
opencode --version# pick a provider and paste the API key when prompted
opencode auth login
opencode auth listCredentials are written to your user configuration directory, not to the repository, so keys are not committed by accident. If you would rather not use a hosted provider, start a local model server and register it as a provider instead.
Your first session
cd ~/projects/my-app
git status # a clean tree is a safe place to experiment
opencode # opens the terminal interface
# inside the session
/init # scan the project and write an AGENTS.md- Start it from the repository root so the agent can see the whole project.
/initinspects the codebase and writes the build, test and style notes the agent reads later.- Ask for one change, run it, then ask for the next - short steps keep the diff reviewable.
| Command | What it does |
|---|---|
| /init | Scans the project and writes an AGENTS.md with the commands and conventions it found |
| /models | Switches the model or provider for the current session |
| /undo | Reverts the last change the agent made |
| /redo | Reapplies a change you just undid |
| /share | Publishes a read-only link to the session transcript |
| /help | Lists the rest of the interface commands |
⚠️
An agent with shell access can run destructive commands. Answer the permission prompts deliberately, keep an uncommitted reset point such as a scratch branch, and never start a session in a directory that holds production credentials.
FAQ
Do I need a paid API key to try it?
Not necessarily. A hosted provider is the fastest start, while a local model server costs nothing per request at the price of weaker reasoning on large refactors.
Where should I launch it?
At the repository root. If the agent cannot see the files it will invent APIs, and a working directory that is too narrow is the most common cause of bad output.
Related
What OpenCode is Workflow tips and limits
Last refreshed 2026-09-18.