Build 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. For a guided start, follow the quickstart or use the desktop app.

Build from package names

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 lists exact baseline IDs and architecture names.

See building without a snapshot for the base workflow.

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

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:

# Command-line tools
jq
tree
ripgrep

Then build from that file:

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.

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:

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

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

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.

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

For apt errors, missing container tools, or failed downloads, see troubleshooting.