Skip to content

Migrating from EctoLedger

EctoSpace edited this page Nov 13, 2026 · 1 revision

Migrating from EctoLedger

IronVise is the new name for EctoLedger. Version 0.8.0 is the first release since EctoLedger 0.6.3. Your ledgers, signing keys, data directories, environment variables and signed formats stay compatible. What changes is the names you type: the CLI executable, the SDK imports, the container image and the desktop app. The authoritative reference is docs/reference/compatibility.md.

What is renamed

Was (EctoLedger 0.6.3) Now (IronVise 0.8)
ectoledger CLI executable and Windows launcher ironvise (and ironvise-win.ps1 on Windows). The old executable is not shipped.
Python ectoledger-sdk, import ectoledger_sdk PyPI ironvise, import ironvise_sdk
npm ectoledger-sdk, EctoLedgerClient npm ironvise, IronViseClient, IronViseApiError, IronViseUsageError
Image ghcr.io/ectospace/ectoledger ghcr.io/ectospace/ironvise; compose service ironvise. Images up to 0.6.3 stay at the old name.
Desktop app EctoLedger IronVise, executable ironvise-gui
Linux package ecto-ledger iron-vise (declares Replaces, Conflicts and Provides for ecto-ledger)
LLM_BACKEND LLM_PROVIDER. LLM_BACKEND still works as an alias.
Contact address ironvise@ectospace.com

What is kept, deliberately

These names keep their EctoLedger spelling so that nothing has to move:

What Kept as
Data directory .ectoledger/ (the default of ECTO_DATA_DIR)
Desktop ledger file ectoledger.db in the app data folder
Desktop app data folder io.ectoledger.agent-ledger (the bundle identifier) on macOS, Windows and Linux
Environment variables Every ECTOLEDGER_* and ECTO_* variable, DATABASE_URL, and the others
Signing keys keys/session-<session id>.key in the data directory, same passwords
Credential store Existing keyring services and stored provider keys
Rust package and crates ectoledger, ectoledger_*, ectoledger-* (run from a clone with cargo run -p ectoledger --bin ironvise)
Certificates and signatures .elc, schema fields, signing bytes, hashes, VC types and proof formats
Webhooks and SIEM Header names (X-EctoLedger-*), HMAC domain separators, CEF/LEEF vendor identifiers
Agent hooks Existing hooks are recognised; ironvise hook install replaces the old command instead of adding a duplicate

No key rotation, certificate conversion, signature format change or data-path migration is needed for the rename.

Upgrade steps

  1. Back up the database and the signing keys together: the ledger (ectoledger.db or your PostgreSQL database) and the data directory (.ectoledger/, or the desktop app data folder).

  2. Stop the old application. Do not run both versions against the same ledger.

  3. Install IronVise 0.8 (see Getting Started).

  4. Update scripts and imports:

    • ectoledger <cmd> becomes ironvise <cmd>
    • Python: python -m pip uninstall ectoledger-sdk, then pip install "ironvise>=0.8.0", and change ectoledger_sdk to ironvise_sdk
    • TypeScript: npm install ironvise@^0.8.0, and use IronViseClient
    • Docker: ghcr.io/ectospace/ironvise
  5. Start IronVise with the same working directory and configuration. Existing database migrations run as before.

  6. Verify the whole ledger. Verification in 0.8 is stricter than in earlier releases:

    ironvise verify-ledger --all --strict

Keep the previous binary and the backup for recovery. Do not downgrade a database that 0.8 has already migrated without checking migration compatibility. Never delete an old data directory to fix an upgrade problem.

Signing keys from 0.6.3

A key file written by 0.6.3 opens with the same password (ECTO_KEY_PASSWORD, --key-password-fd, or the prompt). After it opens, 0.8 rewrites it in the current format and keeps the original beside it as session-<session id>.key.v063.bak. The Ed25519 key itself does not change.

Desktop app

  • macOS: install IronVise, then remove the old EctoLedger.app. Keep the data folder ~/Library/Application Support/io.ectoledger.agent-ledger.
  • Windows: the .msi keeps the same upgrade code. The .msi and .exe install the desktop app only and do not put ironvise on PATH; the CLI is the ironvise-x86_64-pc-windows-msvc.zip release archive.
  • Linux: installing iron-vise removes ecto-ledger. The data folder ~/.local/share/io.ectoledger.agent-ledger is not moved or deleted.

The desktop identity is unchanged, but that alone does not guarantee every installer replaces the old application in place. Check that only one copy remains after upgrading.

If the app shows "IronVise could not open its ledger", your data has not been changed. Keep the file and report the message with the version you upgraded from.

SDK changes beyond the rename

  • Python LangChain: LedgerTool is removed; use the fail-closed LedgerCallbackHandler.
  • Python AutoGen: LedgerHook.attach() (AutoGen 0.2) is gone; use LedgerHook.wrap_tools() with autogen-agentchat 0.4 or newer.
  • Both SDKs add verify_intent / verifyIntent. See SDKs.

Other removals in 0.8

  • prove-audit (SP1 proving) is unavailable because of an upstream security advisory. Export .elc certificates instead.
  • EVM anchoring is removed. anchor-session --chain accepts only bitcoin (OpenTimestamps).
  • audit --auto-anchor-interval and --auto-anchor-chain are removed.

The full list is in the CHANGELOG.

Clone this wiki locally