OpenCode: A Lightweight Terminal Agent, Step by Step

Agents at the terminalEN2026-10-24

OpenCode brings an AI coding agent into your terminal. You can ask it to explain a repository, propose changes, edit files, and run project commands without moving your workflow into a separate editor. This walkthrough connects OpenCode to Vana API and starts with a small, reviewable task.

§ 1. Prepare a clean working directory

Use a repository you can safely modify. Before starting an agent, run git status and commit or stash unrelated changes. A clean baseline makes it easier to distinguish the agent’s edits from your own.

Make sure the project’s normal checks work before introducing changes. If tests already fail, note those failures so you do not mistake them for regressions later. Avoid exposing production credentials or sensitive datasets in the working directory.

§ 2. Install and launch OpenCode

With Node.js and npm available, install the CLI by running npm install -g opencode-ai. Then run opencode --version to confirm that the executable is available. If your environment blocks global npm installs, use an installation method supported by your system rather than changing permissions broadly.

Move into your project with cd your-project. You will launch OpenCode here after configuring the provider, so its file operations start in the intended repository.

§ 3. Get a Vana API key

Create a Vana API account, then obtain an API key from your dashboard. Vana API provides one endpoint at https://api.vanaapi.com, with OpenAI-compatible access as well as support for Anthropic Messages and Gemini native protocols. For this setup, use the OpenAI-compatible interface.

In a macOS or Linux shell, set export VANA_API_KEY='your-api-key'. In PowerShell, use $env:VANA_API_KEY='your-api-key'. These commands affect the current shell session. Keep the key out of committed files, screenshots, and shared terminal logs.

Vana API bills per real token with no monthly fee. Agent sessions can make several requests for a single task, so begin with a narrow assignment and monitor usage.

§ 4. Configure the OpenAI-compatible provider

Create an opencode.json file in the repository root. OpenCode supports custom providers through its OpenAI-compatible SDK adapter. Use this configuration, replacing MODEL_ID with an exact model identifier available in your Vana API account:

{ "provider": { "vana": { "npm": "@ai-sdk/openai-compatible", "name": "Vana API", "options": { "baseURL": "https://api.vanaapi.com/v1", "apiKey": "{env:VANA_API_KEY}" }, "models": { "MODEL_ID": { "name": "Selected model" } } } }, "model": "vana/MODEL_ID" }

Replace both occurrences of the placeholder. A display name such as Claude Sonnet 5.5 is not necessarily the API identifier; copy the identifier rather than deriving it from the name. The provider prefix vana/ refers to your local OpenCode configuration, not part of the upstream model ID.

§ 5. Start with inspection, not editing

Run opencode. For the first prompt, ask: “Inspect this repository and explain its entry points, test commands, and coding conventions. Do not modify files or run commands yet.”

Check the response against the actual project. This establishes context before giving the agent permission to change anything. Review any permission prompts carefully, especially for shell commands, file writes, or access outside the repository.

§ 6. Request one bounded change

Choose a small task with a clear acceptance condition. For example: “Add a regression test for empty input in the parser. Keep the public API unchanged. Explain your plan before editing, then run only the relevant tests.”

State which behavior should change and which behavior must remain stable.
Ask the agent to avoid unrelated refactoring and dependency updates.
Require an explanation if it cannot run the requested checks.

§ 7. Review the result and stop deliberately

After the task, inspect git diff and run the relevant checks yourself. Look for accidental file changes, weakened assertions, and commands that succeeded without testing the intended behavior.

If authentication fails, check the environment variable. If the model is unavailable, verify its exact identifier and account access. Keep subsequent tasks similarly scoped: inspect, plan, edit, test, and review. That loop makes a terminal agent useful without turning every session into an open-ended repository rewrite.