Back Up and Restore - Inktomi93/OrbWeaver GitHub Wiki

Your library, accounts and saved keys all live in one folder on your machine, so a backup is a copy. There's also an export button in the app for moving your library. Different jobs, so pick the right one. Back up before a big update.

The data folder is data/ inside your Orbweaver folder, or wherever DATA_DIR points if you changed it. In Docker it is the orbweaver-data volume.

Back up everything except cache/.

Your port and sign-in choice are not in the data folder. They live in the .env file in your Orbweaver folder (in Docker, docker/orbweaver.local.env), so copy that too if you want the same setup.

The secrets folder travels with the database. secrets/credentials_key decrypts the model keys you saved in Orbweaver. secrets/session_secret is what passwords, sign-ins and invite links are checked against. A database restored without them cannot read its saved keys or sign anyone in. If the database holds saved keys, passwords or sign-ins and the matching file is missing, Orbweaver refuses to start and names the file rather than quietly generating a new one. Keep the two together, and treat the backup as private because it contains them.

Stop Orbweaver first. The database is live while the app runs, and a copy taken mid-write can be broken. Press Ctrl-C if you started it in a terminal, or run docker compose stop for Docker. Copy the folder, then start it again.

Orbweaver's compose file keeps the data in a named volume. With the app stopped, this writes the whole volume to orbweaver-data.tgz in your current folder. The archive is owned by you and readable by you only, because it holds the secrets:

docker run --rm -v orbweaver_orbweaver-data:/data -v "$PWD":/out alpine sh -c 'umask 077 && tar czf /out/orbweaver-data.tgz -C /data . && chown "$(stat -c %u:%g /out)" /out/orbweaver-data.tgz'

The volume name is the compose project name plus orbweaver-data. The shipped compose file names the project orbweaver, so the volume is orbweaver_orbweaver-data wherever you started it. If you changed the project name (with -p or COMPOSE_PROJECT_NAME), check docker volume ls. Switching the volume line in the compose file to ./data:/app/data gives you a plain folder you can copy like any other.

docker compose down keeps the volume. docker compose down -v deletes it, and your library with it.

Open Settings, then Backup & Restore, then Export. Tick what you want and press Download my library to get one zip.

• In it: characters, the chats you host (with their game state), personas, world info, regex scripts, databank documents, presets, themes, tags, gallery, image generation history, and a share-safe part of your settings (looks, chat, persona, world info and memory). Media always travels with them.
• Not in it: anything not listed above, including model connections and saved keys, model roles, accounts and passwords, and plugins. Memory summaries are not exported either. The Memory switch comes along with your settings. With Memory on, the import report offers Build memory for imported chats and shows the estimated model-call count before you confirm. Skip it and each chat builds its memory at its next reply. You can also run Memory backfill from Jobs. Summaries run on your Utility model, so connect one before starting that work.
• Whose library: the account you are signed in as. On a shared install, each person exports their own.

Keep Image generation history selected if you want your generated pictures' recorded details to travel. The export does not preserve embedding or compaction spend history. See Stats and Insights for the accounting limits.

The zip carries no credentials, but it does hold your chats and personas, so treat it as private. It also cannot restore a lost install on its own. You will connect your models again afterward (Connect a model).

From a data folder copy. Stop Orbweaver, put the copied folders back in the data folder (secrets/ included), and start it. If you are replacing a library that is already there, empty db/ first so no old -wal or -shm file is left beside the restored database. A data folder from an older install is rearranged into the current layout on the first start, and the log says what moved. Any built-in models in cache/ download again in the background.

For a Docker volume, stop the container and unpack the archive into an empty volume:

docker run --rm -v orbweaver_orbweaver-data:/data -v "$PWD":/in alpine tar xzf /in/orbweaver-data.tgz -C /data

From an export zip. Open Settings, Backup & Restore, Import, and drop the zip. You can also pick an unzipped folder. Orbweaver tells you what it will do before it starts: importing adds to your library and never updates or deletes what you have, anything already there is skipped, a world book, theme, preset or persona that shares a name with a different one of yours lands beside it under a numbered name, and the backup's settings merge into yours. When it finishes it reports anything it skipped. The same page brings in a SillyTavern library, which Coming from SillyTavern walks through.

Orbweaver upgrades its database when it starts. Before a start that is going to change the database, it copies the database into backups/ as orbweaver.db.backup-<timestamp>, upgrades it, checks the upgraded database, and trims old copies. A start that changes nothing makes no copy. To keep a particular copy from being trimmed, create an empty file beside it with the same name plus .keep.

Upgrades only go forward, so there is no undo button. To go back:

1. Stop Orbweaver.
2. Replace db/orbweaver.db with the backup copy you want.
3. Delete the -wal and -shm files next to it, if they exist.
4. Start the older version of Orbweaver that matches that backup.

Starting a newer version on top of the restored copy upgrades it again, as usual.

If Orbweaver won't start for some other reason, see Troubleshooting.