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

# [[run]]: run a program during setup

> Reference for [[run]] in bach.toml: run a packaged program on install, first install or before removal, with exit codes that count as success.

`[[run]]` runs a program from your own files while setup installs or removes the app. Use it for what copying files cannot do, like a runtime's own installer or a driver. Add the program under `[files] source` so it is packaged.

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[[run]]
name = "Visual C++ runtime"            # "Setting up Visual C++ runtime"
file = "redist/vc_redist.x64.exe"      # a packaged .exe, relative to [files] source
arguments = "/quiet /norestart"        # the command line, passed as written
when = "first_install"
success_codes = [0, 3010]
```

| Setting | Default | Meaning |
| - | - | - |
| `file` | required | A packaged `.exe`. Setup never runs anything else, and never through a shell. |
| `name` | the file's name | What the progress label says: "Setting up {name}". Shown as written in every language. |
| `arguments` | none | The command line, passed as written. |
| `when` | `install` | `install`: after the files are in place, on a first install and on every update. `first_install`: not on updates. `uninstall`: before the files are removed. |
| `success_codes` | `[0]` | Exit codes that mean it worked. `0` always counts. Any other code stops the install with "{name} couldn't be set up (exit code N)". |
| `ignore_errors` | `false` | Go on when it fails. Not allowed with `when = "uninstall"`. |
| `component` | the file's component | Only run when this optional component is installed. |
| `timeout_minutes` | Minutes before setup ends the step and every program it started. Default `15`, 1 to 120. What the program prints is kept in the log (its last 8 KB), so a failure comes with its reason. | |
| `elevated` | `false` | Run this step with administrator rights. Windows asks once when it starts, and not at all when setup is elevated already, as with a [machine-wide install](/docs/guides/machine-wide-installs.md). Setup itself stays unelevated. Declining fails the step like any other failure. |

## How it runs

* Steps run in the order listed, as the user, in the program's own folder. Setup waits for each one.
* A program that asks for administrator rights fails to start, and that is reported like any other failure, unless the step says `elevated = true`. Setup then starts that program through Windows' administrator prompt and the rest of the install stays unelevated. Bach asks for administrator rights only when you tell it to, here or with `installer.scope = "machine"`.
* A step that runs longer than 15 minutes is ended and counts as failed.
* A failed install step stops the install with a readable sentence, and "Try again" runs it all again. Set `ignore_errors = true` to go on instead.
* A step with `when = "uninstall"` runs while the app's files are still there, and a failure never stops the removal. An app must always be removable.
* Every run, with its exit code, is in `%TEMP%\<app id>-setup.log`. `bach inspect` lists steps as `Runs`.

## Elevated steps

Some programs only work with administrator rights, like the Visual C++ redistributable's own installer:

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[[run]]
name = "Visual C++ runtime"
file = "redist/vc_redist.x64.exe"
arguments = "/quiet /norestart"
success_codes = [0, 1638, 3010]   # installed, newer already there, restart needed
when = "first_install"
elevated = true
```

An elevated step starts the program from the install folder. In a per-user install that folder can be written by the user's own programs, so use `elevated` for well-known installers, and sign them, not for anything else. `bach check` warns about that combination. Right before Windows is asked for administrator rights, setup checks the file against the size and SHA-256 recorded when the setup file was built, and does not start a program that was swapped since.

A step that runs past `timeout_minutes` is ended together with everything it started, with one exception: an elevated step in a setup that is not elevated itself (a per-user install). Windows does not let a program without administrator rights end one that has them, so setup only stops waiting, says so in the log, and the program may keep running until it ends or somebody closes it in Task Manager. The exit code of an elevated step is read the same way as for any other step. If the user declines Windows' prompt, the step fails and the log says so.

The texts `step_running` and `error_run` can be replaced under [`[text]`](/docs/reference/config/text).


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