OpenCode Deployment GuideInstall, configure,and verify your model setup

1. If the command is missing, check the global npm bin path and reopen the terminal.
2. If the model list is empty, check provider login, API key validity, base URL, and network access.
3. If requests time out, separate local network, proxy, provider rate limits, and service outage.
4. If permissions fail, check the working directory, file permissions, and OpenCode permission policy.
5. If answer quality is unstable, verify deployment with a stable model before tuning prompts.

A reliable OpenCode deployment starts with a few explicit choices. Decide which model provider is the default, which model should handle normal code edits, which cheaper model can explain files, and which fallback provider you will use when latency or rate limits interrupt work. Write those choices down before inviting teammates to use the same setup.

Keep the OpenCode CLI close to the project workflow. The first validation should happen inside a small repository with Git history, tests, formatting, and a harmless command. That gives you evidence about file reading, diff quality, command approval, and recovery after a mistake without risking production code.

The most common mistake is treating opencode.json as a secret store. Use it for non-secret preferences such as default model, ignored folders, and permission posture. API keys, provider tokens, proxy credentials, and private base URLs belong in environment variables, a password manager, or the provider's recommended credential path.

After installation, test the deployment in layers. First confirm the opencode command launches from a fresh terminal. Next confirm the model list loads. Then ask OpenCode to summarize a small file, edit a documentation line, and run a read-only command. Only after those checks pass should you allow broader edits or project-specific automation.

Record the exact Node.js version, OpenCode version, provider name, model ID, operating system, shell, and proxy setting used during the successful test. That note saves time when the same machine later fails after a shell profile change, a provider outage, or a model rename.

For teams, add a short onboarding note to the repository: how to install the CLI, where opencode.json lives, which paths are ignored, which commands require approval, and how to report a failed provider connection. The note does not need to be long; it needs to be accurate enough for the next developer to reproduce the working deployment.

Treat the first working setup as a baseline rather than a permanent configuration. Review model IDs, provider pricing, permission rules, and ignored paths whenever the project changes deployment scripts, adds generated output, or starts handling sensitive data. OpenCode can be flexible, but flexibility needs a small amount of maintenance.

When troubleshooting, separate four layers: local runtime, network path, provider credentials, and project permissions. A missing command points to installation or PATH. An empty model list points to provider access. A timeout usually belongs to network, proxy, quota, or provider availability. A denied edit usually belongs to workspace permissions or policy.

Use Git as the final safety net. Before trusting a new OpenCode deployment, confirm that every generated edit is easy to inspect, revert, and explain. A good setup is not just one that answers quickly; it is one that leaves clean diffs and predictable command history.

If the setup will be shared, schedule a short review after the first week. Check whether developers used the documented model, whether approval prompts blocked real work, whether ignored folders covered build output, and whether the provider connection stayed stable. Update the guide from those observations instead of waiting for a larger migration problem, and keep a short changelog so future troubleshooting starts from known configuration changes. Recheck the baseline after provider updates.