> ## 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.

# Safety rules: what Bach promises and how it keeps them

> The promises behind every Bach setup file: paths cannot escape the install folder, data is deleted only on request, administrator rights only on request, no foreign keys.

Bach writes installers that other people run on their computers, so its safety rules are promises. A report that breaks one of them is treated as a vulnerability. This page lists the rules and where they show up in your day-to-day use.

## The rules

> [accordion] Packaged paths cannot leave the install folder
>
> Packaged paths are relative and can never contain `..`, so a setup file cannot write outside its install folder. Paths from a payload are untrusted and always checked before anything touches the disk.

> [accordion] Data folders stay inside the user's profile
>
> Data folders must sit inside the user's profile (`%APPDATA%`, `%LOCALAPPDATA%`, `%USERPROFILE%`) and name a folder of their own: never `Documents`, `Desktop`, `AppData` or another profile folder, never anything inside `.ssh` or `Microsoft`, never developer tool folders, browser or chat profiles of other programs or `NTUSER.DAT`, and never the install folder or a folder that contains it. They are deleted only when the user ticks the box, and the removal window lists the real folders under it.

> [accordion] The uninstaller removes only what it installed
>
> The `bach-setup.exe` runtime that ends up in every setup file is downloaded over https only and checked against a SHA-256 built into a released `bach`. A cached copy is checked again before use, and the cache never falls back to the shared temp folder. `bach check` and `bach build` refuse a source folder that holds secrets such as `.env` files, private keys, `.git` or `bach.toml`, (and many more credential files, and keys or tokens inside small text files) unless `files.allow_secrets` names them. A first install into a folder that already holds files of the same names warns in the window, naming them, and a silent run refuses unless it gets `--overwrite`. The uninstaller keeps a file that was changed after setup wrote it. It deletes only files listed in its manifest, inside a folder that is verifiably the app's install. It refuses a folder that does not hold the app, and an update only cleans up after an earlier install of the same app id.

> [accordion] Administrator rights only when the app says so
>
> By default, setup never asks for administrator rights and never writes outside the user's own folders and `HKCU`. It asks once, through Windows' own prompt, only when the app sets `installer.scope = "machine"`, marks a [`[[run]]`](/docs/reference/config/run) step `elevated = true` or allows an elevated [`[[migrate]]`](/docs/reference/config/migrate). Before it writes into a machine-wide install folder, and again before an elevated update or removal, setup reads the folder's access list and refuses one that Users, Authenticated Users or Everyone may change, or that Administrators, SYSTEM and TrustedInstaller do not own. A machine-wide uninstaller removes itself from where it is instead of from a copy in the user's temp folder, and setup files load only System32's DLLs, never one planted next to the setup file. See [machine-wide installs](/docs/guides/machine-wide-installs.md).

> [accordion] The manifest is checked again at start
>
> The manifest is validated when a setup file starts, so a damaged or edited file fails with a sentence instead of misbehaving. The archive is also checked against the SHA-256 recorded at build time, and every unpacked file against the size and SHA-256 the manifest records for it. An archive that lists a path twice, or lacks a file the manifest names, is refused before anything is replaced.

> [accordion] Keys are checked first, and kept sealed
>
> An app with [`[access]`](/docs/reference/config/access) checks the key before anything on the computer is touched. Files are encrypted with Argon2id and ChaCha20-Poly1305 in authenticated chunks, so a changed or cut-short setup file fails instead of unpacking something wrong. A setup file that asks for unreasonable key-derivation costs is refused. The key kept for updates is sealed with the Windows Data Protection API for that user, and is sent only to the host it was meant for.

> [accordion] Run steps are the app's own files
>
> A [`[[run]]`](/docs/reference/config/run) step starts only a packaged file inside the install folder, as the user unless it says `elevated = true`, never through a shell. An elevated program is checked against its recorded SHA-256 right before Windows is asked for administrator rights. Setup waits for a step and ends it after 15 minutes (an elevated step in a per-user setup can only be waited out, not ended). A failing step before removal never stops the removal.

> [accordion] Registry, variables and menu entries stay the app's own
>
> [`[[registry]]`](/docs/reference/config/registry) keys stay below `Software\<your key>`, never `Classes`, `Policies`, Bach's, or any key of Microsoft, Google or Mozilla. Variables must start with the app id unless `allow = true`, and variables that inject code or redirect traffic, such as `COR_PROFILER` or `HTTPS_PROXY`, are never set. Values and [`[[env]]`](/docs/reference/config/env) variables are removed only while they still hold what setup wrote. [`[[context_menu]]`](/docs/reference/config/context-menu) entries carry the `BachApp` mark.

> [accordion] Migration runs only an entry's uninstall command
>
> [`[[migrate]]`](/docs/reference/config/migrate) runs the uninstall command of the Settings › Apps entry you name, never through a shell and never so that it stops the install. An elevated setup ignores per-user entries, and a machine-wide old uninstaller runs elevated only from Program Files or the Windows folder. Windows' folders come from Windows, not from environment variables.

> [accordion] Signing runs only when you ask
>
> A [`[signing]`](/docs/reference/config/signing) section names a program, so `bach build` runs it only with `--sign` or `BACH_SIGN=1`. A `bach.toml` from somewhere else never runs a program just because it was built.

> [accordion] A patch is only good for the version it was made for
>
> An [update patch](/docs/guides/updates.md#update-patches) checks the size and SHA-256 of every file it leaves out before it places anything. If one differs, nothing is touched and the app takes the full setup file instead.

> [accordion] Mirrors cannot widen trust
>
> The first update feed that answers decides the newest version. A mirror can only offer another place to download the same file, with the same version and SHA-256.

> [accordion] PATH is edited as raw text
>
> Exactly one entry is added or removed, the value's type (`REG_EXPAND_SZ`) is kept, and nothing is written when there is nothing to change. The rest of `PATH` is kept byte for byte.

> [accordion] Foreign registry keys are never touched
>
> Registry keys Bach creates for link schemes and file types carry a `BachApp` mark. Keys without it belong to another program and are never changed or deleted.

> [accordion] No Visual C++ redistributable needed
>
> The C runtime is linked in, so setup files start on a fresh Windows without the Visual C++ redistributable.

## Rules the config checker enforces

Fix the setting `bach check` names rather than working around it:

* Data folders must start with `%APPDATA%`, `%LOCALAPPDATA%` or `%USERPROFILE%` plus the app's own folder.
* The source folder cannot contain symbolic links or a top-level `uninstall.exe`.
* Schemes like `http` and extensions like `.exe` are refused.
* `[text]` keys must be real text names.
* The update feed and requirement downloads must be https.

## Updates are verified

A self-update downloads over https only. The file is checked against the feed's SHA-256 and must be a setup file for the same app id and the version the feed names, so a wrong or tampered file is never run. A downloaded file waiting in the update folder is checked again right before it runs, never trusted because of where it is.

The SHA-256 comes from the same place as the file, so it guards against damage and a wrong file, not against someone who controls the release page. Signing the setup file ([Signing](/docs/guides/signing.md)) is what lets Windows show your name.

Automatic updates are a per-user scheduled task that needs no administrator rights, and an update only installs while the app is closed. A machine-wide app has no background updates, because its update has to write to Program Files. A power cut in the middle of an update is undone by the next run, using a journal that can only act on paths inside the install folder.

## What is not a vulnerability

Bach packages what you give it. A setup file is as trustworthy as the app inside, so a developer putting something harmful into their own `bach.toml` or app files is not a Bach vulnerability. See the [security policy](/docs/resources/security.md) for how to report a problem.


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