Self-Updates & Versioning

Eliza includes a built-in update system inherited from the elizaOS framework. It checks the npm registry for new versions, notifies users of available updates, and can perform in-place upgrades across multiple installation methods. The system is implemented across three service modules: update-checker.ts (registry communication), update-notifier.ts (background notifications), and self-updater.ts (install-method detection and upgrade execution).

How It Works Internally

The update system has three layers that work together:

Version Resolution

The current Eliza version is resolved at import time via the version module, which calls resolveElizaVersion(). This function checks, in order:

1. A build-time injected define or environment variable (for bundled/embedded builds)
2. The version field from the nearest package.json
3. A build-info.json fallback generated during the build process

This version string is used as the baseline for all update comparisons.

Registry Queries

The update checker (@elizaos/agent/services/update-checker.ts) fetches version metadata from the npm registry using the abbreviated metadata endpoint:

GET https://registry.npmjs.org/elizaos
Accept: application/vnd.npm.install-v1+json

Eliza inherits its update system from the elizaOS framework, so the checker queries the upstream elizaos npm package. The application/vnd.npm.install-v1+json accept header requests only the abbreviated package metadata (dist-tags, versions), rather than the full document with all tarball URLs and readmes. This keeps the response small and fast.

The response's dist-tags object maps npm dist-tag names to version strings:

{
  "dist-tags": {
    "latest": "2.0.0",
    "beta": "2.1.0-beta.3",
    "nightly": "2.1.0-nightly.20260218"
  }
}

Semver Comparison

Version comparison uses the compareSemver() utility from src/services/version-compat.ts. This function returns:

• A negative number if the current version is older than the registry version (update available)
• Zero if they are equal
• A positive number if the current version is newer
• null if either version string is not valid semver

Pre-release tags (e.g., 2.0.0-alpha.87) are handled correctly per the semver specification.

Release Channels

Eliza supports three release channels, each mapped to an npm dist-tag:

Channel Resolution Order

The effective release channel is resolved by resolveChannel() in this priority order:

1. ELIZA_UPDATE_CHANNEL environment variable (if set to stable, beta, or nightly)
2. update.channel field in eliza.json configuration
3. Default: stable

The environment variable value is trimmed and lowercased before comparison. Invalid values are ignored, falling through to the config or default.

Update Checking

Automatic Background Check

On every CLI startup, the scheduleUpdateNotification() function fires a background update check. This is a fire-and-forget operation that does not block CLI startup. If a newer version is available, a styled one-line notice is printed to stderr:

Update available: 1.2.0 -> 1.3.0
Run eliza update to install

The notification uses the terminal theme for coloring: the current version is dimmed, the new version is highlighted in green, and the channel suffix (for non-stable channels) is shown in parentheses.

The background check is skipped when:

• update.checkOnStart is set to false in the config
• Running in CI (process.env.CI is set)
• stderr is not a TTY (non-interactive environments)
• The check interval has not elapsed since the last check
• The notifier has already run in this process (singleton guard)

If the config file is malformed or unreadable, the notifier falls back to defaults and continues rather than crashing.

Check Interval

The update checker respects a configurable interval to avoid excessive registry requests:

When the interval has not elapsed, the shouldSkipCheck() function returns true and the checker returns a cached result based on lastCheckVersion without contacting the registry. This cached result still performs a semver comparison against the current version, so the updateAvailable field is accurate even without a network call.

Registry Communication

The update checker fetches dist-tags from the npm registry:

GET https://registry.npmjs.org/elizaos
Accept: application/vnd.npm.install-v1+json

• Timeout: 8 seconds (via AbortController)
• On network failure: Returns { updateAvailable: false, error: "Unable to reach the npm registry..." }
• On non-OK HTTP response: Returns null dist-tags (treated as network failure)
• On missing dist-tag: Returns an error indicating the channel has no published releases

After a successful fetch, the checker persists the check metadata (lastCheckAt, lastCheckVersion) to eliza.json. If the config file is unwritable, a warning is printed to stderr but the check result is still returned.

Fetching All Channel Versions

The fetchAllChannelVersions() function queries the registry once and returns the latest version for every channel:

{
  stable: "2.0.0",
  beta: "2.1.0-beta.3",
  nightly: "2.1.0-nightly.20260218"
}

This is used by the eliza update status command to display a complete version overview.

CLI Commands

eliza update

Check for and install updates on the current channel:

eliza update

# Check only, don't install
eliza update --check

# Switch to beta channel and update
eliza update --channel beta

# Force a fresh registry check
eliza update --force
```

When --channel is specified, the command:

1. Validates the channel name (exits with an error if invalid)
2. Saves the new channel to eliza.json
3. Clears lastCheckAt and lastCheckVersion to force a fresh registry check
4. Proceeds with the update check using the new channel

eliza update status

Display the current version, install method, active channel, and available versions across all channels:

eliza update status

Example output:

Version Status

  Installed:  1.2.0
  Channel:    stable
  Install:    npm-global
  Authority:  package-manager
  Next:       run-package-manager-command
  Command:    npm install -g elizaos@latest
  Can run:    yes

Available Versions

  stable                 1.3.0 <-- current
  beta                   1.4.0-beta.2
  nightly                1.4.0-nightly.20260218

  Last checked: 2/19/2026, 10:30:00 AM

The status command fetches live data from the npm registry (not cached) to show the most current versions across all channels.

The Authority and Next fields make the update owner explicit:

eliza update channel [name]

View or change the release channel:

eliza update channel beta

eliza update channel nightly

eliza update channel stable

When viewing (no argument), the command displays:

• The current active channel with its description
• All available channels with descriptions
• A hint about how to switch

When switching channels, the cached lastCheckAt and lastCheckVersion are cleared to force a fresh check on the next update. This ensures the user sees the correct latest version for their new channel immediately.

Installation Method Detection

Eliza automatically detects how it was installed to determine the correct update command. The detectInstallMethod() function works by:

1. Running which eliza to find the binary path (5-second timeout)
2. Resolving symlinks via fs.realpathSync() to get the true filesystem location
3. Checking the resolved path against heuristic patterns

If which eliza returns nothing (binary not in PATH), the detection falls back to checking whether the current directory is a local development checkout (by looking for devDependencies in the root package.json).

Snap Channel Mapping

Update Command Construction

The buildUpdateCommand() function takes the detected install method and target channel, then returns the appropriate shell command and arguments. For npm and bun installs, the version specifier uses the channel's dist-tag:

elizaos@latest     (stable channel)
elizaos@beta       (beta channel)
elizaos@nightly    (nightly channel)

For Homebrew, the command is simply brew upgrade eliza (Homebrew manages version resolution internally). The apt case wraps the update in sh -c since it requires two sequential commands.

For local-dev installs, buildUpdateCommand() returns null and the CLI prints a message directing the user to use git pull instead.

getUpdateActionPlan() wraps the detected method and command in status metadata used by both the CLI and REST API:

Remote REST status responses are display-only. They can show the command that should be run on the host, but Eliza intentionally does not provide a remote update execution endpoint.

Update Process

When eliza update runs (without --check), the following steps occur:

Post-Update Verification

After the update command completes, the updater verifies the installation by running the CLI with --version and parsing the output. The regex (\d+\.\d+\.\d+(?:-[\w.]+)?) handles both stable versions (e.g., 2.0.0) and pre-release tags (e.g., 2.1.0-beta.3).

If the version cannot be read (e.g., the binary is missing or corrupted), the command reports success for the update itself but warns that it could not verify the new version.

What Gets Updated

The eliza update command updates the CLI package itself, which includes:

Core elizaOS plugins (@elizaos/plugin-*) are resolved from node_modules at runtime. When you update Eliza and the new version specifies different plugin versions in its dependencies, those plugins are updated as part of the npm/bun install process.

Version Pinning

To pin Eliza to a specific version and prevent automatic updates:

# Install a specific version
npm install -g [email protected]

# Disable automatic update checks by editing eliza.json
# Set "update": { "checkOnStart": false } in your config file
$EDITOR "$(eliza config path)"

For package-manager-specific pinning:

# npm: exact version
npm install -g [email protected]

# bun: exact version
bun install -g [email protected]

The --force flag on eliza update bypasses the interval cache but still respects the configured channel. It does not bypass version pinning at the package manager level.

Rollback

Eliza does not have a built-in rollback command, but you can revert to a previous version using your package manager:

# npm: install a specific older version
npm install -g [email protected]

# bun: install a specific older version
bun install -g [email protected]

# Verify the rollback
eliza --version

Your configuration, database, and workspace files are preserved across version changes. However, be aware that:

• Database migrations may have run forward during the newer version. Downgrading could leave the database in an incompatible state. Eliza's PGLite recovery mechanism will attempt to reset and rebuild the database if it detects corruption.
• Config schema changes are forward-compatible (unknown fields produce warnings but don't prevent startup), but a much older version may not understand newer config sections.

Update Notifications

Notification Format

The background update notification writes to stderr (not stdout) to avoid interfering with piped output:

Update available: 2.0.0-alpha.26 -> 2.0.0
Run eliza update to install

For non-stable channels, the channel name is appended:

Update available: 2.0.0-alpha.26 -> 2.1.0-beta.3 (beta)
Run eliza update to install

Suppressing Notifications

Notifications can be suppressed through multiple mechanisms:

Offline and Air-Gapped Environments

In environments without internet access:

• The background update check times out after 8 seconds and returns { updateAvailable: false } with an error message. No notification is shown.
• eliza update --check reports the network error and exits with code 1.
• eliza update reports the error and exits with code 1.
• The check interval cache is not updated on failure, so the next startup will try again.

For fully air-gapped deployments, disable the update check entirely:

{
  "update": {
    "checkOnStart": false
  }
}

Or set via the CLI (open config in your editor):

$EDITOR "$(eliza config path)"
# Set "update": { "checkOnStart": false }

To perform offline updates, download the package tarball on a connected machine and install it locally:

# On a connected machine
npm pack [email protected]

# Transfer elizaai-2.0.0.tgz to the air-gapped machine, then:
npm install -g ./elizaai-2.0.0.tgz

Configuration Reference

All update-related settings are stored in the update section of eliza.json:

{
  "update": {
    "channel": "stable",
    "checkOnStart": true,
    "checkIntervalSeconds": 14400,
    "lastCheckAt": "2026-02-19T10:30:00.000Z",
    "lastCheckVersion": "1.3.0"
  }
}

Environment Variables

Breaking Change Handling

When a new Eliza version introduces breaking changes:

• Database schema -- Eliza sets ELIZA_ALLOW_DESTRUCTIVE_MIGRATIONS=true by default, allowing the migration system to drop and recreate tables that have changed between plugin versions. This prevents the runtime from stalling on schema mismatches.
• PGLite corruption -- If the local database becomes incompatible after an update, the isRecoverablePgliteInitError() detection backs up the corrupt data directory (to <dir>.corrupt-<timestamp>) and creates a fresh database. This means conversation history may be lost, but the agent will start successfully.
• Config file -- The config schema is forward-compatible. Unknown fields produce warnings but do not prevent startup. The config file tracks which Eliza version last wrote it.
• Plugin API -- Version skew between @elizaos/core and plugins is detected by version-compat.ts, which checks for missing exports and produces diagnostic messages.

Plugin Version Compatibility

The version compatibility module maintains a map of critical exports and the core version that introduced them. When plugins fail to load, the diagnoseNoAIProvider() function checks whether the failure is due to version skew and produces actionable error messages like:

No AI model provider loaded. This may be caused by a version mismatch
between @elizaos/core and your model provider plugins.

This helps users understand that they may need to update their plugins alongside the CLI, or pin to a compatible version combination.

Electrobun Desktop Updates

The Electrobun desktop app (apps/app/electrobun/) uses the Electrobun updater for native auto-update support, which is separate from the CLI update system. Desktop updates are delivered through platform-native mechanisms (DMG on macOS, NSIS on Windows, AppImage on Linux) and handled by the Electrobun shell rather than the npm registry.