OpenCode Updater

!WARNINGArchived Project - This repository was archived by the owner on Dec 17, 2025. It is now read-only.

The AUR package reliability issues that originally motivated this tool have been resolved. OpenCode can now be reliably updated through standard package managers. This documentation is preserved for historical reference and for users who may still have the tool installed.

OpenCode Updater is a mission-critical infrastructure tool designed to automate the lifecycle management of the opencode binary. It replaces fragile manual update processes and unreliable package managers (like AUR) with a deterministic, security-first compiled binary approach.

!IMPORTANT This tool performs privileged system operations (modifying /usr/bin/). It is built with strict path validation and checksum integrity checks to ensure safe execution in production environments.

Installation

Prerequisites

• Operating System: Linux (x86_64)
• Privileges: sudo access (required for writing to /usr/bin/)
• Dependencies: git, cargo (for building from source)

Build from Source

The recommended installation method ensures you are running the exact code audited for your environment.

# 1. Clone the repository
git clone https://github.com/NocturnLabs/opencode-updater.git
cd opencode-updater

# 2. Build Release Binary
cargo build --release

# 3. Install to System Path (Optional)
sudo cp target/release/opencode-updater /usr/local/bin/

Getting Started

Quick Start: Safe Update

To update opencode to the latest stable release found on GitHub:

sudo opencode-updater

This default mode performs a Safety-First Update Cycle:

1. Backup: The current /usr/bin/opencode is backed up to ~/.local/share/opencode-updater/versions/.
2. Fetch: Queries GitHub API for the latest release metadata.
3. Verify: Downloads the binary and its SHA256 checksum, verifying integrity before execution.
4. Install: atomically moves the validated binary to /usr/bin/opencode.

Advanced Mode: Interactive Selection

For users needing specific builds (e.g., debugging variants or beta releases), use the interactive CLI:

sudo opencode-updater --bin

Core Features

1. Version Management Architecture

Unlike simple curl | bash scripts, OpenCode Updater maintains a local registry of installed versions. This allows for instant rollbacks and audit trails.

Data Layout (~/.local/share/opencode-updater/):

• versions/<version>/: Isolated directory for each installed version.
  • opencode: The binary file.
  • metadata.json: Immutable record of the installation source, time, and checksum.
• current: Symlink pointing to the actively installed version.
• cache/: Local cache of GitHub API responses to prevent rate-limiting.

2. Smart Archive Extraction

The tool implements a Polyglot Extractor that handles distribution variances automatically:

• Primary Strategy: Attempts to fetch and extract .zip assets (standard release format).
• Fallback Strategy: Automatically fails over to .tar.gz if the zip is unavailable.
• Security Check: All extraction paths are validated against directory traversal attacks (e.g., ../../bin/sh) before any file is written.

3. Checksum Integrity Verification

Security is enforced by default. The updater looks for a corresponding {asset}.sha256 file in the release assets.

• If found: The update ABORTS immediately if the calculated hash of the downloaded binary does not match the upstream signature.
• If missing: A warning is logged, proceeding only if the TLS connection to GitHub was secure.

Specification & Reference

Configuration System

Arguments are passed strictly via CLI flags to ensure stateless operation in CI/CD pipelines. State is persisted only for version history.

Storage Schema (metadata.json)

Each installed version includes a strict JSON manifest:

{
  "version": "1.0.73",
  "tag_name": "v1.0.73",
  "release_date": "2025-11-18T12:00:00Z",
  "download_url": "https://github.com/...",
  "checksum": "a1b2c3d4...",
  "installed_at": "2025-12-13T10:00:00Z",
  "install_path": "/usr/bin/opencode",
  "release_notes": "Fixes critical bug in..."
}

Security Constraints

• Root Requirement: The final installation step (mv to /usr/bin) invokes sudo. The tool accepts this privilege escalation requirement as a security feature—preventing unprivileged user processes from modifying system binaries.
• Path Traversal: The internal extract_archive function validates every file entry against std::path::Component::ParentDir to strictly confine extraction to the temporary workspace.
• XAttr Stripping: When handling tar archives, extended attributes are intentionally dropped to prevent privilege escalation vulnerabilities on misconfigured filesystems.

CLI Reference

Status & History

View the complete state of your OpenCode environment.

opencode-updater --list-versions

Output:

📦 opencode Versions

✅ Current: 1.0.73 (installed: 2025-12-13 14:30)

📁 Installed Versions:
  → 1.0.73 (2025-12-13)
    1.0.72 (2025-11-20)
    1.0.70 (2025-11-10)

🌐 Available Updates:
  📦 v1.0.74 (2025-12-14)
  📦 v1.0.73 (2025-11-18)

Performing a Rollback

Emergency reversion to a stable state.

sudo opencode-updater --rollback 1.0.72

Output:

Successfully rolled back to version 1.0.72

Checking Release Notes

Read what's new before updating.

opencode-updater --changelog latest

Output:

📦 Release: v1.0.74 (v1.0.74)
📅 Published: 2025-12-14T09:00:00Z

## What's Changed
* Fixes memory leak in websocket handler
* Adds new 'forge' sub-command
* Performance improvements for large codebases