Updating NodeTool replaces the program and leaves your data directory in place. On start, the server applies any database migrations the new version needs. Back up before you update, because a migration cannot be undone by installing the old version.
Back up first
Stop NodeTool, then copy the data. The desktop app and a local server keep these in the data directory.
| What | Where |
|---|---|
| Database | nodetool.sqlite3, plus nodetool.sqlite3-wal and nodetool.sqlite3-shm if they exist |
| Assets | assets/ |
| Vector store | vectorstore.db |
| App settings | settings.yaml in ~/.config/nodetool/ on macOS and Linux, or in %APPDATA%\nodetool\ on Windows |
| Vaults (desktop) | vaults/<id>/ |
The data directory is ~/.local/share/nodetool/ on macOS and Linux (or $XDG_DATA_HOME/nodetool/) and %APPDATA%\nodetool\ on Windows. Vaults sit under ~/.local/share/nodetool/vaults/ on macOS and Linux and %LOCALAPPDATA%\nodetool\vaults\ on Windows. See Where your data lives for the full table.
Stored provider keys are in the database, encrypted with a master key. The master key is in your operating system keychain unless SECRETS_MASTER_KEY is set. A database restored on another machine decrypts only where the master key has the same value, so keep a copy of SECRETS_MASTER_KEY if you set one. See Secret Storage and Master Key.
Export the workflows you cannot afford to lose as a second copy. The API serves a .nodetool bundle at GET /api/workflows/{id}/export-bundle. See API Reference.
Desktop app
Turn on automatic updates
Automatic Updates is off by default. With it off, the app does not check for updates at all.
- Open Settings.
- In General → Workspace, find Updates.
- Turn on Automatic Updates.
- Choose an Update Channel.
Auto-update runs only in installed builds, not in a development checkout. The app reads releases from the nodetool-ai/nodetool GitHub repository. It checks when it starts.
Update channels
| Channel | Follows |
|---|---|
| Stable | Full releases |
| Nightly | Prerelease nightly builds, published daily |
A build whose version ends in -nightly.<date>.<n> starts on Nightly. Any other build starts on Stable. Your own choice in Settings overrides that default. The updater allows downgrades, so moving from Nightly to Stable can install an older build.
What you see
When a newer version exists, the app downloads it in the background. A card at the top right of the main window reads “Version X is available. Downloading in the background…” with a View Release Notes link. When the download finishes the card reads “Version X has been downloaded and will be installed on restart.” with a Restart to Update button. A system notification appears for both events. See Update Notification.
If the app logs that app-update.yml is missing, you have an older installation. Reinstall from GitHub releases to enable auto-updates.
Update by hand
Download the current installer from nodetool.ai or from GitHub releases, and install it over the existing app. Your data directory stays. See Installation.
Node packs and runtimes
Node packs and runtime packages update separately, from Tools → Package Manager. See Node Packs.
Command line
If you installed the nodetool command with npm, install it again:
npm install -g @nodetool-ai/cli
Self-hosted Docker
The reference docker-compose.yml pulls ghcr.io/nodetool-ai/nodetool:${NODETOOL_VERSION:-latest}. All state lives under /workspace on the nodetool-data volume, so it survives an image upgrade.
Choose a tag
| Tag | Meaning |
|---|---|
latest |
The newest build of main |
1.2.3, 1.2, 1 |
A release, published when a v1.2.3 git tag is pushed |
main-<shortsha> |
A specific commit on main |
In production, pin a release with NODETOOL_VERSION in .env so an upgrade happens when you choose it. Set NODETOOL_IMAGE to run an image you built yourself.
Back up the volume
Stop the server, then archive the volume. With the compose project name nodetool, the volume is nodetool_nodetool-data:
docker compose down
docker run --rm -v nodetool_nodetool-data:/workspace -v "$PWD":/backup \
alpine tar czf /backup/nodetool-data.tgz -C /workspace .
The archive includes /workspace/.secrets_master_key if the entrypoint generated your master key. Keep that file with the backup. If you use PostgreSQL, take the dump with your own PostgreSQL tools.
Upgrade
docker compose pull
docker compose up -d
Check that the server is healthy at http://localhost:17777/health (or your NODETOOL_PORT). See Self-Hosted Deployment.
Roll back
Set NODETOOL_VERSION to the previous tag and run docker compose up -d. If the newer version applied a migration, restore the volume backup first, because the older image may not understand the migrated database. This is advice from how migrations work and not a tested guarantee.
Database migrations on start
| Database | When migrations run |
|---|---|
| SQLite (desktop app, local server, and the default Docker setup) | Every time the server starts. It applies pending migrations before it opens the database and logs the versions it applied |
| PostgreSQL or Supabase in Docker | The image entrypoint runs db-migrate.mjs on every start when DATABASE_URL is set. Set NODETOOL_MIGRATE_ON_BOOT=0 if a release step migrates instead |
For PostgreSQL or Supabase you can also run migrations yourself:
nodetool db status --direct-url "$DIRECT_URL"
nodetool db migrate --direct-url "$DIRECT_URL" --dry-run
nodetool db migrate --direct-url "$DIRECT_URL"
nodetool db rollback --steps <n> rolls PostgreSQL or Supabase migrations back. See CLI Reference. For a rolling release across replicas, migrations run once before either replica changes, so they must work with the previous image. See Docker Production Deploy.
Related pages
- Changelog for what changed in recent releases
- Desktop App for settings and data locations
- Self-Hosted Deployment for Docker setup
- Configuration for storage and secrets variables