Backup, restore, auto-update

Backups

OpenEnsemble is fully backed by files on disk — users/, config.json, messages.json, tasks/, expenses/, roles/, etc. The Backup tab packs all of them into a single tar.gz (or encrypted .oeb).

Export

Settings → Backup → Export Backup → Download. The file includes:

  • config.json and the custom-provider registry (config/user-providers.json)
  • All user dirs under users/ (which is where each user’s per-user encryption key lives, so encrypted-at-rest fields restore cleanly)
  • messages.json, threads.json, tasks/
  • Expenses, autolabel rules, sharing manifest
  • Custom skills, custom drawers, custom roles

It does not include the bundled GGUF models, your node_modules/, or anything in .git.

Password-protected backups

The Export panel has an optional Password field. If you fill it in:

  • The backup is encrypted with AES-256-GCM, with the key derived from your password using scrypt (N=2¹⁵, r=8, p=1).
  • The downloaded file is named .oeb instead of .tar.gz and is no longer a readable tarball — tar tzvf won’t work on it.
  • Restoring requires the same password (the Restore panel has a matching password field; first-run restore on a fresh install does too).
  • There is no recovery. The password is the only way in. If you forget it, the backup is unreadable.

If you leave the password field blank, the backup is plain .tar.gz exactly as before, no encryption.

Restore

Two paths:

  • Existing install — Settings → Backup → Restore Backup → upload .tar.gz or .oeb and enter its password if encrypted. Replaces current state.
  • Fresh install — on the first-run screen, click “Already have an OpenEnsemble backup?” and upload. Skips the rest of first-run.

Restore validates the archive and stages it before restarting. The launcher applies it before loading accounts, encryption keys, scheduler tasks, or other in-memory state. Users, files, and custom drawers created after the snapshot are removed from the restored data. Browser and API sessions are cleared; sign in again after restart. Paired devices reconnect through the restored device registries.

If a restore cannot finish applying, OE rolls back the changed paths and keeps the staged archive for a retry. The startup error explains the failure. Fix the storage or permission problem and start node scripts/launch.mjs again. For manual starts, npm start also uses the launcher. Keep a separate export if you want to return to the state before a successful restore.

Both plain and encrypted UI backups have a 500 MiB compressed limit and a 5 GiB restored-data limit. Export checks the limits before returning a download. Larger installations need an offline filesystem backup.

Backups contain saved configuration, credentials, and the keys needed to decrypt them. Global configuration is copied in its saved on-disk form; environment-only credentials are not included. Use a password-protected export when storing the backup somewhere untrusted. Restoring a legacy export that omitted configuration preserves non-secret destination configuration. If the destination has encrypted global credentials, use a fresh installation or create a new export, so the restore cannot pair those credentials with an unrelated encryption key.

Encryption keys

OpenEnsemble auto-generates keys for supported encrypted credential fields. Per-user keys live at users/{userId}/.master-key; global configuration uses users/_system/.master-key. Each is a 32-byte file with permissions 0600. OE manages these files automatically. They are separate from the password you choose for an encrypted backup. See Encryption and backups.

For backups specifically:

  • Default behaviour. The backup tar packs the whole users/ directory, so each user’s .master-key is included automatically. Restore on a new host gets the keys with the rest of the data and encrypted records decrypt fine — no extra steps.
  • What to be careful about. If you ever pull .master-key out of a backup manually (e.g. to share a backup without secrets), the encrypted fields in that backup become unrecoverable on the destination box. The key is not derivable from anything else.
  • File permissions. OE chmods .master-key back to 0600 on every read, so it self-heals if a restore or rsync widens the permissions.

Keep the complete backup intact so its saved credentials and keys restore together.

Software auto-update

Owner/admin sees a green Update badge in the status bar when a new commit lands on the configured git remote. Clicking it opens Settings → System → Software Update.

How it works

  1. Server polls the remote (default origin) on updateCheckIntervalMs (default 1h, minimum 60s).
  2. If new commits exist and the working tree is clean and there are no unpushed commits, the badge appears.
  3. Click Apply Update — server fast-forwards, runs npm install if package.json changed, then restarts itself.
  4. Browser reconnects automatically once the server is back.

When it refuses to update

The flow refuses to update if:

  • The working tree is dirty.
  • There are unpushed local commits.
  • The remote has been force-pushed (would require a merge).

It will never git stash or git reset --hard. Resolve those manually with git status from a terminal, then come back and click Update.

Tunables in config.json

Key Default Purpose
updateCheckEnabled true Master switch for periodic polling
updateCheckIntervalMs 3600000 Poll interval, ms (min 60000)
updateRemote origin Git remote to follow

Trust note

Auto-update means anyone with push access to your updateRemote can ship code that runs on your install. If you don’t fully trust the upstream, fork the repo and set updateRemote to your fork.

Manual restart

If you ever need to bounce the server without an update, Settings → System → Restart Server. It restarts in-place using the same detached-respawn flow as the update path. (Avoid using this mid-conversation — in-memory state like ongoing chat streams and pairing codes does not survive.)

This site uses Just the Docs, a documentation theme for Jekyll.