> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bach builds Windows installers from one bach.toml with the bach command: bach init, bach check, bach preview, bach build. Installs are per user and need no administrator rights by default. installer.scope = "machine" installs for every user after one Windows prompt. On Windows, run setup files with Start-Process -Wait -PassThru in PowerShell, and give signtool arguments that start with the word sign.

# [access]: ask for a key and encrypt the files

> Reference for [access] in bach.toml: an access key the installer asks for, encrypted packaged files, private updates, and what this does and does not protect.

`[access]` makes an app private. The installer asks for an access key before it does anything, the packaged files are encrypted with that key, and updates can send the key to a server that checks it. The key is **never written in `bach.toml`**: the build reads it from an environment variable or a file.

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[access]
get_key_url = "https://example.com/buy"   # optional: adds a "Get a key" button to the key page
```

```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
bach key --out key.txt          # writes one key (try --count 100 for a batch)
bach build --key-file key.txt   # every line of the file is a key that opens the setup file
```

`--key-file` works in every shell. The build can also read the key from the environment variable, which PowerShell sets with `$env:BACH_ACCESS_KEY = "..."`, cmd with `set BACH_ACCESS_KEY=...` and bash with `BACH_ACCESS_KEY=... bach build`. See [`bach key`](/docs/reference/cli/key).

```console theme={"theme":{"light":"github-light","dark":"github-dark"}}
$ bach build
The files are encrypted with the access key.
Wrote dist\Hello-Setup-1.4.0.exe (8.7 MB)
```

| Setting | Default | Meaning |
| - | - | - |
| `encrypt` | `true` | Encrypt the packaged files with the key. |
| `key_env` | `BACH_ACCESS_KEY` | The environment variable the build reads the key from. `bach build --key-file FILE` reads every line of a file instead: each is a key, blank lines and lines starting with `#` are skipped, at most 1000. |
| `get_key_url` | none | An `https` page where people get a key. The key page shows a "Get a key" button that opens it. |
| `send_key` | `true` with `[updates]` | Send the key as `Authorization: Bearer <key>` with every request to the host of `[updates] feed` (the feed, and a download on that same host, redirects from it included), so a private server can refuse anyone without one. Mirrors and downloads on other hosts never get it. Needs `[updates]`. |

A key is 8 to 128 characters: letters, digits and `- _ . ~ + / = :`. [`bach key`](/docs/reference/cli/key) makes random 100-bit keys. Put a key per customer in one key file (`bach key --count 100 --out keys.txt`) and every one of them opens the same setup file on its own, or build one setup file per key.

## One key per customer

The files are locked with a random key of their own, and the setup file holds that key once per access key, each copy locked with that access key (a "slot"). The archive is stored once, not once per customer. A silent install with any one of the keys works, and a key that is not in the file does not.

To take a customer's key away, build again without their line and hand out that setup file. Copies already handed out keep working with the keys they were built with, so a revoked key still opens an old copy. Pair this with `send_key` and a server that refuses the revoked key, so updates stop too.

Opening takes about a third of a second per slot tried. With 17 keys or more, every slot also carries a one-byte tag (a fast hash of the key) that lets setup skip most of them, so a key opens in about one try even with a thousand slots. The tag is something somebody who guesses keys offline can use to rule candidates out, which only helps against keys that are easy to guess, so a setup file with fewer keys has no tags at all. Use the random 100-bit keys `bach key` makes. Setup files made before slots, with one key for the whole file, still open.

`[access]` with `encrypt = false` and `send_key = true` encrypts nothing and only passes the key to your server. With both off the section does nothing, and `bach check` says so.

## What the user sees

The window asks for the key on its own page, after any requirements and before the license. The user types it or pastes it. A wrong key shows "That key doesn't fit" and nothing on the computer is touched.

A silent install takes the key from `--key-file FILE` or the `BACH_ACCESS_KEY` environment variable, never from an argument, because other programs can read arguments. Without a key it exits with code `2`. With a wrong key it exits with code `1`.

```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
Start-Process .\Hello-Setup-1.4.0.exe -ArgumentList '--silent', '--key-file', 'key.txt' -Wait -PassThru
```

See [Silent installs](/docs/guides/silent-installs.md) for why `Start-Process -Wait -PassThru` is used.

## What is kept on the computer

After a successful install of an app with `[updates]`, the key is kept so updates can send it and open protected setup files. It is sealed with the Windows Data Protection API for that Windows user and the app's id, and stored under `HKCU\Software\Bach\Access`. Another user, or the same data copied to another computer, cannot read it. Removing the app deletes it. A program running as the same user can still ask Windows to unseal it, as with a browser's saved passwords.

The updater sends the key only to the host of the main update feed, which is in the signed setup file. A feed can name any download link, so a download or a mirror on another host never gets the key, and a redirect to another host, like a storage bucket's signed link, is followed without it. Put your private download on the same host as the feed.

## How the files are protected

Each access key goes through Argon2id (64 MiB of memory, 3 passes) into a ChaCha20-Poly1305 key that unlocks its slot, which holds the files' key. The archive is encrypted in 64 KiB chunks. Each chunk is authenticated and the last one is marked, so a changed, reordered or cut-short setup file fails with a sentence instead of unpacking something wrong. A setup file that asks for more memory than 256 MiB, or names an unknown scheme, is refused.

> [!WARNING]
>
> Know what this does not do. File names and sizes stay visible, because the manifest lists them. And once an app is installed, its files are ordinary files on the user's disk. The key protects the setup file and the download, not a running app. For protection after install, check a license inside your app.

For the strongest private distribution, combine it with the [online installer](/docs/reference/config/installer.md#online-and-offline-installers): the files never sit in the installer, and the download itself is behind your server's check.

See [Private updates](/docs/guides/updates.md#private-updates) for the server side.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.