Data, backups and upgrades

Know which data belongs to which component

Helios normally keeps its application state in ~/.helios/. HELIOS_STATE_DIR changes that app-state root for supported Helios paths. Provider CLIs keep separate authentication and authoritative histories.

Changing HELIOS_STATE_DIR alone does not isolate all provider files or make a fully separate demo account. Native provider stores, Claude transcripts and memory, optional tandem state and title-generation working files can live elsewhere.

Make a consistent backup

1. Finish or stop active work. Review background activity and provider processes.
2. Quit Helios before copying its state. The Work store uses SQLite with write-ahead logging; a stopped app makes a filesystem backup straightforward.
3. Back up the whole app-state directory, including any database sidecars that remain.
4. Separately back up project folders and the provider histories you need.
5. Keep the backup private. App and provider directories can contain API keys, conversation content and source code.

For the default state directory, a simple app-state archive is:

install -m 700 -d "$HOME/Backups/helios"
tar -czf "$HOME/Backups/helios/state-$(date +%Y%m%d-%H%M%S).tar.gz" \
  -C "$HOME" .helios
chmod 600 "$HOME"/Backups/helios/state-*.tar.gz

This example covers app state only. Adjust the source if you use HELIOS_STATE_DIR, and keep repository and provider backups alongside it. Copying app state cannot recreate code that was stored elsewhere.

Restore carefully

Quit Helios, preserve a copy of the current state, and restore into the intended app-state location. Preserve file ownership and private permissions. Restore project folders and native provider data separately when required.

Launch Helios and verify the expected sessions, working directories, media and provider account. Start with a read-only check before resuming an editing task. Avoid overlaying an older backup onto a running database.

Recover older or missing sessions

First check the sidebar’s project and Temporary filters, then reload. Temporary project paths include /tmp and components beginning with _tmp_.

Older local Claude transcripts can move into session-archive/ under Helios’s state directory. Throwaway project directories can also move into Claude’s projects-archive/. Archiving moves history; it does not delete it.

To restore a transcript for Claude’s native resume flow, close Helios and inspect the archived file and original project mapping. Move the matching transcript and any same-stem sidecar directory back to the correct Claude project directory, then reload. Preserve both copies if a filename already exists.

Upgrade through the channel you chose

The latest GitHub release package and the stable APT channel can be different versions. The installation channel guide explains the choice and checksum verification.

Back up before upgrading. Installing a new package does not change code already loaded by a running Helios process. Finish active work, quit and relaunch when you are ready, then check the version in About.

Know the recovery limits

Memory-editor backups are rotating copies of edited memory files. Checkpoints capture eligible Git project files before messages. Neither substitutes for a full backup of app state, native histories and project data.

See checkpoint exclusions and the repository’s data and environment reference for more detail.