# How Debark works

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

Source: https://debark.dev/docs/concepts/how-debark-works

---
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](/docs/get-started/interactive).

<AirGapFlowDiagram />

## Start with a baseline OS

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

```bash
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](/docs/get-started/no-target-machine) 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:

```bash
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](/docs/concepts/backends) for setup.

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

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

The [quickstart](/docs/get-started/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](/docs/guides/policy-and-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.

```bash
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`](/docs/guides/upgrades). 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.

<NextSteps
  items={[
    {
      title: 'Snapshots',
      href: '/docs/concepts/snapshots',
      description: 'Create and manage the target’s package information.',
    },
    {
      title: 'Build a bundle',
      href: '/docs/guides/building-a-bundle',
      description: 'Choose packages, output options, and signing settings.',
    },
  ]}
/>