Skip to content

CruxExperts/best-backup

BranchesTags

Repository files navigation

🗄️ bbackup

Back up Docker containers and host filesystems — encrypted, incremental, and agent-ready.

Python 3.10+ License: MIT Version

Quick start · Filesystem backup · Agent integration · CLI reference · Docs

pipx install git+https://github.com/cptnfren/best-backup.git

pipx handles the virtual environment automatically. If bbackup is already installed and you want to move to a newer version, use pipx upgrade bbackup (or the system-wide variant from Installation) instead of re-running pipx install. See Installation if you need to install pipx first, or for alternative methods.

What it does

Run bbackup backup and you get an interactive container picker, a live BTOP-style dashboard while the backup runs, and a finished archive that can be encrypted and shipped to Google Drive, SFTP, or a local path. Point it at /srv/data and it backs that up too, with gitignore-style excludes. The companion bbman command handles setup, health checks, dependency installs, and self-updates so day-to-day maintenance stays out of the way.

Every command speaks structured JSON, making it compatible with AI agents out of the box: set two env vars, run bbackup skills, and drive the entire tool with --input-json.

Features

Feature Description
🖥️ Rich TUI BTOP-style live dashboard with real-time transfer metrics
🐳 Docker backup Containers, volumes, networks, and configs in one shot
📁 Filesystem backup Back up any host path recursively with gitignore-style excludes
⚡ Incremental backups rsync --link-dest so unchanged data is hardlinked, not copied
🔐 Encryption AES-256-GCM (symmetric) or RSA-4096 (asymmetric) at rest
☁️ Remote storage Google Drive via rclone, SFTP, or local directory
♻️ Rotation Time-based daily/weekly/monthly retention with quota enforcement
📦 Solid archive Optional single tarball (and optional whole-file encryption) for upload so remotes get one file instead of many
↩️ Full restore Containers, volumes, networks, and filesystem paths; restore from directory or solid archive file
📦 Backup sets Named groups of containers defined in config for repeatable runs
🤖 Agent-friendly CLI JSON I/O, --input-json, --dry-run, and skill discovery on every command
🛠️ Management CLI bbman for setup, health, updates, cleanup, and diagnostics

Requirements

  • Python 3.10+
  • Docker (with socket access for your user)
  • rsync (system package — used for volume and filesystem backups)
  • rclone (optional, for Google Drive)

Installation

pipx handles the virtual environment automatically. Pick the method that fits your setup.

pipx install (single user)

Use this when installing bbackup for the first time for your user only:

sudo apt install pipx && pipx ensurepath
pipx install git+https://github.com/cptnfren/best-backup.git

Open a new shell and both commands are ready.

pipx upgrade (single user)

If bbackup is already installed via pipx and you just want to move to a newer version:

pipx upgrade bbackup

Use pipx reinstall bbackup if you want a fresh virtual environment.

pipx install (server / all users)

Installs to /usr/local/bin and makes bbackup and bbman available to every user and cron job:

sudo apt install pipx
sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install git+https://github.com/cptnfren/best-backup.git

pipx upgrade (server / all users)

If bbackup is already installed system-wide via pipx and you want to update in place:

sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx upgrade bbackup

For development installs, manual venv setup, and uninstall instructions, see INSTALL.md.

Quick start

# First-time setup: checks Docker, installs deps, creates config
bbman setup

# Interactive backup with live TUI
bbackup backup

# Target specific containers
bbackup backup --containers myapp mydb

# Back up a host filesystem path
bbackup backup --paths /srv/data

# Non-interactive mode (cron or agent)
BBACKUP_OUTPUT=json BBACKUP_NO_INTERACTIVE=1 bbackup backup --backup-set production

See QUICKSTART.md for a full walk-through: config, remote storage, encryption setup, and more.

Configuration

bbackup checks these locations in order:

  1. ~/.config/bbackup/config.yaml
  2. ~/.bbackup/config.yaml
  3. /etc/bbackup/config.yaml
  4. ./config.yaml

A fully annotated template is in config.yaml.example. The minimal setup:

backup:
  local_staging: /tmp/bbackup_staging
  backup_sets:
    production:
      containers: [myapp, mydb, nginx]
      scope:
        volumes: true
        configs: true

remotes:
  local:
    enabled: true
    type: local
    path: ~/backups/docker

For rclone remotes you can optionally set rclone_options.transfers and rclone_options.checkers (or top-level rclone.default_options) to tune upload concurrency; both accept 1–32, default 8. See config.yaml.example and docs/architecture.md.

Filesystem backup

Add a filesystem: section to back up arbitrary host paths:

filesystem:
  home-data:
    description: "Important home directory data"
    targets:
      - name: documents
        path: /home/user/Documents
        enabled: true
        excludes:
          - "*.tmp"
          - ".cache/"
          - "node_modules/"

Run a named filesystem set:

bbackup backup --filesystem-set home-data

Or pass paths directly, no config needed:

bbackup backup --paths /home/user/docs /srv/data --exclude "*.tmp"

CLI reference

bbackup commands 
# Docker backup
bbackup backup                                         # Interactive backup with TUI
bbackup backup --backup-set production                 # Named backup set from config
bbackup backup --containers app db                     # Specific containers
bbackup backup --incremental                           # rsync --link-dest mode
bbackup backup --config-only                           # Skip volumes
bbackup backup --volumes-only                          # Skip configs
bbackup backup --no-networks                           # Skip network configs
bbackup backup --remote gdrive                         # Upload to specific remote

# Filesystem backup
bbackup backup --paths /home/user/docs /srv/data       # Back up specific paths
bbackup backup --paths /home/user/docs --exclude "*.tmp"
bbackup backup --filesystem-set home-data              # Named set from config

# Restore
bbackup restore --backup-path /path/to/backup --all
bbackup restore --backup-path /path --containers app --rename app:app_v2
bbackup restore --backup-path /path --filesystem documents \
  --filesystem-destination /home/user/docs

# Inspect
bbackup list-containers
bbackup list-backup-sets
bbackup list-filesystem-sets
bbackup list-backups
bbackup list-remote-backups --remote gdrive

# Setup
bbackup init-config
bbackup init-encryption --method asymmetric --algorithm rsa-4096

# Agent / non-interactive (available on every command)
bbackup list-containers --output json
bbackup backup --containers app --input-json '{"incremental":true}'
bbackup backup --containers app --dry-run --output json
bbackup skills                          # discover all capabilities
bbackup skills docker-backup            # step-by-step guide + JSON schemas
bbman commands 
bbman setup                                          # First-time setup wizard
bbman setup --no-interactive                         # Skip wizard (agent mode)
bbman health                                         # Docker, tools, config health check
bbman health --output json
bbman check-deps                                     # Check dependencies
bbman check-deps --install                           # Install missing packages
bbman validate-config                                # Parse and validate config
bbman status                                         # Backup history and totals
bbman status --output json
bbman cleanup                                        # Clean staging dirs and old logs
bbman cleanup --yes                                  # Skip confirmation (agent mode)
bbman diagnostics                                    # Generate diagnostic report
bbman diagnostics --report-file /tmp/report.txt      # Save to file
bbman check-updates                                  # Check for newer version
bbman update                                         # Self-update from repo
bbman update --yes                                   # Skip confirmation (agent mode)
bbman repo-url --url URL                             # Set the update source URL
bbman run backup --containers app                    # Run bbackup through the wrapper
bbman skills                                         # Discover bbman capabilities
bbman skills maintenance                             # Step-by-step maintenance guide

Agent integration

bbackup and bbman are natively compatible with AI agents. Every command supports structured JSON I/O, progressive skill discovery, and non-interactive execution without extra configuration.

Environment variables

Set these once and every subprocess inherits them:

export BBACKUP_OUTPUT=json           # all commands emit a JSON envelope
export BBACKUP_NO_INTERACTIVE=1      # no TUI, no prompts, no pagers
Variable Effect
BBACKUP_OUTPUT=json All commands emit JSON envelope without --output json
BBACKUP_NO_INTERACTIVE=1 Suppresses TUI, prompts, and pagers system-wide

Skill discovery (JSON and Markdown)

bbackup skills                           # level-0: all skill IDs + summaries (JSON)
bbackup skills docker-backup             # level-1: steps, schemas, examples (JSON)
bbackup skills --format markdown         # full Markdown skills catalog
bbman skills                             # level-0 skills for bbman (JSON)
bbman skills maintenance                 # maintenance skill (JSON)
bbman skills --format markdown           # full Markdown skills catalog

Level-0 JSON output:

{
  "cli": "bbackup",
  "version": "1.4.0",
  "agent_hint": "Set BBACKUP_OUTPUT=json and BBACKUP_NO_INTERACTIVE=1 for fully non-interactive use.",
  "skills": [
    {"id": "docker-backup",     "summary": "Back up Docker containers, volumes, networks, and configs.", "common": true},
    {"id": "filesystem-backup", "summary": "Back up arbitrary host filesystem paths with gitignore-style excludes.", "common": true},
    {"id": "restore",           "summary": "Restore containers, volumes, networks, or filesystem paths from a backup.", "common": true}
  ]
}

JSON envelope

Every command in JSON mode emits exactly this to stdout. All progress and diagnostic text goes to stderr.

{
  "schema_version": "1",
  "command": "backup",
  "success": true,
  "data": {},
  "errors": []
}
  • schema_version bumps only on breaking changes — additive fields are always safe.
  • errors is always present; non-empty means success: false.
  • A non-zero exit code always accompanies success: false.

--input-json parameter passing

Pass all parameters as a single flat JSON object. Keys use underscores (hyphens converted). The object merges over any CLI flags already provided.

bbackup restore \
  --input-json '{"backup_path":"/tmp/bbackup/backup_20260227","containers":["myapp"],"dry_run":true}' \
  --output json

Unknown keys are silently ignored — forward-compatible by design.

Dry-run / pre-flight

bbackup backup --containers myapp --dry-run --output json
{
  "schema_version": "1",
  "command": "backup",
  "success": true,
  "data": {
    "dry_run": true,
    "would_backup": {
      "containers": ["myapp"],
      "filesystem_targets": [],
      "remotes": [],
      "incremental": false,
      "scope": {"volumes": true, "configs": true, "networks": true}
    }
  },
  "errors": []
}

Exit codes

Code Meaning
0 Fully successful
1 Bad argument, missing param, or invalid --input-json
2 Config not found or fails validation
3 Docker unreachable, rsync/rclone missing, or key generation failed
4 Partial: some items succeeded, some failed
5 Operation cancelled by user or agent

Tip

For agent workflows, set BBACKUP_OUTPUT=json and BBACKUP_NO_INTERACTIVE=1 globally, then use bbackup skills to discover what's available before issuing commands.

Encryption

Two modes are available:

Symmetric — AES-256-GCM: One key encrypts and decrypts. Good for single-server setups.

bbackup init-encryption --method symmetric

Asymmetric — RSA-4096: Public key encrypts, private key decrypts. Better for multi-server setups where backup and restore run on separate machines.

bbackup init-encryption --method asymmetric --algorithm rsa-4096

The public key can live on GitHub:

encryption:
  enabled: true
  method: asymmetric
  asymmetric:
    public_key: github:YOUR_USERNAME/gist:YOUR_GIST_ID
    private_key: ~/.config/bbackup/backup_private.pem

Full details in docs/encryption.md.

TUI keyboard controls

Key Action
Q Quit / cancel backup
P Pause / resume
S Skip current item
H Help

Project structure

best-backup/
├── bbackup/
│   ├── cli.py                # bbackup CLI entry point
│   ├── cli_utils.py          # JSON envelope, exit codes, shared decorators
│   ├── skills.py             # Skill descriptors for agent discovery
│   ├── config.py             # Config loading and all dataclasses
│   ├── docker_backup.py      # Docker backup via temp Alpine containers
│   ├── filesystem_backup.py  # Host filesystem backup via rsync
│   ├── backup_runner.py      # Backup workflow orchestration
│   ├── restore.py            # Restore operations
│   ├── tui.py                # Rich TUI and BackupStatus tracking
│   ├── remote.py             # Remote storage (local / rclone / SFTP)
│   ├── rotation.py           # Retention policies and quota cleanup
│   ├── encryption.py         # AES-256-GCM + RSA encryption
│   ├── logging.py            # Rotating file logger
│   ├── bbman_entry.py        # Console script shim for bbman
│   └── management/           # bbman subpackage (11 modules)
├── bbackup.py                # bbackup entry point
├── bbman.py                  # bbman entry point
├── config.yaml.example       # Annotated config template
├── requirements.txt
└── setup.py

Documentation

Doc Description
QUICKSTART.md Setup to first backup in 5 minutes
INSTALL.md All installation methods
docs/management.md Full bbman reference
docs/encryption.md Encryption setup and key management
CHANGELOG.md Release history
CONTRIBUTING.md How to contribute
SECURITY.md How to report vulnerabilities
docs/cli-skills.md Unified CLI skills catalog for humans and AI agents

Roadmap

Shipped

  • Rich TUI with real-time transfer metrics
  • Incremental backups with rsync --link-dest
  • Backup rotation and retention policies
  • AES-256-GCM and RSA-4096 encryption
  • Full restore with optional rename
  • Filesystem backup for arbitrary host paths and directory trees
  • Management wrapper (bbman)
  • GitHub key integration for public key distribution
  • AI agent JSON I/O, skill discovery, --dry-run, and --input-json on all commands

Planned

  • Backup verification and checksums
  • Email and webhook notifications
  • Cron-based scheduling integration
  • Multi-server backup coordination
  • Backup diff / comparison
  • Web UI

Credits

Built with Rich, Click, and docker-py.

License

MIT



Slavic Kozyuk
© 2026 Crux Experts LLC — MIT License

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

3 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases 9

v1.7.0 Latest
Mar 4, 2026
+ 8 releases

Packages

 
 
 

Contributors

Languages