# BotBus for Windows

> Install BotBus on Windows with one PowerShell command: no administrator rights, runs in the background after you sign in with a tray icon, and after pairing lets you check on and approve Codex and Claude Code tasks from your phone.

Canonical: https://botbus.io/en/docs/install-windows  
Updated: 2026-09-30

Installs on your Windows PC and runs in the background after you sign in, with a BotBus icon in the notification area. Check on and approve Codex, Claude Code, and other agent tasks on that PC from your phone and watch. Everything is end-to-end encrypted, just like the Mac version.

```powershell
irm https://botbus.io/install.ps1 | iex
```

Version **1.0.7** · released **2026-10-09** · Windows 10 / 11 (ARM PCs need Windows 11)

## One command to install, then scan to pair

On the PC you want to watch from your phone, open PowerShell with the Windows account you normally use and run the install command. No administrator rights needed.

### Install

```powershell
irm https://botbus.io/install.ps1 | iex
```

#### What the install script does

1. Downloads the version listed on this page. It’s an x64 program: Windows 11 on ARM PCs runs it through its built-in emulation, while ARM PCs on Windows 10 can’t install it.
2. Checks the download against the SHA-256 in the release manifest, and stops without installing anything if it doesn’t match.
3. Extracts it to `%LOCALAPPDATA%\Programs\BotBus` and adds that folder to your user PATH (so `botbus` works in any terminal you open afterwards). System folders are left alone.
4. Runs `botbus up`: creates a “BotBus” task in Task Scheduler that starts it in the background every time you sign in to Windows, then opens the BotBus icon in the notification area, which also starts when you sign in.
5. If Claude Code is on this PC (`%USERPROFILE%\.claude` exists), installs BotBus’s Claude Code hooks so Claude sessions started on the PC also show up on your phone; uninstalling removes them.
6. Shows a pairing QR code in the PowerShell window and waits for you to scan it with your phone.

When it isn’t run in an interactive terminal (remote scripts, automated deployment), the script only starts the background process and doesn’t show a pairing code, so a pairing link carrying a key never ends up in a log. Afterwards, right-click the tray icon on that PC and choose to pair a phone, or run `botbus pair` in a terminal.

### Pair your phone

- Scan the QR code in the PowerShell window with BotBus on your phone. The code is drawn with characters, so make the window bigger if it doesn’t fit.
- You can also right-click the BotBus icon in the notification area and choose to pair a phone, then scan the code in the window that opens.
- If you can’t scan it, send the pairing link from that window to your phone and open it there. The link carries an encryption key: only pass it between your own devices, and don’t paste it into chats or tickets.
- Pairing codes expire; if one has, run `botbus pair` again (or reopen it from the tray menu).
- Already paired and want to add another phone? Run `botbus pair` too; it creates an invitation.

## The tray icon and the botbus command

The tray icon and the `botbus` command both run as your user and talk to the background process over a local channel only you can use.

### Tray icon

The BotBus icon in the notification area changes color with the connection status. Left-click it (or open BotBus from the Start menu) for the main window: it lists the agents on this PC, each with “open desktop app” and “open in terminal” buttons, or a way to install it if it’s missing. Claude Code and Codex opened from here use the same program and sign-in as the BotBus background process (Claude Code gets its hooks installed first), so sessions you start on the PC show up on your phone. The gear in the top-right corner opens the settings window.

Its right-click menu has:

- Open BotBus (the main window);
- the current version, connection status, and how many tasks are running or waiting for you; when an update is out, one click installs it;
- the agents on this computer: each has a submenu listing the sessions started from your phone (click one to continue it in a terminal), a switch to turn it on or off, “open in terminal” (to sign in), and its settings;
- Add Agent: every agent BotBus supports, with a website and a one-line install command for the ones you don’t have yet; click “Re-detect” after installing. If no agent is found at all, the tray reminds you once;
- paired phones (click one to open its settings page, where you can remove it), and pairing a phone;
- Settings: the same settings window as on the Mac (connection status, paired devices, each agent, Add Agent, the folder for new projects, starting at sign-in, checking for updates);
- opening the log (the tray looks after the background process: if it isn’t running, the tray starts it when the tray launches or when you open the menu);
- quitting the tray icon (the background process keeps running; run `botbus tray` to bring the icon back).

The menu is in Chinese for now. Windows may tuck new icons behind the “Show hidden icons” arrow; drag it onto the taskbar to keep it visible.

### Commands

| Command | What it does |
| --- | --- |
| `botbus up [--no-pair]` | Sets up and starts the background process and tray icon that launch when you sign in; shows a pairing QR code if you haven’t paired yet. Run it again after replacing the program to switch the background process to the new version |
| `botbus pair` | Pairs a phone; if already paired, creates an invitation for another phone |
| `botbus status [--json]` | Connection status, paired phones, detected agents, and whether a new version is available |
| `botbus agents` | Lists detected agents; `botbus agents enable|disable <kind>` turns one on or off (for example `claude` or `codex`; ACP agents are `acp:<id>`) |
| `botbus phones` | Lists paired phones; `botbus phones remove <id>` removes one |
| `botbus unpair` | Dissolves the whole pairing group; every phone has to scan again |
| `botbus logs [-f]` | Shows the background log, `%LOCALAPPDATA%\BotBus\daemon.log` |
| `botbus tray` | Opens the BotBus icon in the notification area |
| `botbus open` | Opens the main window (the agents on this PC and buttons to open them) |
| `botbus settings` | Opens the settings window |
| `botbus down` | Stops the background process and keeps your credentials; it still starts again the next time you sign in |
| `botbus update` | Updates to the latest version |
| `botbus uninstall [--purge]` | Removes the background process, tray icon, and program; `--purge` also deletes credentials and data |
| `botbus --version` | Shows the version |

The `botbus share`, `link`, `list`, and `mcp` commands that agents use in phone tasks work the same as on the Mac. The Windows version doesn’t support development previews (`botbus preview`) or controlling the PC’s screen yet.

### Update

```powershell
botbus update
```

- Downloads the new version for your architecture from the botbus.io release manifest, checks its SHA-256 and Ed25519 signature, replaces the program, restarts the background process and tray icon, and confirms the new version is the one running.
- `botbus status` tells you when a new version is out (it checks once a day).
- You can also rerun the install command: after installing the new program, the `botbus up` it runs switches the background process to the new version.

### Uninstall

```powershell
botbus uninstall
```

You can also find BotBus under Windows Settings → Apps → Installed apps and choose Uninstall; it does the same.

Stops the background process, deletes the “BotBus” scheduled task, the tray icon’s autostart, and BotBus in the Start menu and in Installed apps, removes BotBus’s hooks from Claude Code’s settings, and takes the program folder off your user PATH and deletes it. Your credentials stay in `%LOCALAPPDATA%\BotBus`, so you won’t have to pair again after reinstalling.

```powershell
botbus uninstall --purge
```

Also deletes credentials and data (`%LOCALAPPDATA%\BotBus`). The PC then shows as offline on your phone, and you can remove it there.

## Troubleshooting

### Common situations

- **“botbus” is not recognized** — PATH changes only reach terminals opened afterwards. Close and reopen PowerShell, or run `& "$env:LOCALAPPDATA\Programs\BotBus\botbus.exe"` directly.
- **Claude Code or Codex doesn’t show up on the phone** — The background process uses the PATH from when you ran `botbus up`. Install the agent first, make sure `Get-Command claude` (or `codex`) finds it in a new terminal, then run `botbus up` again. `botbus agents` lists the agents it found.
- **Claude Code sessions started on the PC don’t show up on the phone** — `botbus up` installs the hooks when `%USERPROFILE%\.claude` exists. After installing Claude Code, run `botbus up` again. Sessions started from the phone don’t depend on hooks.
- **Can’t find the tray icon** — Look behind the “Show hidden icons” arrow in the notification area first. If you quit the tray icon, run `botbus tray`.
- **The PC doesn’t allow scheduled tasks** — Some work PCs don’t let regular users create scheduled tasks. `botbus up` then starts the background process directly, but you’ll need to run `botbus up` again after signing in next time.
- **The background process won’t start or its status looks wrong** — Check `botbus logs` (add `-f` to follow it). `botbus status` also reports reasons such as failing to read credentials.
- **The log shows <private> instead of content** — By default the log redacts strings like task content and paths. To debug, run `botbus down`, then temporarily run it in the foreground with `$env:BOTBUS_LOG_PRIVATE = '1'; botbus daemon`; press Ctrl-C when done and run `botbus up`. That log contains task content, so check it before sharing.

### Manual install

If you’d rather not pipe a script, you can download, verify, and extract it yourself. The files for this version (the same package for x64 and ARM PCs):

| Architecture | File | Size | SHA-256 |
| --- | --- | --- | --- |
| x64 | [`botbus-1.0.7-windows-x86_64.zip`](https://botbus.io/downloads/windows/botbus-1.0.7-windows-x86_64.zip)  
[.sha256](https://botbus.io/downloads/windows/botbus-1.0.7-windows-x86_64.zip.sha256) | 52.8 MB | `9bfca38cd7678e5d920169c3121fcbfb2fbc13a31e98e6eda8359c6073be4e99` |

```powershell
$Version = '1.0.7'
$File = "botbus-$Version-windows-x86_64.zip"
Invoke-WebRequest -UseBasicParsing "https://botbus.io/downloads/windows/$File" -OutFile $File
(Get-FileHash $File -Algorithm SHA256).Hash.ToLower()
Expand-Archive $File "$env:LOCALAPPDATA\Programs\BotBus" -Force
& "$env:LOCALAPPDATA\Programs\BotBus\botbus.exe" up
```

The SHA-256 printed by the fourth line should match the table above. A manual install doesn’t change PATH: to use `botbus` from any terminal, add `%LOCALAPPDATA%\Programs\BotBus` to your user PATH. Release packages also carry an Ed25519 signature, which `botbus update` verifies.

### Where files live

| Location | Contents |
| --- | --- |
| `%LOCALAPPDATA%\Programs\BotBus\` | The program: `botbus.exe` (the command line), `botbusw.exe` (the background process and tray icon, without a console window), and the runtime libraries they use |
| `%LOCALAPPDATA%\BotBus\` | Pairing credentials `credentials.dat` (encrypted with Windows DPAPI), settings, and the log `daemon.log` |
| “BotBus” in Task Scheduler | Starts the background process when you sign in to Windows |
| `BotBus` under `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` | Opens the tray icon when you sign in |
| “BotBus” in the Start menu | Opens the main window (and the tray icon if it isn’t running) |
| BotBus in Settings → Apps → Installed apps | Version, size, and the uninstall entry (`HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\BotBus`) |
| `\\.\pipe\botbus-admin-…` | The management channel the `botbus` command and tray icon use to talk to the background process; it only accepts connections from you |

### Security

- Content is end-to-end encrypted: tasks, conversations, and commands are encrypted on this PC before they leave, and the server only relays ciphertext it can’t read. See [End-to-end encryption](https://botbus.io/en/docs/security).
- Pairing credentials are encrypted with Windows DPAPI, so only your Windows account on this PC can decrypt them; the files and the management channel are restricted to you, and other users on the same PC can’t read them or connect.
- The pairing link carries a key and is only shown in your terminal and the tray’s pairing window, never written to a log.
- The install script checks the SHA-256 from the release manifest; `botbus update` also verifies the Ed25519 signature.

Updated 2026-09-30
