BotBus for Linux

Install

curl -fsSL https://botbus.io/install.sh | sh

No curl? Use wget:

wget -qO- https://botbus.io/install.sh | sh

What the installer does

1. Picks the x86_64 or aarch64 package based on uname -m and downloads the version listed on this page.
2. Checks the download against the SHA-256 in the release manifest, and stops without installing anything if it doesn’t match.
3. Puts botbus at ~/.local/bin/botbus without touching system directories. If ~/.local/bin isn’t on your PATH, it tells you how to add it.
4. Runs botbus up: with a systemd user session it installs the user service botbus.service; without one it starts in the background with nohup.
5. If Claude Code is on the machine (~/.claude exists), it installs BotBus’s Claude Code hooks so Claude sessions you start on the computer show up on your phone too. Uninstalling removes them.
6. Shows a pairing QR code in the terminal and waits for you to scan it with your phone.

Keep it running after you log out of SSH

By default, systemd stops user services when your last login session ends. On a server, enable linger for your user so the service keeps running and also starts at boot:

loginctl enable-linger $USER

Some systems require admin rights for this; then run sudo loginctl enable-linger $USER. botbus up reminds you when linger is off.

Machines without systemd (containers, some minimal systems) run it in the background with nohup. Logging out of SSH usually doesn’t affect it, but after a reboot you need to run botbus up again. To use this mode even when systemd is available, set BOTBUS_NO_SYSTEMD=1 first.

Pair your phone

• Scan the QR code in the terminal with BotBus on your phone. It’s drawn with text characters, so enlarge the terminal window if it doesn’t fit.
• Can’t scan it (say, you’re using an SSH client on the phone itself)? Open the pairing link printed below the QR code on your phone. The link carries the encryption key: only pass it between your own devices, and don’t paste it into chats or tickets.
• Pairing codes expire; the terminal shows when. If it has expired, run botbus pair again.
• Already paired and want to add another phone? Run botbus pair too; it creates an invite code.
• Once paired, botbus status shows the connection state and how many phones are paired.

Commands

The botbus share, link, list, and mcp commands that agents use in phone tasks work the same as on the Mac. Dev previews (botbus preview) aren’t supported on Linux yet.

Update

botbus update

• Downloads the new version for your architecture according to the release manifest on botbus.io, checks its SHA-256 and Ed25519 signature, replaces the program, restarts the service, and confirms that the new version is running.
• botbus status tells you when an update is available (it checks once a day).
• You can also rerun the install command: once the new program is in place, the botbus up it runs switches the service to the new version.

Uninstall

botbus uninstall

Stops and removes the background service, deletes ~/.local/bin/botbus, and removes BotBus’s hooks from Claude Code’s settings. Credentials stay in ~/.config/botbus, so you won’t need to pair again after reinstalling.

botbus uninstall --purge

Also deletes credentials and data (~/.config/botbus, ~/.local/share/botbus). The computer then shows as offline on your phone, and you can remove it there.

Common problems

• The botbus command isn’t found~/.local/bin isn’t on your PATH. Run echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile && . ~/.profile, or call ~/.local/bin/botbus directly.
• Claude Code or Codex doesn’t show up on the phoneThe systemd service uses the PATH from the moment you ran botbus up. Install the agent first, make sure which claude (or which codex) finds it in your terminal, then run botbus up again so the service picks up the new PATH. botbus agents lists the agents it detected.
• Claude Code sessions started on the computer don’t show upbotbus up installs the hooks when ~/.claude exists, and they use curl to report events to BotBus. Run botbus up again after installing Claude Code, and install curl if it’s missing. Sessions you start from the phone don’t rely on hooks.
• It can’t connect and the log mentions certificates or TLSThe system is missing root certificates. Install ca-certificates (Debian / Ubuntu: sudo apt install ca-certificates; Alpine: apk add ca-certificates), then run botbus down && botbus up. Minimal container images often lack them.
• The machine has no systemdBotBus falls back to running in the background with nohup, which also works in containers; run botbus up after a reboot.
• The service stops when you log out of SSHEnable linger for your user; see Keep it running after you log out of SSH.
• The service won’t start or reports a problemCheck botbus logs (add -f to follow). botbus status also reports causes such as credentials that can’t be read.
• Log lines show <private>By default the log redacts strings such as task content and paths. To debug, run botbus down, then temporarily run BOTBUS_LOG_PRIVATE=1 botbus daemon in the foreground; press Ctrl-C when done and run botbus up. That log contains task content, so review it before sharing.

Manual install

If you’d rather not pipe a script into your shell, download, verify, and unpack it yourself. The files for this version:

VERSION=1.0.5
ARCH=$(uname -m)    # x86_64 or aarch64
FILE=botbus-$VERSION-linux-$ARCH.tar.gz
curl -fLO https://botbus.io/downloads/linux/$FILE
curl -fLO https://botbus.io/downloads/linux/$FILE.sha256
sha256sum -c $FILE.sha256
mkdir -p ~/.local/bin
tar -xzf $FILE -C ~/.local/bin botbus
~/.local/bin/botbus up

sha256sum -c should print OK; you can also compare against the SHA-256 in the table above. Release packages also carry an Ed25519 signature, which botbus update verifies.

Where files live

If XDG_CONFIG_HOME or XDG_DATA_HOME is set, those locations are used instead.

Security

• End-to-end encryption: tasks, conversations, and commands are encrypted on this machine before they leave it, and the server only relays ciphertext it can’t read. See End-to-end encryption.
• Pairing credentials live only in ~/.config/botbus with file mode 0600; other users on the same machine can’t read them or connect to your admin socket.
• The pairing link carries keys, so it’s only printed in your terminal and never written to the log.
• The installer checks the SHA-256 from the release manifest; botbus update also verifies the Ed25519 signature.