Install OpenCode on Linux: version 1 or 2, sign-in, updates

Two versions, two install lines

Both versions use the command opencode, and OpenCode’s migration page says they “are no longer installed side by side by default”. So the first thing to know is which one a given line gives you. As of October 11, 2026:

The shorter address is the older version: on that day https://opencode.ai/install redirected to the install script on the repository’s v1 branch. Version 2 is not a routine upgrade. The migration page lists three deliberate breaks: plugins use a new plugin API, the server API and its clients have new contracts, and the terminal client’s configuration moves. A tutorial or a plugin written before version 2 may assume version 1, so check which one it means before copying an install line from it.

Install it

curl -fsSL https://opencode.ai/v2/install | bash

On an Ubuntu 24.04 cloud server on October 11, 2026, in a home folder with Ubuntu’s stock shell files, this took about three seconds. It printed Installing opencode version: 2.0.26 and Successfully added opencode to $PATH in /home/you/.bashrc, and left a single 210 MB executable at ~/.opencode/bin/opencode, with a two-line script named opencode2 beside it that runs the same binary. The line it appended to ~/.bashrc:

# opencode
export PATH=/home/you/.opencode/bin:$PATH

Open a new terminal, or run source ~/.bashrc, and opencode --version answers. The script takes three options after bash -s --: --version <version> installs a specific release, --no-modify-path leaves your shell files alone, and --binary <path> installs a binary you already have. It needs curl and tar, and it chooses the build for you: the musl one on Alpine, and a baseline one on an x64 processor without AVX2.

The other routes in the version 2 docs are npm install -g @opencode/cli and brew install anomalyco/tap/opencode-v2. The npm package “uses a postinstall script to select the native opencode binary for your platform”, so an npm set up to skip install scripts will not produce a working command.

Where the PATH line does not reach

Ubuntu’s stock ~/.bashrc opens with a check that returns at once in any shell that is not interactive, and the installer’s line sits at the bottom of the file, below it. On that server an interactive shell found opencode, and neither a login shell running a command nor a plain one did:

$ bash -ic 'command -v opencode'
/home/you/.opencode/bin/opencode
$ bash -lc 'command -v opencode'
$ bash -c 'command -v opencode'
$

That is the case for ssh server 'opencode …', cron jobs and systemd services. Give them the full path, ~/.opencode/bin/opencode.

Already on version 1

Version 1 can move itself. On the same server, with 1.19.0 installed from the version 1 line:

$ opencode upgrade --major
●  Using method: curl
●  From 1.19.0 → OpenCode 2
└  Done
$ opencode --version
opencode v2.0.26

It took about four seconds and replaced the binary in place. The 1.19.0 release note is where the command appeared, and the same note changes how version 1 updates: “Use /update to install OpenCode updates or upgrade to OpenCode 2; updates are no longer installed automatically.” If you installed version 1 through a package manager, the migration page asks you to remove it before installing version 2. Staying on version 1 is a choice the project still supports with releases; 1.19.0 shipped that morning.

Connect a provider with no browser

OpenCode needs a model to talk to, and on a server the dependable way to give it one is a key. In version 2:

opencode auth login                          # pick a provider from a list
opencode auth login anthropic --method key   # straight to pasting a key
opencode auth list                           # what is connected

The providers page sets one limit that matters for automation: “API-key entry and provider forms require an interactive terminal.” An SSH session is one; a script is not. For a script or a service, put the key in the environment instead. OpenCode reads a provider’s variable without saving it:

# one run, with its own private server
ANTHROPIC_API_KEY=sk-ant-... opencode --standalone

# the background service every later command uses
opencode service set env ANTHROPIC_API_KEY sk-ant-...

Sign-ins that go through a browser are less certain on a machine without one. A provider’s OAuth method gives “a browser URL, device code, or authorization-code prompt”, and a device code works from anywhere because you type it into a browser on another device. But an issue open on October 11, 2026 reports that on a Linux machine without xdg-open, opencode auth login prints the authorization link and then exits with Error: Executable not found in $PATH: "xdg-open", so the sign-in cannot be finished. On Ubuntu that command comes from the xdg-utils package, and the key route does not use it.

Saved keys and tokens are on the disk in plain reach of your user account: version 2 keeps them in its database, normally ~/.local/share/opencode/opencode.db, and version 1 in ~/.local/share/opencode/auth.json. Treat both like a password file. OpenCode’s pricing covers which plans and keys it takes and what its own free and paid models cost.

The background service, and two installs on one server

Version 2 does its work in a background server it calls the service, which the first command starts and later commands reuse. On that server, opencode auth list was enough to start it, and opencode service status then printed its address, a port on 127.0.0.1. opencode service stop stops it, and --standalone runs a command with a private server of its own.

Two installs on one machine want the same service port. With another OpenCode 2 service already running on that server under a different home folder, the first command from a new install failed with:

Error: Managed service port 49374 on 127.0.0.1 is already in use by another
process. Configure another port with `opencode service set port <port>` and
start the service again.

Doing what it says cleared it:

opencode service set port 49391
opencode service status

The service is also what serves OpenCode’s web interface. OpenCode on a remote server covers reaching that from a laptop or a phone, and what protects it.

Updates, pinning and removal

In version 2 updating is a setting in the global config, ~/.config/opencode/opencode.json. The config page gives its three values: "disable" skips update checks, "notify" shows an update before installing it and is the default, and "auto" installs without asking. It adds that an automatic install “does not restart a running server”, so on a machine where the service runs for days, restart it to pick the update up.

opencode upgrade            # to the newest
opencode upgrade 2.0.21     # to one version
curl -fsSL https://opencode.ai/v2/install | bash -s -- --version 2.0.21

To hold a version, install it by number and set "update": "disable".

Removal differs between the versions, and opencode uninstall --dry-run shows which you have before anything is deleted. Version 1’s dry run listed everything: its data, cache, config and state folders, the binary and the PATH line in ~/.bashrc, with --keep-config and --keep-data to spare some. Version 2.0.26 describes its own as “Uninstall OpenCode, keeping session data, configuration, and state”, and its dry run listed only the cache, stopping the background service, and the binary marked for manual removal. To erase a version 2 install completely, delete these yourself afterwards:

~/.opencode                  # the binary
~/.config/opencode           # configuration
~/.local/share/opencode      # sessions, the database with saved keys, logs
~/.local/state/opencode      # service state
~/.cache/opencode

opencode debug paths prints the same list for your machine, which is the one to trust if you have set any of the XDG variables.

When it does not work

• opencode: command not found from a script, cron or ssh server '…'. The PATH line is below the interactive check in ~/.bashrc. Use ~/.opencode/bin/opencode.
• Managed service port … is already in use by another process. Another OpenCode 2 service on the machine has the port: opencode service set port <port>.
• Executable not found in $PATH: "xdg-open" during sign-in. The open issue above. Connect with a key.
• A service that stops answering. OpenCode’s troubleshooting page starts with opencode service restart, and warns against deleting or editing the service files or the database by hand.
• Anything else. The log is ~/.local/share/opencode/log/opencode.log; tail -f it while you reproduce the problem.

An interactive session ends when your SSH connection does, like any terminal program. Start it inside tmux and it stays on the server while you are away.