# Quickstart

Download a package and its dependencies on an online computer, then install them on your offline machine.

Source: https://debark.dev/docs/get-started/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](/docs/get-started/no-target-machine)
  by selecting Debian or Ubuntu, its release, variant, and architecture.
- **Use guided questions:** run `debark build --interactive` on the online computer.
  The [interactive guide](/docs/get-started/interactive) covers both target choices.

Prefer a graphical workflow? The [desktop app](/docs/get-started/desktop) 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](/docs/get-started/installation) 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](/docs/concepts/backends). Installing packages on the offline machine requires root.

## 0. Download and install Debark

On an online Linux builder:

```bash
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](/download#cli).
Also download and [verify](/docs/trust/release-downloads) 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:

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

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

## 2. Build the bundle on the online computer

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

```bash
debark keygen --out operator.key
```

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

```bash
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](/docs/trust/signing) 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:

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

You can also preview the apt installation:

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

If the plan looks right, install the packages:

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

```bash
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](https://github.com/inferops/debark/blob/main/docs/quickstart.md#carry-the-cli-in-the-bundle)
for embedded binary paths and transfer options.

## Next time

Add more package names to the build command or use a [package list](/docs/guides/building-a-bundle).
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](/docs/operate/troubleshooting).

<NextSteps
  items={[
    {
      title: 'Use the desktop app',
      href: '/docs/get-started/desktop',
      description: 'Browse packages and prepare bundles with the GUI.',
    },
    {
      title: 'Add vendor .deb files',
      href: '/docs/guides/vendor-debs',
      description: 'Include packages from a download URL or local file.',
    },
    {
      title: 'Prepare updates',
      href: '/docs/guides/upgrades',
      description: 'Download upgrades for the offline machine.',
    },
  ]}
/>