Auto Update

opencode can automatically download and apply updates when a new session starts. This keeps you on the latest version without manual intervention, ensuring you always have access to the newest features, bug fixes, and security patches.

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.

The entire process completes in the background before the interface loads. You typically see no interruption. Total update time is usually under 5 seconds on a reasonable internet connection.

Configuration

Disable Auto Update

To prevent opencode from checking for or installing updates automatically:

{
  "autoupdate": false
}

With this setting, opencode starts immediately without any network check. You remain on the currently installed version until you manually upgrade. This is useful in:

• Air-gapped or restricted networks where outbound HTTPS is blocked.
• CI/CD environments where binary stability is critical.
• Audited environments where software changes must follow a change management process.

Notify Only Mode

If you want to know about available updates without automatic installation, use notify mode:

{
  "autoupdate": "notify"
}

In this mode, opencode checks for updates but does not download or install them. A notification displays the available version with a link to the release notes. You can choose to:

• Upgrade later using opencode upgrade.
• Dismiss the notification and continue with the current version.
• Visit the release notes page to review changes before upgrading.

This mode is ideal for users who want to control when updates happen but do not want to check for updates 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

Pre-release versions, release candidates, release notes, and any published tag are valid targets. The checksum verification and atomic replacement process is the same as for the default upgrade path.

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

Auto-update is disabled for package manager installations. The mechanism detects the installation method and silently skips the update check:

Package Manager	Upgrade Command
Homebrew	brew upgrade opencode
npm (global)	npm update -g @opencode/cli
Cargo	cargo install opencode --force
Scoop	scoop update opencode
Chocolatey	choco upgrade opencode
Winget	winget upgrade opencode

Package managers manage their own update mechanisms and binary locations. Running auto-update on a package-manager-installed binary could cause conflicts, permissions issues, or corrupt the package manager's internal state. opencode detects package manager installations by checking for package manager metadata files in the binary's parent directory.

Release Channels

Stable Channel

The default channel. Auto-update checks the latest stable GitHub release. This is the recommended channel for production use. Stable releases are versioned with semantic versioning (e.g., v1.2.3) and are published after passing all integration tests and undergoing a release candidate period.

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

Variable	Effect
OPENCODE_NO_UPDATE	Set 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_URL	Override 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_INSECURE	Set 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

The update check transmits:

• The installed version number.
• The target platform and architecture (derived from the binary file name).

No personal information, project data, environment variables, or usage telemetry is transmitted during the update process.