Bundle format

A bundle is a directory containing packages and the files needed to verify and install them. It can also be exported as a compressed .debark.tar.zst archive.

Most users only need debark inspect, verify, and install. This page is for browsing the files or integrating another tool.

Directory layout

A typical signed bundle has this structure. The package filenames vary with the build:

bundle/
  README.txt
  debark.manifest.json
  debark.manifest.sig
  lock.json
  snapshot.json
  evidence.json
  last-run-added.txt
  last-run-removed.txt
  last-run-unreferenced.txt
  repo/
    Packages
    Packages.gz
    Release
    pool/
      ... package .deb files ...

Optional additions are sbom.cdx.json and bin/debark-linux-ARCH.

File reference

Path	Purpose
README.txt	Human-readable summary of the target, package contents, sources, and signing status.
debark.manifest.json	File list with sizes and SHA-256 checksums, plus references to the bundle metadata.
debark.manifest.sig	Detached signature document. Absent for unsigned builds.
lock.json	Selected package versions, source information, and exact install set.
snapshot.json	The target snapshot document used by the build.
evidence.json	The bundle’s build event record.
last-run-added.txt	Paths added in the latest build.
last-run-removed.txt	Paths removed in the latest build.
last-run-unreferenced.txt	Package files present in the pool but absent from the current apt index.
repo/Packages	apt package index.
repo/Packages.gz	Compressed copy of the package index.
repo/Release	Repository metadata and index checksums.
repo/pool/	Downloaded .deb files.
sbom.cdx.json	CycloneDX package inventory, added with --sbom.
bin/debark-linux-ARCH	Target-side executable, added with --embed-binary PATH.

Package repository

repo/ is a flat apt repository: the indexes are directly inside it, instead of under a dists/ tree.

The package files are copied without modifying their contents. Their names, versions, architectures, sizes, and checksums are recorded in lock.json.

The repository can contain more files than the normal install set requests, particularly after repeated builds into the same folder. The lock’s install entries select the intended packages. Refresh a bundle explains the change lists and leftover files.

Manifest and signature

The signature covers the manifest’s canonical JSON representation. The manifest, in turn, records checksums for the bundle’s payload files. The manifest and detached signature are not ordinary entries in their own file list.

debark verify checks these relationships before a normal installation. Do not edit the files inside a finished bundle or save reports into it; unexpected or changed files can fail verification.

The generated apt Release file is unsigned. If you use the repository directly with apt, Debark’s verification does not run automatically. See How verification works.

Lock and snapshot

The lock records the packages selected for this target. Its install list uses apt’s exact-version form:

name:architecture=version

snapshot.json describes the target state used to make those selections. It is a JSON document, not another copy of the snapshot archive.

For package fields and their meanings, see Package versions and the lock file.

Archive form

To export one compressed file:

debark build --snapshot target.snapshot.tar.zst \
  --tar packages --sign operator.key jq

This writes packages.debark.tar.zst. Bundle commands accept the archive directly:

debark verify packages.debark.tar.zst --key operator.pub
debark inspect packages.debark.tar.zst

The archive uses the same bundle layout. It does not need a different key or verification process.

Schemas and format details

The source repository publishes JSON schemas for the manifest, signature, lock, and snapshot.

Use those schemas for integrations that need individual fields. JSON output covers command reports and events.