Backup and restore your packages and configurations across Linux machines - like Apple's Migration Assistant or Chrome Sync, but private, open-source, and under your control. Your data stays in your GitHub account, not some company's servers.
# Backup your files from your old machine
# basic backup (apps+packages+bashrc)
tuxsync backup
# full backup (apps+packages+all-dotfiles+config-files+secrets(encrypted))
tuxsync backup --use-chezmoi --chezmoi-repo username/dotfiles
# Restore on new machine
pip install tuxsync
tuxsync restore <GIST_ID>
# List your backups
tuxsync list- Multi-Distro Support - Ubuntu/Debian (apt), Fedora (dnf), and Arch (pacman)
- Privacy First - GitHub Gists (convenient) or your own custom server (private)
- Chezmoi Integration - Optional comprehensive dotfile management with encryption support (guide)
- Loose Coupling - Uses tuxmate, tuxmate-cli, and chezmoi as external executors
- Smart Scanning - Only backs up user-installed packages, filters out libraries
- Magic Restore - One-liner command to restore your setup on any Linux machine
See Usage section below for detailed commands.
pip install tuxsync --upgrade# Backup your current system
tuxsync backup
# Restore on a new machine
tuxsync restore <GIST_ID># Interactive mode (recommended)
tuxsync backup
# Non-interactive mode
tuxsync backup --github --non-interactiveWhat happens:
- Scans your system for user-installed packages (filters out libraries)
- Backs up your
~/.bashrcfile - Uploads to GitHub Gist (private by default)
- Gives you a magic restore command
# Backup everything with chezmoi integration
tuxsync backup --use-chezmoi --chezmoi-repo username/dotfilesWhat happens:
- Backs up all packages (same as basic)
- Auto-installs chezmoi if not present
- Initializes chezmoi with your dotfiles repository
- You can then add your dotfiles manually
💡 Learn more:
# Using the magic one-liner (no installation needed!)
curl -sL https://raw.githubusercontent.com/Gururagavendra/tuxsync/main/restore.sh | bash -s -- <GIST_ID>
# Or install TuxSync first
pip install tuxsync
tuxsync restore <GIST_ID>What happens:
- Downloads package list from GitHub Gist
- Installs packages using tuxmate-cli (cross-distro magic!)
- Restores your
.bashrcfile
tuxsync restore <GIST_ID> --use-chezmoi --chezmoi-repo username/dotfilesWhat happens:
- Restores all packages (same as basic)
- Auto-installs chezmoi if not present
- Clones your dotfiles repository
- Applies all dotfiles system-wide
- Your entire environment is restored!
# Dry run (see what would happen without making changes)
tuxsync restore <GIST_ID> --dry-run
# Skip specific components
tuxsync backup --no-bashrc # Skip .bashrc backup
tuxsync restore <GIST_ID> --skip-packages # Only restore configs
tuxsync restore <GIST_ID> --skip-bashrc # Only restore packages
# Merge bashrc instead of replacing
tuxsync restore <GIST_ID> --merge-bashrc
# Non-interactive mode (for automation)
tuxsync backup --github --non-interactive
tuxsync restore <GIST_ID> --yes
# List your backups
tuxsync listScenario 1: New Laptop (Basic)
# Old laptop
$ tuxsync backup
# ✓ Backup ID: abc123def456
# New laptop (any distro!)
$ pip install tuxsync
$ tuxsync restore abc123def456
# ✓ All packages installed!Scenario 2: New Laptop (Full Setup)
# Old laptop
$ tuxsync backup --use-chezmoi --chezmoi-repo myusername/dotfiles
# New laptop
$ pip install tuxsync
$ tuxsync restore abc123def456 --use-chezmoi --chezmoi-repo myusername/dotfiles
# ✓ Packages + entire dotfile setup restored!Scenario 3: Distro Hopping (Ubuntu → Arch)
# On Ubuntu
$ tuxsync backup --use-chezmoi --chezmoi-repo user/dotfiles
# Switch to Arch Linux
$ pip install tuxsync
$ tuxsync restore abc123def456 --use-chezmoi --chezmoi-repo user/dotfiles
# ✓ TuxSync translates apt packages to pacman equivalents!| Component | Basic Backup | With --use-chezmoi |
|---|---|---|
| User-installed packages | ✅ | ✅ |
| System libraries | ❌ (auto-filtered) | ❌ |
~/.bashrc |
✅ | ✅ |
All dotfiles (~/.vimrc, ~/.gitconfig, etc.) |
❌ | ✅ (manual) |
Entire ~/.config/ directory |
❌ | ✅ (manual) |
| SSH configs | ❌ | ✅ (manual, encrypted) |
| Encrypted secrets | ❌ | ✅ (manual, encrypted) |
See Managing Dotfiles with Chezmoi for details on what's automatic vs manual.
- Python 3.10+
- GitHub CLI (gh) - For GitHub Gist storage
- tuxmate-cli - Auto-downloaded when needed
- chezmoi - Auto-installed when using
--use-chezmoi - gum (optional) - For interactive menus
git clone https://github.com/Gururagavendra/tuxsync.git
cd tuxsync
uv sync
./tuxsync.sh helpTuxSync creates a backup containing your package list and bashrc, stored as a private GitHub Gist. The restore process fetches this backup and uses tuxmate-cli to install packages across different Linux distributions.
Architecture:
- TuxSync - The Orchestrator (coordinates backup/restore workflow)
- tuxmate-cli - Package Manager (handles cross-distro package installation using tuxmate's curated package database)
- chezmoi - Dotfile Manager (optional integration for comprehensive dotfile syncing)
Documentation:
- Managing Dotfiles with Chezmoi - Complete guide to adding and managing dotfiles
- Chezmoi Workflow - Behind-the-scenes commands and processes
- Backing Up Sensitive Credentials - Security best practices for SSH keys, credentials
- Architecture Overview - Technical specifications and design philosophy
- Custom Server API - Self-host your backups
When using --use-chezmoi, TuxSync integrates with chezmoi for comprehensive dotfile management.
Important: Chezmoi does NOT automatically add files - you have full control over what gets backed up.
# Initial backup
tuxsync backup --use-chezmoi --chezmoi-repo username/dotfiles
# Add dotfiles
chezmoi add ~/.vimrc ~/.gitconfig ~/.config/nvim
# Add encrypted secrets
chezmoi add --encrypt ~/.ssh/id_rsa
chezmoi add --encrypt ~/.docker/config.json
# View managed files
chezmoi managed
# Push changes
cd ~/.local/share/chezmoi && git push📖 Complete Guide: Managing Dotfiles with Chezmoi
Detailed instructions on adding files, encryption setup, exclusions, and troubleshooting.
TuxSync supports backing up sensitive data like SSH keys, Docker credentials, cloud provider tokens, and more using encrypted storage via chezmoi integration.
# Step 1: Setup encryption (one-time)
sudo apt install age
age-keygen -o ~/.config/chezmoi/key.txt
# Step 2: Backup with chezmoi
tuxsync backup --use-chezmoi --chezmoi-repo username/dotfiles
# Step 3: Add encrypted secrets
chezmoi add --encrypt ~/.ssh/id_rsa
chezmoi add --encrypt ~/.docker/config.json
# Step 4: Push to repo
cd ~/.local/share/chezmoi && git push
# On new machine - credentials are automatically restored
tuxsync restore <GIST_ID> --use-chezmoi --chezmoi-repo username/dotfilesImportant: All sensitive data (SSH keys, credentials, tokens) is encrypted before leaving your machine using age or GPG encryption. Your secrets are never stored in plain text.
📖 Full Guide: Backing Up Sensitive Credentials - Detailed security guide covering SSH keys, Docker credentials, cloud provider tokens, and more.
Early Development: TuxSync is actively being developed.
- ✅ Package scanning (apt, dnf, pacman)
- ✅ GitHub Gist storage
- ✅ bashrc backup/restore
- ✅ tuxmate-cli integration
- ✅ Dry-run mode
- ✅ Chezmoi integration - Comprehensive dotfile management
- ✅ Encrypted secrets support - SSH keys, credentials, tokens
- Sensitive file auto-detection with encryption prompts
- Credential rotation helper on restore
- Incremental backups - Only backup changes since last backup
- Profile versioning - Keep multiple versions/snapshots with timestamps
- Custom backup schedules and automation
Want to host backups on your own server instead of GitHub? See Custom Server API for implementation details.
Contributions welcome! Please feel free to submit issues or pull requests.
GPL-3.0 License - See LICENSE for details.
- Package restoration powered by tuxmate-cli
- Package database from tuxmate by @abusoww - curated collection of 150+ Linux applications
- dotfile management from chezmoi