EKOSdocs
Docs / Operations Operate

Upgrades

Upgrading the binary, the console, the storage format and cached compilation output.

  1. Read the release notes and newest devlogs for changes that affect your workspace.
  2. Take a backup (ekos home backup). For the console there is no downgrade.
  3. Install the new version — the installer or package, or for the container git pull (or a new image tag) and docker compose -f deploy/docker-compose.yml up -d --build. Keep the old binary until you have verified.
  4. Run ekos doctor and ekos config validate — unknown config sections are rejected.
  5. The console upgrades its own database when it starts.
  6. Re-running the pipeline is not needed for an upgrade; it is how new compiler features reach an existing project. The build fingerprint includes the pipeline's logic version, so changed analyzers reprocess automatically; no manual .ekos wipe is needed. For a project with model-backed passes a re-run costs money.
  7. If a read-only client (MCP server) reports a stale search index, run ekos ledger repair once.

Search index format

From RFC 0229 (tantivy 0.27) the search index is written in a newer format. A newer EKOS reads an older index as it is; an older EKOS cannot read an index a newer one wrote, and runs without search (it says so) until the index is rebuilt. To go back, restore the backup.

Storage format migration

From To Command
SQLite v1 v2 compact ekos ledger migrate
SQLite fact engine (v3) ekos ledger migrate --v3

An existing SQLite workspace is never migrated automatically. Migrate a copy first and compare ekos status before and after.

Cached output

A CompilerPass skipped as cached uses its version and inputs. If an upgrade changes a pass without bumping its version, clear with ekos clean and rebuild.