Original title "Recover files from Synology Hyper Backup (.hbk) archives without Synology software — CLI + TUI, checksum-verified, plus a full format spec" compressed to fit within title limits.
I'm on the other side of the world from my NAS right now, and I wanted to pull the whole backup down and restore it elsewhere. Hyper Backup is great at pushing data out to S3/R2. Getting it back is where it falls apart.
Hyper Backup Explorer is the only official way to open a .hbk archive. It's GUI-only, has no CLI, and ships no Apple Silicon build. On my archive (4.8TB, around 1.1 million files) it was slow enough that I gave up and picked the format apart instead.
github.com/YordiLorenzo/hbkit (MIT license) or `pip install hbkit`
CLI plus a TUI. Point it at an archive, browse it like a file tree, tick what you want, pull it out. Runs natively on Apple Silicon and headless on Linux, extraction is parallel and resumable. Every chunk gets verified against the MD5 and CRC32 that Hyper Backup already stores, so it can't quietly hand you a corrupted photo. If something's wrong it stops and names the file.
Two things it doesn't do. Encrypted archives are detected and refused rather than half-decoded. And I've only had one archive to test against: DSM 7, unencrypted, LZ4. There's code in there for older layouts that I worked out by disassembling Synology's own binary, but it has never seen a real archive of that kind.
Which is why I'm posting. If you have a Hyper Backup archive lying around, run:
hbk <path> doctor
It reads the layout, then proves it can handle it by rebuilding a few of your real files and verifying them. Takes seconds, writes nothing, doesn't touch the archive. If it fails, that output is exactly what I need.
I also documented the format in FORMAT.md, with everything marked as verified, disassembled, or still guesswork. Nothing public seems to describe it, the magic bytes turn up zero hits anywhere. So even if the tool is useless to you, someone else can write their own reader.
I've been an engineer for 10+ years, mostly mobile native and large-scale web platforms. Claude Code did a lot of the typing on this, but I read every line that went in and the verification design is the part I insisted on.
Update: encrypted archives are now supported as of v0.2.0. Both file contents and filenames decrypt, and a wrong password is rejected instantly before any data is read.
Original title "Recover files from Synology Hyper Backup (.hbk) archives without Synology software — CLI + TUI, checksum-verified, plus a full format spec" compressed to fit within title limits.
Not mine, found via Hyper Backup Explorer drove me to reverse-engineer the .hbk format - https://old.reddit.com/r/synology/comments/1vf9xzr/hyper_bac...
From the Reddit thread cited:
---
I'm on the other side of the world from my NAS right now, and I wanted to pull the whole backup down and restore it elsewhere. Hyper Backup is great at pushing data out to S3/R2. Getting it back is where it falls apart.
Hyper Backup Explorer is the only official way to open a .hbk archive. It's GUI-only, has no CLI, and ships no Apple Silicon build. On my archive (4.8TB, around 1.1 million files) it was slow enough that I gave up and picked the format apart instead.
github.com/YordiLorenzo/hbkit (MIT license) or `pip install hbkit`
CLI plus a TUI. Point it at an archive, browse it like a file tree, tick what you want, pull it out. Runs natively on Apple Silicon and headless on Linux, extraction is parallel and resumable. Every chunk gets verified against the MD5 and CRC32 that Hyper Backup already stores, so it can't quietly hand you a corrupted photo. If something's wrong it stops and names the file.
Two things it doesn't do. Encrypted archives are detected and refused rather than half-decoded. And I've only had one archive to test against: DSM 7, unencrypted, LZ4. There's code in there for older layouts that I worked out by disassembling Synology's own binary, but it has never seen a real archive of that kind.
Which is why I'm posting. If you have a Hyper Backup archive lying around, run:
hbk <path> doctor
It reads the layout, then proves it can handle it by rebuilding a few of your real files and verifying them. Takes seconds, writes nothing, doesn't touch the archive. If it fails, that output is exactly what I need.
I also documented the format in FORMAT.md, with everything marked as verified, disassembled, or still guesswork. Nothing public seems to describe it, the magic bytes turn up zero hits anywhere. So even if the tool is useless to you, someone else can write their own reader.
I've been an engineer for 10+ years, mostly mobile native and large-scale web platforms. Claude Code did a lot of the typing on this, but I read every line that went in and the verification design is the part I insisted on.
Update: encrypted archives are now supported as of v0.2.0. Both file contents and filenames decrypt, and a wrong password is rejected instantly before any data is read.