Check the runtime
Prepare Node.js LTS, Git, a clean project folder, and a terminal that can reach your model provider.
2026 practical guide
OpenCode Deployment GuideInstall, configure,and verify your model setup
This guide is for developers who want OpenCode running quickly. It covers the environment check, CLI installation, provider connection, project configuration, validation tasks, and the common failures that usually block a first deployment.
- Recommended entry
- CLI first
- Core config
- Provider + model
- Best for
- AI coding users
Quick Start
7-step OpenCode deployment workflow
Use this sequence for a first install or when moving the same setup to a new machine.
Install the CLI
Use the official installation method, then confirm the opencode command is available in the current terminal.
Connect a provider
Add one provider first. Keep API keys in environment variables or a secure credential store, not in the repository.
Choose a model
Start with a stable and affordable model. Verify the model ID from the provider dashboard or API docs.
Create project config
Use opencode.json for non-secret project preferences such as permissions, ignored paths, and default model choices.
Run a small validation task
Ask OpenCode to explain a file, edit a low-risk file, and run a test or formatting command.
Save a troubleshooting note
Record your Node version, provider, proxy settings, default model, and common errors for later reuse.
Provider
Provider setup: make one path work before optimizing
Most deployment failures come from API keys, base URLs, model names, proxy settings, or overly broad permissions. Connect one provider first, then add backups.
| Check | Recommended action | Common mistake |
|---|---|---|
| API key | Store it outside the repository. | Committing secrets to Git. |
| Base URL | Use the official or compatible endpoint. | Missing protocol or using the wrong path. |
| Model name | Copy the real model ID. | Using a marketing name instead of an API ID. |
| Permissions | Start conservatively and loosen after validation. | Allowing every command before testing. |
Project config example
Use this as a non-secret configuration shape. Confirm exact fields with your OpenCode version.
{
"model": "provider/model-id",
"permission": { "edit": "ask", "bash": "ask" },
"ignore": ["node_modules", ".env", "dist"]
}Platform Notes
Platform notes
Windows
Use PowerShell for simple projects. Switch to WSL when your repository depends heavily on Linux tooling.
macOS
Confirm which Node installation your terminal is using, especially if you mix Homebrew, nvm, and system Node.
Linux
Use a normal user, protect API keys, and avoid long-running development tasks under root.
Troubleshooting
Troubleshooting order
- If the command is missing, check the global npm bin path and reopen the terminal.
- If the model list is empty, check provider login, API key validity, base URL, and network access.
- If requests time out, separate local network, proxy, provider rate limits, and service outage.
- If permissions fail, check the working directory, file permissions, and OpenCode permission policy.
- If answer quality is unstable, verify deployment with a stable model before tuning prompts.
FAQ
OpenCode deployment FAQ
What should I install before deploying OpenCode?
Install Node.js LTS, Git, a usable terminal, and at least one model provider API key.
Where should opencode.json live?
Project-level configuration usually belongs in the repository root, but never commit secrets.
How do I verify the deployment?
Run three small checks: read a file, edit a low-risk file, and run a test or formatting command.