Move your Hub to a new machine

When you change hardware, you can move a Hub — installed apps, app data, and settings — by copying two things to the new machine: its data folder, and the Docker volume that holds its database.

Before you start

You need:

• Docker installed on the new machine — see Install Docker
• Companion Hub installed on the new machine, at the same version, started once and then stopped. This creates the correct folder structure, database volume, and system integration before you copy the data over.
• Enough free disk space on the new machine for the data you’re moving
• A Linux or macOS shell — the commands on this page assume one

Find your Hub data folder (ROOT_FOLDER_HOST) on the old machine. cihub doctor prints it on the Root folder line. The defaults are ~/.local/share/companion-hub on Linux, ~/Library/Application Support/companion-hub on macOS, and %APPDATA%\companion-hub on Windows. Folder structure explains what’s inside.

A Hub keeps its state in two places, and you need both:

• The data folder holds app data, installed app files, your per-app config, and Hub settings.
• The ci_hub_pgdata Docker volume holds the Hub database: operator accounts, the list of installed apps, and API keys. It is not inside the data folder, so an archive of the data folder alone moves your files but starts the new Hub with an empty database.

flowchart LR
    subgraph OLD["Old machine"]
        IN["Data folder: app-data, apps, user-config,<br/>state, logs, cache"]
        DB["Docker volume ci_hub_pgdata<br/>the Hub database"]
        EX["Left behind on purpose: media, repos, backups,<br/>env file, docker-compose.prod.yml"]
    end
    IN -- "tar -czvf" --> AR["hub-data.tar.gz"]
    DB -- "docker run alpine tar" --> AD["hub-db.tar.gz"]
    AR -- "scp, rsync, external drive,<br/>or magic-wormhole" --> EXT
    AD -- "scp, rsync, external drive,<br/>or magic-wormhole" --> EXT
    subgraph NEW["New machine"]
        EXT["Extract into the fresh install's<br/>data folder and database volume"] --> UP["cihub up --detached"]
    end
    EX -. "media: copy separately<br/>backups: copy to keep them" .-> EXT
    NOT["Not in the archives: shared folders,<br/>mount points, firewall rules,<br/>CI Account pairing"] -. "re-apply by hand" .-> UP

cihub down

docker ps

DATA_ROOT="$HOME/.local/share/companion-hub"
cd "$(dirname "$DATA_ROOT")"
NAME="$(basename "$DATA_ROOT")"
tar -czvf hub-data.tar.gz --anchored \
  --exclude="$NAME/media" --exclude="$NAME/repos" --exclude="$NAME/backups" \
  --exclude="$NAME/.env" --exclude="$NAME/.env.dev" --exclude="$NAME/docker-compose.prod.yml" \
  "$NAME"

docker run --rm -v ci_hub_pgdata:/source:ro -v "$PWD":/backup alpine \
  tar -czf /backup/hub-db.tar.gz -C /source .

cihub down

tar -xzvf hub-data.tar.gz -C /path/to/parent/of/data/root

docker run --rm -v ci_hub_pgdata:/target -v "$PWD":/backup alpine \
  sh -c 'find /target -mindepth 1 -delete && tar -xzf /backup/hub-db.tar.gz -C /target'

cihub up --detached

cihub doctor

After the move

• Re-apply host-specific configuration — shared folders, mount points, and firewall rules do not travel in the archive
• Check your network settings — the new machine has a different IP, so any manual DNS entries or port forwards need updating
• Pair the Hub again if you use remote access. Your CI Account registration belongs to the old machine’s device ID, and the tunnel token sits in a tunnel folder next to the data folder, which the archive doesn’t include. If cihub doctor shows Registration as degraded (portal_rejected), run cihub register --code <code> with a fresh pairing code. See Device Pairing.
• Check the device ID — if you copied an env file with a DEVICE_ID line, cihub doctor reports Device ID as copied from another machine, and Hub refuses to pair under it. Remove the line, or set it to the new machine’s own ID.