Debark
Get Debark
Browse docs

How Debark works

How a snapshot or baseline OS becomes a package bundle, and what happens when you install it offline.

ExplanationUpdated

On this page

Debark uses a snapshot or a baseline OS to work out which packages the target needs. It downloads them on an online computer. You copy the resulting bundle over and install it with apt.

The CLI handles every step. The desktop app helps you choose packages and build the bundle on your online Linux computer.

The CLI can also ask for these choices: run debark build --interactive to follow the guided build.

Build from a snapshot or baseline OS, then install offline.Start with either a snapshot captured on the offline machine or a baseline OS chosen on the online computer. The baseline path requires no captured snapshot. The online builder downloads the packages for the selected target and creates a bundle. Copy the bundle to the offline machine, verify its files and signature, then install it.Offline targetair gapOnline builderCapture the targetdebark snapshot createactual packages and apt settings12target.snapshot.tar.zstcopy to the online computerOr choose a baseline OSdebark build --baserelease, variant, architectureDownload and builddebark buildpackages for the selected target3bundle/packages, versions, checksumsCheck, then installdebark verifythendebark installverify before installing packages4

Start with a baseline OS

Choose a stock release, installation variant, and architecture on the online computer. For example, using an existing signing key:

debark build --base ubuntu:24.04/minimal --arch amd64 \
  --out ./bundle --sign operator.key jq

No snapshot from the offline machine is required. The baseline supplies an assumed installed package set. See Build with a baseline OS for the choices and how to check the assumptions on the target.

Snapshot the target

A snapshot records the offline machine’s installed packages, apt sources, settings, and architecture. It contains package information, not the installed software or your personal files.

Run this on the offline machine, then copy the file to the online computer:

debark snapshot create --out target.tar.zst

Use this starting point when you want the machine’s actual installed package set and settings. Creating a snapshot needs no network or root access. Take a new snapshot when installed packages or apt settings change.

Download the missing packages

On the online computer, Debark gives apt the captured or baseline package state in a temporary working directory. This lets apt work out what the offline machine needs without changing the online computer’s apt configuration.

apt runs locally when the systems are compatible, or in a Docker / Podman container for the target release. See build backends for setup.

To download jq and sign the bundle with a key you already created:

debark build --snapshot target.tar.zst \
  --out ./bundle --sign operator.key jq

The quickstart includes key creation and file transfer steps.

Assemble the bundle

The bundle contains:

  • A repo/ folder with the .deb files and an apt index.
  • lock.json, recording the package versions to install.
  • A manifest listing the files and their checksums, plus a signature when you sign the build.
  • A README.txt summary and records of the build.

Before finishing, Debark simulates installation using the bundle as the only package source. This checks for missing dependencies against the snapshot. It doesn’t run package installation scripts, so packages that download extra software during setup still need attention. Use doctor to check for common problems.

Verify, then install

Copy the entire bundle to the offline machine. Its public signing key should already be available there through a trusted route, outside the bundle folder.

debark verify ./bundle --key operator.pub
sudo debark install ./bundle --key operator.pub --dry-run
sudo debark install ./bundle --key operator.pub

Verification checks the signature and file contents. Installation repeats those checks, then uses apt to install the selected versions from the bundle.

A normal install applies the requested package set. To include the additional upgrade set, use --upgrade. The machine’s apt sources are unchanged unless you explicitly use --keep-source.

Limits

Debark handles Debian and Ubuntu apt packages. Snap, Flatpak, language-package registries, and OS images are outside this workflow. A successful dependency check also depends on the snapshot still matching the offline machine.