VT Code Update System Guide

March 18, 2026 ยท View on GitHub

This guide covers VT Code's update system, including release channels, version pinning, and configuration options.

Overview

VT Code includes a built-in update system that can check for and install updates from GitHub Releases. The system supports:

  • Multiple release channels (stable, beta, nightly)
  • Version pinning for staying on specific versions
  • Configurable update behavior via ~/.vtcode/update.toml
  • Download mirrors for better availability

Quick Start

Check for Updates

# Check and install updates
vtcode update

# Check only (don't install)
vtcode update --check

List Available Versions

# List recent versions
vtcode update --list

# List more versions
vtcode update --list --limit 20

Pin to a Specific Version

# Pin to a specific version
vtcode update --pin 0.85.3

# Unpin and resume following the channel
vtcode update --unpin

Release Channels

# Switch to beta channel
vtcode update --channel beta

# Switch to nightly channel
vtcode update --channel nightly

# Back to stable
vtcode update --channel stable

View Configuration

# Show current update configuration
vtcode update --show-config

Release Channels

VT Code follows three release channels:

Stable (Default)

  • Purpose: Production-ready releases
  • Update frequency: Every 2-4 weeks
  • Recommended for: Most users, production environments
  • Quality: Fully tested and validated
# ~/.vtcode/update.toml
channel = "stable"

Beta

  • Purpose: Pre-release testing
  • Update frequency: Weekly
  • Recommended for: Early adopters, testing new features
  • Quality: Feature-complete, minor bugs possible
# ~/.vtcode/update.toml
channel = "beta"

Nightly

  • Purpose: Bleeding edge builds
  • Update frequency: Daily (automated builds)
  • Recommended for: Contributors, extreme early adopters
  • Quality: May contain bugs, rapid iteration
# ~/.vtcode/update.toml
channel = "nightly"

Version Pinning

Version pinning allows you to stay on a specific version, disabling automatic updates until you unpin.

When to Pin

  • Waiting for a bug fix in the next release
  • Stability requirements for production
  • Testing compatibility with specific version
  • Avoiding a problematic release

Pin to a Version

vtcode update --pin 0.85.3

This creates/updates ~/.vtcode/update.toml:

[pin]
version = "0.85.3"

Unpin

vtcode update --unpin

Configuration File

Location: ~/.vtcode/update.toml

Example Configuration

# VT Code Update Configuration

# Release channel to follow
# Options: stable (default), beta, nightly
channel = "stable"

# Version pinning (optional)
# Uncomment to pin to a specific version
# [pin]
# version = "0.85.3"
# reason = "Waiting for bug fix in next release"
# auto_unpin = false

# Download mirrors (optional)
# [mirrors]
# primary = "https://github.com/vinhnx/vtcode/releases"
# fallbacks = [
#     "https://mirror.example.com/vtcode",
# ]
# geo_select = true

# Auto-update check interval in hours (0 = disable)
check_interval_hours = 24

# Download timeout in seconds
download_timeout_secs = 300

# Keep backup of previous version after update
keep_backup = true

# Auto-rollback on startup if new version fails
auto_rollback = false

Configuration Options

OptionTypeDefaultDescription
channelString"stable"Release channel: stable, beta, or nightly
pin.versionStringnullPinned version (null = follow channel)
pin.reasonStringnullUser note for pinning
pin.auto_unpinBooleanfalseAuto-remove pin after successful update
mirrors.primaryStringGitHubPrimary download mirror URL
mirrors.fallbacksArray[]Fallback mirror URLs
mirrors.geo_selectBooleantrueEnable geographic mirror selection
check_interval_hoursInteger24Hours between update checks (0 = disable)
download_timeout_secsInteger300Download timeout in seconds
keep_backupBooleantrueKeep backup of previous version
auto_rollbackBooleanfalseAuto-rollback on startup failure

CLI Reference

vtcode update

Check for and install updates.

Options:

  • --check - Check only, don't install
  • --force - Force reinstall even if up-to-date
  • --list - List available versions
  • --limit <N> - Number of versions to list (default: 10)
  • --pin <VERSION> - Pin to specific version
  • --unpin - Remove version pin
  • --channel <CHANNEL> - Set release channel
  • --show-config - Show current configuration

Examples:

# Check and install
vtcode update

# Check only
vtcode update --check

# List versions
vtcode update --list

# Pin version
vtcode update --pin 0.85.3

# Switch to beta
vtcode update --channel beta

Update Behavior

Managed Installs

If VT Code was installed via a package manager, the update system will detect this and provide the appropriate update command:

  • Homebrew: brew upgrade vtcode
  • Cargo: cargo install vtcode --force
  • npm: npm install -g @vinhnx/vtcode@latest --registry=https://npm.pkg.github.com
  • Standalone: Direct update via vtcode update

Backup and Rollback

When keep_backup = true (default), the previous version is kept after update. If auto_rollback = true, VT Code will automatically revert to the backup if the new version fails to start.

Update Checks

By default, VT Code checks for updates every 24 hours. The check timestamp is cached in ~/.cache/vtcode/last_update_check.

To disable automatic checks:

check_interval_hours = 0

Troubleshooting

Update Fails to Download

  1. Check internet connectivity
  2. Try a different mirror: 
    [mirrors]
primary = "https://mirror.example.com/vtcode"
  3. Increase timeout: 
    download_timeout_secs = 600

Binary Permissions Issues

On Unix systems, ensure the binary has execute permissions:

chmod +x ~/.local/bin/vtcode

Rollback to Previous Version

If an update causes issues:

  1. Manual rollback: Download previous version from GitHub Releases
  2. Auto-rollback: If enabled, happens automatically on startup failure 
    auto_rollback = true

Check Current Version

vtcode --version

Force Update

If you suspect corruption:

vtcode update --force

Integration with CI/CD

For automated environments, you can:

  1. Pin versions to ensure consistency:

    vtcode update --pin 0.85.3

  2. Disable auto-checks:

    check_interval_hours = 0

  3. Use specific channels for testing:

    channel = "beta"

Security Considerations

  • Updates are downloaded from GitHub Releases over HTTPS
  • Binary signatures are verified automatically
  • Backup versions are kept for rollback safety
  • Configuration file is user-controlled (~/.vtcode/update.toml)