Quickstart

This example installs jq on an offline Debian or Ubuntu machine. Replace jq with the package you need.

You can start in three ways:

• Use a snapshot: follow the walkthrough below for an existing machine.
• Choose a baseline OS: build without a snapshot by selecting Debian or Ubuntu, its release, variant, and architecture.
• Use guided questions: run debark build --interactive on the online computer. The interactive guide covers both target choices.

Prefer a graphical workflow? The desktop app can select the target, browse packages, and build this bundle on the online machine. The CLI handles snapshot capture and offline installation in either workflow.

You need the CLI installed on both computers and a USB drive or another way to transfer files. The online computer needs matching Debian or Ubuntu apt tools, or Docker / Podman. Windows and macOS builders also need a Linux helper binary; see Build backends. Installing packages on the offline machine requires root.

0. Download and install Debark

On an online Linux builder:

curl -fsSL https://debark.dev/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
debark version

For Windows or a manual installation, use the CLI downloads. Also download and verify a Linux CLI archive matching the offline target’s architecture. Extract it and transfer its debark file to that machine. From the directory containing the transferred file, run on the offline target:

sudo install -m 755 debark /usr/local/bin/debark
debark version

If both computers use Linux and the same architecture, you can transfer the builder’s ~/.local/bin/debark instead. Check the target with dpkg --print-architecture.

1. Save a snapshot on the offline machine

Run this on the machine that needs the software:

debark snapshot create --out target.tar.zst

The snapshot records installed packages and apt settings. It needs no internet or root access. Copy target.tar.zst to your online computer.

Snapshots can contain sensitive machine and repository configuration. --redact removes selected fields, but is not a complete anonymizer. See snapshot privacy.

2. Build the bundle on the online computer

Create a signing key once. Keep operator.key private and reuse it for later bundles.

debark keygen --out operator.key

From the directory containing the snapshot and key, build the bundle:

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

This downloads jq and the dependencies the offline machine is missing. The finished bundle/ folder includes the packages, their versions, and a signed list of its files.

3. Transfer the bundle and public key

Copy the whole bundle/ folder to the offline machine.

The key command also created operator.pub. Put this public key on the offline machine through a trusted route, separate from the bundle, and keep it outside the bundle folder. It lets that machine check that the bundle was signed by your key.

Copy only the public key. The private operator.key stays on the online computer. See signing keys for other signing options.

4. Preview and install on the offline machine

From the directory containing bundle/ and the provisioned operator.pub, verify the bundle and check the target’s status without root:

debark verify ./bundle --key operator.pub
debark install ./bundle --key operator.pub --status

You can also preview the apt installation:

sudo debark install ./bundle --key operator.pub --dry-run

If the plan looks right, install the packages:

sudo debark install ./bundle --key operator.pub --yes
jq --version

The installer checks the signature and file checksums before running apt. The installation uses packages in the bundle and needs no internet connection.

Carry the CLI in the bundle

For future transfers, include a trusted Linux CLI binary for the target architecture:

debark build --snapshot target.tar.zst --out ./bundle \
  --sign operator.key --embed-binary ./debark-linux-amd64 jq

After transfer, verify the bundle with a CLI you already trust before executing the embedded copy. An embedded executable cannot independently establish its own authenticity. Keep the public key provisioning step above. See the repository walkthrough for embedded binary paths and transfer options.

Next time

Add more package names to the build command or use a package list. Cached downloads are reused. Take a new snapshot after the offline machine changes.

If a command fails, start with the error message and the troubleshooting guide.