Subshell Docs

Backups and restoration

Save your server's data and configuration in one archive to restore it here or move it to another machine.

What a full backup contains

DataArchivedDetails
Server databaseYesA consistent SQLite snapshot containing accounts, settings, and session records.
Server configurationYesSupported settings and the authentication secret.
Identity and connection keysYesServer-owned node signing and encryption keys, channel identities, peer records, and push notification keys.
Installed pluginsYesPlugin code, settings, state, and plugin-owned secrets.
Server and pane logsYesCaptured over the backup interval rather than at the database snapshot's exact instant.
Projects and project uploadsNoRemain on the machines where they are stored.
External agent credentialsNoCredentials managed by agent tools outside Subshell.
Remote node filesNoFiles and logs stored on enrolled remote nodes.
External network daemon stateNoState managed by services outside Subshell.
Operating system servicesNoService definitions and login startup settings.
Binaries and cachesNoServer executables and cached binaries.
Previous backups and temporary filesNoExisting backups, staging files, and restore or update transactions.
Running processesNoLive sessions, tmux sockets, and agent in-memory state.

Backup credentials

A full archive contains keys and credentials. Enable encryption to protect them with a password, and keep the archive in a secure location. Store the password separately; a forgotten password can't be recovered.

Before you start

Use the OS account that owns the server when working in the desktop app or CLI. Browser backup and restore preparation require an instance administrator.

Encrypted backups

Plain archives use .tar.gz; encrypted archives use .tar.gz.enc.

Encryption is optional and defaults off. Enable it when saving an archive to protect its contents with a password.

Use at least eight characters, preferably a unique password generated by a password manager or a long random passphrase. Passwords can't contain line breaks. The minimum length doesn't make a predictable password strong.

See Security model for encryption details, resource limits, and protection against password guessing.

Download from Server Settings

You must be an instance administrator.

  1. Open Settings → Server Settings → Backups in the server dashboard.
  2. Select Backup, optionally enable Encrypt the archive with a password, and enter and confirm your password. Invalid or mismatched passwords prevent creation; errors appear when you leave a field.
  3. Select Create backup. Wait for the progress pane to finish, then select Next.
  4. Review the archive filename, size, and encryption status, then select Download backup. Select Done to return to configuration.

When you download from the control plane inside a desktop app, the app reports the saved location when the download completes.

The server keeps only a temporary download copy. The link is available once, for one hour, and the temporary copy is deleted after downloading or discarding it. There is no automatic backup schedule.

Restore in the control plane

  1. Open Settings → Server Settings → Backups as an instance administrator.
  2. Select Restore, then choose Open a backup file or Use a saved backup. Select Choose backup file… or choose a saved archive under Available backups. The selection is validated automatically.
  3. If the archive is encrypted, enter its password and select Validate backup. The password field appears only when needed. Configure backup stays disabled until validation succeeds.
  4. Select Configure backup. Choose the restore mode and review destination paths and addresses. Optionally enable Recover an existing administrator, choose the account, and enter and confirm a temporary password.
  5. Select Review backup. Invalid configuration or recovery fields prevent advancing; errors appear when you leave a field. Review the archive, destination, and any affected-session count. Back returns to configuration.
  6. Select the confirmation checkbox, then Start restore. The server host performs the restore directly, including on headless installations.
  7. Wait for restoration and the startup check to finish. The page reconnects after the server restarts. Select Next to review the result, then sign in with an account from the backup.

Browser uploads support archives up to 128 MB. Saved backups are selected from the server's backup directory. Use the CLI or desktop assistant for larger files on your own machine. The configuration and review steps don't replace the running server’s state. Extracted copies expire after ten minutes; an expired extraction is validated again while its source remains available. The control plane restores to the server’s current destination paths.

Use Subshell Server on desktop

Open Backup… or Restore… from Subshell Server's native menu or tray. The bundled assistant works while the server is stopped. Restore is also available before first-run setup.

Save an archive

  1. Open Backup….
  2. Optionally enable Encrypt the archive with a password, then enter and confirm the password. Invalid or mismatched passwords prevent saving; errors appear when you leave a field.
  3. Select Save backup… and choose a filename and location in the native save dialog. If you confirm replacing an existing file, the previous archive stays intact until the new backup completes successfully.
  4. Wait for the backup progress pane to finish, then select Next.
  5. Check the saved archive path, size, and encryption status. Copy the path if needed, then select Done.

Restore an archive

  1. Open Restore… and choose Open a backup file or Use a saved backup.
  2. For a file, select Choose backup file… to open the native file picker. For a saved backup, select a file under Available backups. The assistant validates the selection automatically.
  3. If the archive is encrypted, enter its password and select Validate backup. The password field appears only when needed. Configure backup stays disabled until validation succeeds.
  4. Select Configure backup. Review the restore mode, destination paths, and address settings. Optionally enable Recover an existing administrator, choose the account, and enter and confirm a temporary password.
  5. Select Review backup. Invalid configuration or recovery fields prevent advancing; errors appear when you leave a field.
  6. Review the prepared destination, backup details, and session consequences. The assistant reports the count of incompatible sessions rather than listing every name. Back returns to configuration without applying the restore.
  7. Select the confirmation checkbox acknowledging replacement and the session effects. Select Start backup to apply the restore; this is the current button label on the restore review pane.
  8. Wait for the restore progress pane to finish, then select Next. Review the result, destination paths, and the configured control plane URL. Use its open or copy controls, then select Done.

The form fills optional locations and addresses from the backup, using the current server's values when an older archive omits them. Clearing an optional field keeps its suggested value. The server is always started and checked after restoring through the desktop assistant. An installed service keeps its existing supervision; an app-managed server uses the restored configuration.

Preparation keeps a private extracted copy for ten minutes. The saved backup itself doesn't expire. If the extraction expires while the assistant is open, it extracts and validates the source again before applying. Changed backup details or destination choices require another review. Keep the source file available throughout the flow.

The app uses its bundled CLI for backup and restore. If the installed server is newer than the app, update Subshell Server before proceeding.

Use the CLI

Run these commands on the server host as its owning OS user. The destination directory must exist or be writable by that account. The CLI won't overwrite an existing backup file, so choose a new filename.

subshell-server backup --output /private/backups/server.tar.gz
subshell-server restore /private/backups/server.tar.gz --inspect --json
subshell-server restore /private/backups/server.tar.gz

Interactive encryption asks for a hidden password and confirmation. For automation, use --encrypt --password-file <private-file> when creating the archive and --password-file <private-file> when inspecting or restoring it. A password file must be owned by your OS user, have no group or other permissions, and contain one line. - reads the password from stdin. Never put the password in a command argument.

For an encrypted backup using an existing private password file:

subshell-server backup --output /private/backups/server.tar.gz.enc \
  --password-file /private/credentials/backup-password --json
subshell-server restore /private/backups/server.tar.gz.enc --inspect \
  --password-file /private/credentials/backup-password --json

Use subshell-server backup --list --json to list files in the server’s backup directory. A terminal restore walks through the choices before replacing state. Automation uses --yes for replacement and, when sessions can't be preserved, separate --force consent. Use --no-start to leave the instance stopped. --prepare creates a private extracted stage without replacement; restore --staged <id> applies its prepared choices. Stages expire after ten minutes, so an expired CLI stage must be prepared again from its source. See the Server CLI reference for migration and account recovery flags.

Restore guarantees

An older restored database receives pending application and authentication migrations when the server starts, before it serves requests. Invalid archives, unsupported newer migrations, and wrong encryption passwords are rejected before replacement. The restore preserves the previous destination state until the restored server completes a successful boot. An interrupted replacement is recovered before configuration is loaded; a failed boot rolls back to the previous state. If you choose not to start, the previous state remains until the next successful boot.

Migration writes the selected destination paths into configuration. It retains network settings and secrets but disables network plugins and clears publication addresses until you review Settings → Server Settings → Networking. Operating system services and external network daemons still belong to the destination machine.

Verify recovery

Test a restore on an isolated instance before relying on a backup. After restoring, sign in, change a temporary recovery password if selected, review networking and addresses, check node connectivity, and inspect your saved sessions and logs. Read Files and paths, Account recovery, and Update the server.

Edit on GitHub

Last updated on

On this page