To install stable OpenCode, use the current official installer or a package manager listed in the stable documentation, verify the opencode binary, connect a provider with /connect, then launch it inside the project you want it to understand and run /init.
The shortest official installer command verified on August 26, 2026 is:
The official docs listed this command on August 26, 2026. On the same date, a separate local check ran OpenCode 1.18.23 through bunx opencode-ai, confirmed its version output, and loaded the CLI help. That check did not execute this installer across every operating system. Recheck the current OpenCode docs before running it and follow your organization’s policy for downloaded shell scripts.
Choose stable OpenCode before you install
This guide covers the stable opencode binary and stable v1 configuration.
OpenCode v2 is currently documented as a separate beta with the opencode2 binary. It does not replace the stable opencode command. Beta instructions, configuration shapes, and feature behavior must not be copied into this stable tutorial.
Before doing anything else, decide which track you intend to use:
If a tutorial asks you to run opencode2 or uses a v2-only configuration shape, stop. It may be valid for the beta, but it is not evidence for the stable installation covered here.
Install OpenCode on macOS
The official install script is the simplest documented stable path:
OpenCode’s stable documentation also lists package-manager routes including Homebrew, npm, and Bun. Use the exact command shown on the current official page for the manager you already trust, and let one installation route own future upgrades.
After installation, open a new terminal if the installer changed your shell environment, then verify the binary:
A version string confirms that your shell can find an OpenCode binary. It does not yet confirm that you installed the intended stable build, can authenticate with a provider, or started in the right project. Compare the displayed version with the current stable release information.
Install OpenCode on Linux
The same official stable installer is documented for Unix-like systems:
Run it only after checking the current official page and your environment’s policy for downloaded shell scripts. The stable docs also list npm and Bun routes. Choose one installation owner: mixing the official script with multiple package managers can leave more than one opencode binary on the machine and make upgrades harder to reason about.
Verify the result with:
If the shell reports that opencode cannot be found, do not repeatedly reinstall it. First check the installer’s final output, whether the installation directory is on the current shell’s PATH, and whether the terminal needs to be restarted. The precise install directory is version-sensitive and must come from the current installer output rather than an assumed path copied from another machine.
Install OpenCode on Windows
The official stable documentation recommends Windows Subsystem for Linux (WSL) for better compatibility and performance. In plain language, WSL gives Windows a Linux environment in which terminal development tools can run with Linux-like behavior.
For the recommended path:
- Set up a currently supported WSL distribution using Microsoft’s current WSL installation guidance.
- Open the WSL terminal.
- Recheck the OpenCode Windows/WSL documentation.
- Inside WSL, use the current stable OpenCode installation path documented for Linux.
- Verify
opencode --versioninside that same WSL environment. - Open the project from a location whose Windows/WSL file behavior your team understands.
OpenCode also documents native Windows package-manager routes through Scoop and Chocolatey. If you choose native Windows instead of WSL, copy the current command from the stable official docs and test that path separately.
Do not combine WSL and native Windows installations without recording which shell owns the binary, configuration, provider credentials, and project path. A command that works in PowerShell may not refer to the same installation or files as a command run inside WSL.
Verify and update your OpenCode installation
Use the stable CLI version command after any install or upgrade:
The stable CLI documentation also lists:
The current CLI exposes this upgrade command, but the installation owner still matters. A package-manager-managed install may have a different preferred upgrade owner, so do not assume every route should be upgraded in two places.
If the version is unexpected, check these possibilities before changing configuration:
- the shell is finding an older binary from another installation route;
- the tutorial installed stable
opencode, but you expected the separateopencode2beta; - a terminal opened before installation has stale PATH state;
- an organization-managed environment pins a version intentionally.
Do not delete configuration or credentials merely to fix a version mismatch. First identify which binary and installation route you are actually using.
Connect a provider and initialize your first project
OpenCode is an agent harness: it organizes the interaction, tools, and project workflow, while a provider supplies access to a compatible model. Installing the binary does not by itself connect a model account.
1. Start stable OpenCode and connect a provider
Run stable OpenCode, then use:
Follow the current in-product flow for a provider you are authorized to use. Never paste a real API key into a blog post, screenshot, public issue, committed config file, or shared transcript.
Provider options, authentication steps, models, and billing can change independently from the OpenCode binary. Verify the exact provider path in your account and use the current official provider documentation rather than inventing a universal login sequence.
2. Start inside the correct project directory
Open the terminal in the project you want OpenCode to inspect, then start:
The working directory matters. Starting from a parent folder can expose unrelated files; starting from the wrong child folder can hide project rules or dependencies. Use a disposable or version-controlled test project for the first run.
3. Initialize the project
Inside OpenCode, use the stable initialization command documented by OpenCode:
Initialization is intended to establish project context, but /init may create or modify project files. Run it only in a disposable or version-controlled project, inspect the diff immediately afterward, and do not describe initialization as a read-only step. The exact files or metadata produced must be observed in the current stable build before this article describes them more precisely.
4. Give it a read-only follow-up task
Do not begin with a repository-wide rewrite. Ask for a bounded, non-mutating result, for example:
Explain the project entry point, list the files you inspected, and identify the command that appears to run the smallest relevant test. Do not modify files or run commands yet.
Review the answer against the repository. Only then move to a small change with a defined file boundary, validation command, and rollback path.
Local OpenCode vs an Agent.Space workspace
After the local installation works, compare it with the broader OpenCode cloud Workspace guide instead of treating installation and hosting as the same decision. If you need persistence and collaboration rather than a local setup, review the Agent.Space Workspace separately.
A local OpenCode installation and a managed agent workspace solve different problems.
- Local OpenCode runs in an environment you manage. You own the installation route, local files, shell, credentials, upgrades, and provider connection.
- A managed workspace can provide a cloud project boundary, persistent saved files, sessions, and collaboration behavior—but only if those capabilities and the OpenCode integration are confirmed in the current product.
Do not install OpenCode locally just because you are considering Agent.Space: local installation is the path for running OpenCode in an environment you manage. Likewise, upstream OpenCode documentation does not prove that every feature is available inside a managed workspace. Before choosing the managed path, check the current Agent.Space product interface and public product pages for OpenCode availability, model access, version information, and workspace persistence.
Common OpenCode installation problems
opencode is not found
Read the installer output, reopen the terminal, and confirm that the installation directory is on the current shell’s PATH. If more than one installation route was used, identify which one should own the binary before reinstalling.
The version is not what you expected
Confirm whether you intended stable opencode or beta opencode2. Then check whether an older package-manager or script installation is earlier on PATH. Do not copy v2 beta configuration into stable to solve a binary problem.
/connect does not show the expected provider
Provider availability and authentication are separate from installation. Recheck the current stable provider docs, account eligibility, region, billing path, and network policy. Never use a workaround that exposes a key or bypasses provider restrictions.
/init starts in the wrong project
Exit and start OpenCode from the intended project root. Inspect the files visible to the process before granting write or command permissions.
Windows and WSL see different files or commands
Treat them as different environments. Confirm which shell owns OpenCode, where the project resides, and where provider configuration is stored. Prefer one documented path for the first setup instead of switching between shells mid-task.
Installation checklist
Before calling the OpenCode install complete, confirm:
- you installed stable
opencode, not the separateopencode2beta; opencode --versionreturns the expected current stable version;- one installation route owns upgrades;
/connectreaches an authorized provider flow without exposing a secret;- OpenCode starts from the intended project root;
/initcompletes in a disposable or version-controlled project;- a read-only first task references the correct project files;
- you know how to review and roll back the first write task.
That full loop is more useful than an installer success message. It confirms that the stable CLI, provider path, project boundary, and first task are connected correctly.
Next step
Complete the local stable OpenCode checklist first. Then compare the same bounded project task in a cloud Workspace, learn how OpenCode Skills and OpenCode MCP extend the harness, or review the Agent.Space Workspace when persistence and collaboration are the real requirement.