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

# [[services]]: install Windows services

> Reference for [[services]] in bach.toml: install a Windows service with its start type and account, have it stopped during updates and deleted on removal.

`[[services]]` installs Windows services: an agent, a sync engine, a local server. A service runs without anyone signed in and starts with Windows.

A service is installed with administrator rights, so `[[services]]` needs [`installer.scope = "machine"`](/docs/guides/machine-wide-installs). In a per-user config, `bach check` stops with a sentence that says so.

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[installer]
scope = "machine"

[[services]]
name = "HelloAgent"                  # what `sc query HelloAgent` knows it by
display_name = "Hello Agent"         # what Services lists; the name by default
description = "Syncs Hello in the background."
file = "agent/agent.exe"             # a packaged .exe; the app's own program by default
arguments = "--service"
start = "auto"                       # auto (default), delayed, manual or disabled
account = "local_service"            # local_service (default), network_service or local_system
restart_on_failure = true            # the default
```

| Setting | Default | Meaning |
| - | - | - |
| `name` | required | The service's name: letters, digits, `.`, `-` and `_`, up to 64 characters, not starting with `.`. |
| `display_name` | the name | The name Services lists, up to 256 characters. |
| `description` | none | One line shown in Services, up to 1000 characters. |
| `file` | `app.executable` | The service's program: a packaged `.exe`, relative to `[files] source`. |
| `arguments` | none | The command line after the program, passed as written. |
| `start` | `auto` | `auto` starts it with Windows, `delayed` a little after the rest, `manual` when something asks for it, `disabled` never. |
| `account` | `local_service` | `local_service` has few rights on the computer and none on the network. `network_service` has the computer's identity on the network. `local_system` has full rights: use it only for a service that has to manage the computer. Setup never takes a password, so no other account is possible. |
| `restart_on_failure` | `true` | Windows starts the service again a minute after it stops by itself, up to three times; the count is forgotten after a day. |

## What setup does

**1. First install**

Creates each service, then starts it when `start` is `auto` or `delayed`. A service that doesn't reach the running state in 30 seconds fails the install, and the install is undone: the services setup made are deleted again.

**2. Update**

A running service holds its program, so setup stops it (up to 30 seconds) before the files are swapped, brings its definition up to date and starts it again, if it was running or `start` says so. A service the new version no longer lists is stopped and deleted. If anything fails after the files were placed, the earlier version's files and services come back.

**3. Removal**

Stops each service, deletes it, then deletes the files. A service that won't stop or delete is logged; removal itself never stops for it.

## What to know

* Setup only changes a service it can prove is its own: one whose program is in the install folder. If a service with that name already exists and starts something else, the install stops with "{name} couldn't be set up (exit code exists)" and the log names the program. Pick a name that is yours.
* A setup file with `[[services]]` can't be an [MSI](/docs/guides/msi.md): `bach build --msi` stops and says so.
* `bach inspect` lists each service as `Service`, and [`bach diff`](/docs/reference/cli/diff) shows one that was added, removed or changed.
* Pair it with [`[[firewall]]`](/docs/reference/config/firewall) when the service listens for connections.
* `--preview` pretends, like every other step.


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