# Build a bundle

Choose packages, use a saved list, and create a signed folder or archive for an offline machine.

Source: https://debark.dev/docs/guides/building-a-bundle

---
Run builds on your online computer. You need either a target snapshot or a baseline OS choice,
apt or a container backend, and enough disk space for the downloads.

The examples below use `operator.key`, created with
[`debark keygen`](/docs/trust/signing). For a guided start, follow the
[quickstart](/docs/get-started/quickstart) or use the [desktop app](/docs/get-started/desktop).

## Build from package names

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

This downloads the requested packages and dependencies missing from the snapshot. The result
is a `bundle/` folder you can copy to the target.

Use exactly one target option:

- `--snapshot FILE` uses the package state captured from a real machine.
- `--base ID` assumes a stock system, such as `ubuntu:24.04/minimal`.
  Use `--arch` with a base if needed; a snapshot already records its architecture.

The [supported systems table](/docs/get-started/supported-systems#baseline-os-list) lists exact
baseline IDs and architecture names.

See [building without a snapshot](/docs/get-started/no-target-machine) for the base workflow.

For example, using a baseline OS instead of a captured snapshot:

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

The baseline assumes which packages the target already has. Preview the bundle on the actual
machine before installing it.

## Use a package list

Save one entry per line in `packages.txt`:

```text
# Command-line tools
jq
tree
ripgrep
```

Then build from that file:

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

Blank lines and lines starting with `#` are ignored. You can repeat `--list` to combine
several files, and add more package names on the command line.

## Accepted inputs

| Input         | Example                            | Meaning                                      |
| ------------- | ---------------------------------- | -------------------------------------------- |
| Package name  | `jq`                               | Select from the target’s apt sources         |
| Exact version | `name=version`                     | Request an available version explicitly      |
| Download URL  | `https://vendor.example/agent.deb` | Download a .deb and resolve its dependencies |
| Local file    | `./vendor/agent.deb`               | Include a .deb already on disk               |

The URL above is a placeholder; replace it with the vendor’s actual download URL.

Use `--local-dir ./vendor` to include .deb files from a directory. This flag is repeatable
and does not scan subdirectories. The prefixes `apt:`, `url:`, and `file:` can make an
input’s type explicit, for example `file:./builds/agent-package`.

For URL checksums and publisher checks, see [vendor packages](/docs/guides/vendor-debs).

## Recommended packages

By default, the build follows the snapshot’s `Install-Recommends` setting. Use
`--no-recommends` to exclude recommended packages, or `--recommends` to include them.
You cannot combine the two flags.

Required dependencies are still included. Omitting recommendations can reduce size but may
leave out plugins or other features you expect.

## Choose a folder or archive

`--out PATH` writes a folder. If you omit both output options, it defaults to `./bundle`.

Use `--tar NAME` for a single compressed archive:

```bash
debark build --snapshot target.tar.zst --tar monthly-tools \
  --sign operator.key jq tree
```

This creates `monthly-tools.debark.tar.zst`. Do not combine `--tar` with `--out`.
Both formats contain the same kinds of files, and the CLI can read either.

## Check the result

```bash
debark verify ./bundle --key operator.pub
debark inspect ./bundle
debark doctor ./bundle
```

Verification checks the signature and contents. Inspection shows package versions and warnings.
Doctor looks for common offline installation problems.

A failed build may leave an older bundle or partial output in the destination. Check the exit
code before transferring it. In particular, exit 3 means the result is incomplete; fix the named
inputs and rebuild.

## Build interactively

```bash
debark build --interactive
```

Choose a snapshot or baseline OS, enter packages one per line, and review the output, signing,
upgrade, and SBOM options. The CLI saves entered packages to a list file and prints a command
you can reuse. See the [interactive CLI guide](/docs/get-started/interactive).

This requires a terminal and cannot be combined with `--json` or `--json-events`.

For apt errors, missing container tools, or failed downloads, see
[troubleshooting](/docs/operate/troubleshooting).

<NextSteps
  items={[
    {
      title: 'Sign a bundle',
      href: '/docs/trust/signing',
      description: 'Set up the key used in these examples.',
    },
    {
      title: 'Install a bundle',
      href: '/docs/operate/installing',
      description: 'Copy, preview, and install the result.',
    },
    {
      title: 'Prepare updates',
      href: '/docs/guides/upgrades',
      description: 'Include upgrades for installed packages.',
    },
  ]}
/>