Upgrading to 2.0

Before 2.0, a SynapseOrch install kept its workflows, agents, custom tools, MCP servers and settings as JSON files under a data directory. 2.0 keeps them in a database.

How your data comes across depends on how you installed 1.x.

Installed with the script, npm or pip

Run the install command again. On an install made with the 1.x script, its own synapse upgrade hands over to it too; on an npm install, so does npm install -g synapse-orch-ai@latest followed by synapse.

It finds your 1.x install — the script's folder (~/.local/share/SynapseAI on Linux, ~/Library/Application Support/SynapseAI on macOS, %LOCALAPPDATA%\Programs\SynapseAI on Windows), a pip install on your path, or npm's — and asks first:

Found Synapse 1.9.1 in ~/.local/share/SynapseAI
7 agents · 4 orchestrations · 312 chats

Not now changes nothing. Upgrade then:

1. Stops 1.x, and its start-on-login entry.
2. Backs up its data, logs and .env to ~/.synapse/backups/synapse-<version>-<time>.tar.gz, after checking there is room, and reads the archive back.
3. Installs 2.0 — Python, the program, Node.js and the browser.
4. Moves your data — your .env's secrets, tokens and ports into ~/.synapse/.env, and everything else into the database, before 2.0 starts for the first time.
5. Sets up — your model and keys come across with your data, so it asks nothing about the AI.
6. Starts 2.0.
7. Removes the old install — its folder, and the lines on your path that named it.

If a step fails before your data moves, 1.x and its data are untouched; run the command again. The upgrade of a pip install is best done this way too: pip install --upgrade upgrades the program but makes no backup; 2.0's first start in a terminal then brings the 1.x data across before anything is asked, so nothing 1.x answered is asked again.

What comes across

Agents, workflows, custom tools, MCP servers, schedules and settings; chats; API keys, which keep working; usage records and model prices; code repositories, database connections and messaging channels; your personal details; MCP and Google sign-ins; the vault's files, datasets and WhatsApp sessions; and run logs.

What does not

• A 1.9 scale mode Postgres database. Start 2.0 on a fresh one and move your workflows with Import/Export.
• An npm 1.x install's chats and logs: they lived inside the npm package, which npm itself replaced when it updated.
• memory/memory.jsonl, the ChromaDB index, caches and google-credentials/.

If something was missed

synapse migrate --from <folder> imports a 1.x data folder into a database that already holds data — see below. The upgrade deletes the old install's folder at the end, so take the folder out of the backup archive first.

Nothing undoes an upgrade automatically. The archive holds the 1.x data, logs and .env, with a manifest.json naming where each came from; going back means reinstalling 1.x and putting them back.

Docker, Compose and source checkouts

The import runs when 2.0 starts:

1. SynapseOrch looks for 1.x data in SYNAPSE_DATA_DIR if it is set, in backend/data beside the code, and in ~/.synapse/data, and imports every one that holds any. Where two hold the same item, the first in that order wins.
2. It imports only while the database holds nothing of yours — what SynapseOrch creates for itself, such as the builder's agents, does not count.
3. Each imported folder is renamed to data.migrated/ (or data.migrated.<time>, if that exists). A folder that 2.0 also uses — the Docker /data volume, which holds the new database — or a mounted folder keeps its place, and the imported files move into a migrated/ folder inside it.

The rename does two jobs. It is what stops the import running a second time, and it means your original files are still there if something did not come across. Nothing is deleted.

The import does nothing at all when the store already holds data, so it is safe on every boot and cannot overwrite work you have done since. Settings do not count as data here: a setting already in the database — one you set with synapse setup before the first start, say — is kept, and the 1.x file fills in only what is missing.

A 1.x Docker container upgrades with the same volume — see Docker. The Compose file imports ./backend/data on its first boot, and its files move to ./backend/data/migrated/.

What changed, and why

DATA_DIR conflated three different things: documents, tenant content, and directories that genuinely need a filesystem. Each now has a home.

By default they live under ~/.synapse/var/ in an installed SynapseOrch ($SYNAPSE_HOME/var), under backend/var/ in a source checkout, and under /data in the single-container Docker image. See the CLI.

One constant meaning all three is what made the engine something you installed on a laptop rather than something a request could be served by. See Environment variables.

Things that are no longer true

If you have scripts, runbooks or notes from 1.x, check these:

• There is no settings.json. Settings are rows. Editing a file changes nothing — use Settings or the API.
• Provider keys are not environment variables. OPENAI_API_KEY, ANTHROPIC_API_KEY and the SYNAPSE_SETTING_* overlay are no longer read. Keys live in the store and never enter the process environment.
• SYNAPSE_DATA_DIR configures nothing. It is read only to find a tree to import.
• The default backend port is 8765.
• An installed SynapseOrch lives in ~/.synapse, not in the installer's 1.x folder.

Running the migration by hand

synapse migrate creates or updates the database schema and imports old data folders if any are present — the same work the first boot does, run on demand. Reach for it when you are preparing a database before starting the service, or confirming an upgrade landed. Ordinary upgrades do not need it.

• --from <folder> imports that folder, even into a database that already holds data. Repeat it for several; where two hold the same item, the first named wins.
• --logs <folder> imports a 1.x logs folder as well.
• --json prints one report, and the command exits with 1 if anything failed.

Postgres

SQLite is the default and is right for a single process. Point SYNAPSE_DB_URL at Postgres when more than one process serves the same data — which is any scale mode deployment, and any install running more than one API replica.