Updates & backups — SpaceApp Docs

Upgrades#

Preferred sequence for an authorized update:

npx --yes run-spaceapp@latest backup
npx --yes run-spaceapp@latest doctor
npx --yes run-spaceapp@latest install
npx --yes run-spaceapp@latest status

The universal install resolves the current launcher/runtime, preserves profile unless changed, checks additional disk, pulls matching images and recreates the stack. Persistent data, secrets, credentials and registered projects are retained by the supported workflow.

Before cutover, the launcher pauses writers and verifies a checkpoint. If the new runtime fails readiness after cutover, it stops writers, retains current database/volumes and reports RECOVERY_REQUIRED. It does not silently restore an older database that could discard writes accepted by the new runtime.

From 1.1.4, SpaceApp tells you when a newer release exists: the top bar shows Update available: vX, which opens the update command (npx --yes run-spaceapp@latest update) with a Copy button and a link to the release notes. Run it on the machine where SpaceApp is installed; data, settings and workspaces are kept.

Investigate the attempted version, use doctor --fix where appropriate and preserve newer data before deciding on rollback or restore. Test release changes on an owned disposable environment when possible. A successful image pull is not a successful upgrade.

Backup contents and limitations#

npx --yes run-spaceapp@latest backup

Portable backups are stored below the installation's backups directory. Documented contents:

database.dump: PostgreSQL custom-format dump.
data.tar.gz: application data, excluding separately handled memory and browser profiles.
memory.tar.gz: mutable owner memory.
manifest.json: format, sizes and SHA-256 checksums.

Excluded: provider API-key files, OAuth/device login state and provider-state volume, registered host workspace contents, and browser profiles. Keep separate project backups and provider recovery arrangements. A portable backup does not transfer every login to another host.

Backup files are owner-restricted but still sensitive. Protect them from public sharing and retain verified copies according to owner policy. A successful backup command is not a demonstrated restore; test recovery in a disposable environment with representative data.

Restore and rollback are different#

Restore:

npx --yes run-spaceapp@latest restore

The verified flow requires typing RESTORE, selects the newest valid backup, creates a pre-restore backup, stops relevant services, validates integrity/archive paths, replaces data/memory/database and restarts. Restore replaces current application state and can discard newer changes. Preserve needed data and an offline backup copy first.

Rollback:

npx --yes run-spaceapp@latest rollback

Rollback returns to the single recorded prior image/configuration version. It does not reverse migrations or data-format changes. Verify backward compatibility and release recovery instructions. Do not automatically combine rollback with restore; that is a separate destructive decision.

When moving to a new host, reconnect provider accounts and register local project paths. Validate owner login, memory, files, workspaces and real agent execution after recovery.

Reset and removal#

factory-reset is for an explicitly requested fresh state, not routine diagnosis:

npx --yes run-spaceapp@latest factory-reset

The workflow attempts a safety backup and requires typed FACTORY-RESET confirmation before destructive reset. In the reviewed implementation a backup problem can be reported without preventing the reset confirmation; independently verify a usable backup before proceeding. A safety backup does not cover excluded provider credentials or host projects. Read the displayed scope and stop if it does not match the intended installation.

Ordinary removal:

npx --yes run-spaceapp@latest uninstall

This removes containers/network while retaining data volumes, configuration, secrets and backups. It does not remove the optional global npm launcher. If appropriate after runtime removal:

npm uninstall -g run-spaceapp

Destructive volume removal:

npx --yes run-spaceapp@latest uninstall --purge-data

This removes application/database/memory/provider/workspace-volume state after confirmation. Host files under the installation root, including backups and provider key files, can remain; do not describe it as secure erasure of every file or deletion of registered host repositories. Review leftovers deliberately and never delete unrelated Docker resources.