Install the Button runner

The Button runner is a small program that runs your tools on your own computer. Install it on the computer that has the scripts you want to share. The people you share tools with install nothing.

Install

Open https://button.bitgate.dev/app/machine and copy the install command. It contains a pairing code that works once, within 10 minutes.

On macOS or Linux, paste it into Terminal:

curl -fsSL https://button.bitgate.dev/install.sh | sh -s -- --code <PAIR_CODE>

On Windows, paste it into PowerShell:

$env:BUTTON_CODE="<PAIR_CODE>"; irm https://button.bitgate.dev/install.ps1 | iex

You don't need administrator rights.

What the installer does

1. Downloads the latest runner for your system and checks its SHA-256 checksum. If the checksum doesn't match, it stops without changing anything.
2. Puts the runner in your user folder (see where files live, below).
3. Pairs this computer with your workspace. A workspace has one computer: pairing a new one replaces the previous one, as long as that one isn't in the middle of a job.
4. Starts the runner in the background and sets it to start when you log in.
5. Opens the setup page in your browser, where you pick a program, describe its form and publish it as a tool.

Without a code, the installer only installs or upgrades the runner.

Supported systems

• macOS 12 or later, Apple silicon or Intel
• Linux on x86-64 or ARM64
• Windows 10 or 11, 64-bit, with Windows PowerShell 5.1 or PowerShell 7

Where files live

If your terminal can't find button-runner after installing, ~/.local/bin isn't on your PATH yet. The installer prints the line to add to your shell profile. On Windows, use the full path, for example & "$env:LOCALAPPDATA\Button\button-runner.exe" status.

The background runner

The runner has to be running for people to use your tools. Tool pages show Ready, Busy or Offline.

• macOS: a LaunchAgent (~/Library/LaunchAgents/dev.bitgate.button.runner.plist) starts it when you log in and restarts it if it crashes.
• Linux: a systemd user service (~/.config/systemd/user/button-runner.service) starts it when you log in and restarts it if it crashes. It stops when you log out. To keep it running while logged out, for example on a server, run sudo loginctl enable-linger $USER once.
• Windows: a ButtonRunner entry under HKCU\Software\Microsoft\Windows\CurrentVersion\Run starts it in the background when you sign in. If it stops, run button-runner restart or sign out and back in.

Only one runner runs per computer. The runner only makes outgoing HTTPS connections to button.bitgate.dev. The only thing it listens on is the setup page, on 127.0.0.1, while that page is open.

Environment

Jobs get the background runner's environment, not your terminal's. On macOS and Linux, the installer copies PATH and the proxy and certificate variables (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, SSL_CERT_FILE, SSL_CERT_DIR) from the terminal you run it in. Anything else your shell profile exports, such as DATABASE_URL, is not there: put it in the tool's environment on the setup page, or have your script read it from a file. After changing PATH or a proxy, run button-runner restart from a terminal that has the new values.

On Windows, the runner gets your Windows user and system environment variables.

Commands

Update a tool

Run button-runner setup and pick the tool. The form opens with its current setup; change what you need and press Publish update. People who already have access confirm a changed command before their next run.

Proxies

The runner reads HTTPS_PROXY and NO_PROXY for its API calls and its live connection. It doesn't use system proxy settings such as PAC files or automatic proxy detection. The proxy has to allow WebSocket connections to button.bitgate.dev.

On macOS or Linux, set it in the terminal and run the install command there:

export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://button.bitgate.dev/install.sh | sh -s -- --code <PAIR_CODE>

On Windows, save it as a user variable, then open a new PowerShell window and run the install command:

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://proxy.example.com:8080", "User")

If your proxy inspects HTTPS with its own certificate authority: on macOS and Windows the runner trusts the certificates in the system store. On Linux, add the certificate to the system bundle or set SSL_CERT_FILE to it.

Upgrade

Run the install command again, without a code.

macOS and Linux:

curl -fsSL https://button.bitgate.dev/install.sh | sh

Windows:

irm https://button.bitgate.dev/install.ps1 | iex

It downloads the latest version if yours is older and restarts the background runner. Your pairing and approved tools stay. Upgrade when no job is running.

Uninstall

On macOS and Linux, stop the background runner, then delete the files.

button-runner uninstall

macOS:

rm -rf ~/.local/bin/button-runner ~/Library/"Application Support"/button ~/.local/share/button ~/Library/Logs/button-runner.log

Linux:

rm -rf ~/.local/bin/button-runner ~/.config/button ~/.local/share/button

Windows:

& "$env:LOCALAPPDATA\Button\button-runner.exe" uninstall
Remove-Item -Recurse -Force -ErrorAction SilentlyContinue "$env:LOCALAPPDATA\Button", "$env:APPDATA\button", "$env:USERPROFILE\.local\share\button"

Your tools show as Offline until you pair another computer.