Skip to main content

Auto Update

tip

Auto-update keeps you on the latest stable version with verified integrity checks.

Default Behavior​

By default, opencode checks for updates at startup. If a newer version is available, it is downloaded and installed automatically before the session begins.

Update Flow​

The update process follows these steps:

  1. Version check – opencode sends a lightweight HTTPS request to the GitHub releases API to compare the installed version against the latest published release. This request contains no personal information, telemetry, or usage data.
  2. Availability decision – If the latest version is greater than the installed version, an update is available. Pre-release versions are ignored unless the installed version is itself a pre-release.
  3. Binary download – The new binary is streamed to a temporary location. The download is verified in chunks using SHA-256 checksums published alongside the release.
  4. Checksum verification – The full downloaded binary is hashed and compared against the published checksum. If the checksum does not match, the download is discarded, the existing binary is preserved, and a warning is displayed.
  5. Atomic replacement – The old binary is replaced with the new one using an atomic rename operation. If the replacement fails (e.g., permission denied), the old binary remains intact.
  6. Session start – The new binary launches the session.

Configuration​

Disable Auto Update​

To prevent opencode from checking for or installing updates automatically:

{
  "autoupdate": false
}

Notify Only Mode​

note

In notify-only mode you are alerted to new versions but must upgrade manually.

Manual Upgrades​

Upgrade to Latest​

opencode upgrade

Downloads and installs the latest stable release. The command:

  1. Checks the currently installed version.
  2. Fetches the latest release information from GitHub.
  3. Downloads the binary for your platform and architecture.
  4. Verifies the checksum.
  5. Replaces the existing binary atomically.
  6. Confirms the new version.

If the latest version is already installed, the command exits with a message indicating no update is needed.

Upgrade to Specific Version​

opencode upgrade v0.1.48

Downloads and installs a specific version by its git tag. This is useful when you need to:

  • Pin to a known-stable version in a production environment.
  • Test a pre-release or release candidate before it becomes the default.
  • Roll back to a previous version if a regression is discovered.
opencode upgrade v0.2.0-rc.1

Check Current Version​

opencode --version

Displays the currently installed version. The output includes:

  • The semantic version number.
  • The git commit hash the binary was built from.
  • The build date.
  • The target platform and architecture.

Installation Method Compatibility​

Auto-update behavior depends on how opencode was installed.

Supported: Install Script​

When installed via the official install script, auto-update works fully:

curl -fsSL https://opencode.ai/install.sh | sh

This method places the binary in /usr/local/bin (or the configured prefix) with permissions that allow the binary to be replaced. The auto-update mechanism has the same level of access and can perform upgrades without password prompts.

Supported: Direct Binary Download​

If you downloaded the binary from the GitHub releases page and placed it on your PATH, auto-update works as long as the binary location is writable by the running user. Common locations:

  • /usr/local/bin/opencode – requires write permission or sudo.
  • ~/.local/bin/opencode – always writable by the user.
  • ~/bin/opencode – always writable by the user.

Not Supported: Package Managers​

Release Channels​

Stable Channel​

Pre-release Channel​

To track pre-release builds, install a binary from a pre-release tag. Auto-update will continue to check the same release category based on the installed version's tag pattern:

  • Tags containing -rc, -beta, -alpha are treated as pre-release.
  • Auto-update from a pre-release will upgrade to newer pre-release versions.
  • Auto-update will not automatically jump from pre-release to stable (or vice versa). To switch channels, use opencode upgrade <specific-version>.

Environment Variables​

VariableEffect
OPENCODE_NO_UPDATESet to any value to skip the update check entirely at startup. Useful in CI environments or when you want to guarantee no network access.
OPENCODE_UPDATE_URLOverride the update check URL for self-hosted or mirror deployments. The URL must return a JSON response matching the GitHub releases API format.
OPENCODE_UPDATE_INSECURESet to true to skip TLS verification during the update check. Only use this in test environments with self-signed certificates.

Troubleshooting​

Auto-Update Not Working​

If auto-update appears to be disabled but you used the install script:

  1. Verify installation method – Run which opencode. The path should point to a standard binary directory (e.g., /usr/local/bin/opencode), not a package manager directory.
  2. Check permissions – Run ls -la $(which opencode). The user running opencode must have write permission on the binary file and its parent directory.
  3. Check configuration – Verify that autoupdate is not set to false in any opencode.json (project or global).
  4. Check environment – Ensure OPENCODE_NO_UPDATE is not set.
  5. Check network – Ensure https://api.github.com and https://github.com are accessible from your network. Corporate proxies may need configuration.

Permission Denied on Update​

If the update fails with a permission error, the binary location likely requires elevated privileges. Solutions:

Re-run the installer with sudo:

curl -fsSL https://opencode.ai/install.sh | sudo sh

Or install to a user-writable location:

curl -fsSL https://opencode.ai/install.sh | sh -s -- --prefix ~/.local

Or run the manual upgrade with elevated permissions:

sudo opencode upgrade

Slow Update Checks​

If the update check is slow (more than 10 seconds), the likely cause is network latency or a rate-limited GitHub API. The update check has a 10-second timeout. If the timeout is reached, opencode starts without updating and continues with the current version.

Corrupted Binary After Update​

If opencode fails to start after an update, the update may have been corrupted during download. Re-run:

opencode upgrade

This re-downloads and reinstalls the latest version. If the issue persists, download the binary directly from the GitHub releases page and replace the binary manually.

Security​

Transport Security​

  • All update checks and binary downloads are performed over HTTPS (TLS 1.2 or higher).
  • The GitHub releases API endpoint is verified using the system's certificate store.
  • OPENCODE_UPDATE_INSECURE must be explicitly set to disable TLS verification.

Integrity Verification​

  • Every binary download is verified against a SHA-256 checksum published alongside the release.
  • The checksum file itself is optionally signed (PGP) for additional integrity guarantees.
  • If checksum verification fails, the update is aborted and the existing binary is preserved.

What Is Not Collected​