Bitfocus Listener is a small companion app you install on a Mac or Windows machine to let Buttons trigger keypresses, shell commands, and other local actions on that computer. This guide covers the connection from Buttons' side: installing and configuring Listener itself happens in its own app, separate from Buttons.
Before you begin#
- Bitfocus Listener installed and running on the target computer, with its own Server Port and Password noted from its app window.
- Network access from Buttons to that computer's IP address and port.
- Add a new connection and choose Bitfocus Listener.
- Enter Target IP: the address of the computer running Listener.
- Enter Target Port: this must match the port shown in the Listener app (its default is
12001). - Enter Password: this must match the password shown in the Listener app.
Buttons doesn't verify these values immediately; check the connection's status once saved to confirm it actually reached and authenticated with Listener.
Note
The password field isn't masked by default; it displays as plain text like any other configuration field. If you want it hidden and encrypted, an administrator with secrets access needs to bind it to a stored secret using Use secret on the field, the same mechanism used to protect credentials on any other connection. This is an extra step you take deliberately, not the default behavior.
What you can trigger#
Once connected, Listener actions become available like any other connection's actions, including: key press, key down/up, key combination, key string (typed text), mouse click and mouse positioning, opening a file, running a shell command, and (on macOS) running an AppleScript or bringing an application's process to the front. There are no feedbacks or variables from this connection; Listener only receives commands, it doesn't report state back into Buttons beyond its connection's own online/offline status.
Because shell commands and AppleScript can do essentially anything the target computer's user account can do, treat every position or workflow that can trigger them with the same care you'd give direct access to that machine.
Restrict what Listener will actually run#
Listener's own app window (not Buttons) is where you control which of these actions it's willing to execute, and who's allowed to trigger them. Configure that restriction directly in Listener on the target computer; it isn't something you set from the Buttons side of the connection.
If you get stuck#
What you see | What to try |
|---|
The connection won't reach Listener at all. | Confirm the target computer's firewall allows inbound connections on the configured port, and that the IP and port match what Listener's own window shows. |
The connection reaches Listener but fails to authenticate. | Re-check the password against Listener's own window: it must match exactly. |
You're not sure who could see the stored password. | Bind the password field to a secret using Use secret if it needs to stay hidden from anyone who can view this connection's configuration. |
An action you expected Listener to run doesn't do anything. | Check Listener's own action-restriction settings on the target computer: it may be configured to refuse that category of action. |
Where to go next#
