# Bundle format

Find the package repository, install plan, signatures, and reports inside a bundle.

Source: https://debark.dev/docs/reference/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:

```text
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](/docs/operate/refreshing) 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](/docs/trust/trust-model).

## Lock and snapshot

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

```text
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](/docs/concepts/lockfile).

## Archive form

To export one compressed file:

```bash
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:

```bash
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](https://github.com/inferops/debark/blob/main/api/schema/manifest.v1.schema.json), [signature](https://github.com/inferops/debark/blob/main/api/schema/signature.v1.schema.json), [lock](https://github.com/inferops/debark/blob/main/api/schema/lock.v1.schema.json), and [snapshot](https://github.com/inferops/debark/blob/main/api/schema/snapshot.v1.schema.json).

Use those schemas for integrations that need individual fields. [JSON output](/docs/reference/json-output) covers command reports and events.

<NextSteps
  items={[
    {
      title: 'Package versions and the lock file',
      href: '/docs/concepts/lockfile',
      description: 'Read the selected versions and package sources.',
    },
    {
      title: 'SBOM and build records',
      href: '/docs/trust/sbom-and-evidence',
      description: 'Export an inventory and keep reports.',
    },
  ]}
/>