Sign in at user.bitfocus.io and open the Downloads page. Download the current Buttons v1.8 build for the computer that will run Buttons.
Buttons is available for:
macOS
Windows
Linux
Enterprise licenses can also run Buttons as a high-availability deployment on Kubernetes. In this setup, Buttons runs replicated services across Kubernetes nodes and can fail over when an active instance becomes unavailable. Kubernetes HA is a separate, advanced installation path; do not follow the single-machine steps below as deployment instructions for an HA cluster: see Deploy Buttons with Kubernetes high availability instead.
Open Buttons after installation. The watchdog window starts and monitors the services that make up Buttons.
Use the watchdog window to:
See whether the Buttons services are starting or running.
Open the web interface with Launch Editor UI.
Restart a service if it has stopped.
Open Environment Settings.
Reset the administrator password when you have access to the host computer.
Shut down Buttons cleanly.
Keep the watchdog running while you use Buttons. Closing Buttons from the watchdog stops the services and makes the Editor UI and operator controls unavailable.
The Linux build can run without a desktop window. In headless mode, the watchdog runs from the command line and supervises the same Buttons services.
The downloaded Linux package includes its current startup instructions, command-line help, and a service example. Follow those instructions to choose whether Buttons listens only on the Linux host or on every network interface. HTTPS normally uses port 4443; if you change the web ports, confirm the resulting HTTPS port with ./watchdog-cli -help, see the startup configuration reference for the full flag list.
For a permanent installation, adapt the supplied service example to your environment.
Buttons uses a web interface. Open it over HTTPS in a modern version of Chrome, Edge, Firefox, or Safari. Chrome is recommended.
On the Buttons host, select Launch Editor UI in the macOS or Windows watchdog. On a headless system, open:
https://localhost:4443
Buttons automatically generates a self-signed certificate so HTTPS is available on a fresh installation. Because your browser does not automatically trust this certificate, it may display a certificate warning the first time you connect. Confirm that you are opening the intended Buttons host before continuing.
From another computer or tablet on the network, use the Buttons host's hostname or IP address, for example:
On macOS and Windows, open the menu beside Launch Editor UI in the watchdog and select Environment Settings.
Under Editor Listen Address, choose:
Local machine only (127.0.0.1): only browsers running on the Buttons host can connect.
All interfaces (0.0.0.0): browsers on other machines can connect through a reachable address or IP of the Buttons host.
Environment Settings also contains:
Editor HTTPS Port: the port on which Buttons accepts direct HTTPS connections. The fresh-install value is 4443.
Buttons Hostname: the hostname through which Buttons is available, such as buttons-studio.example.
Buttons External Address: the complete HTTPS URL people use to reach Buttons. Buttons uses this address when opening the Editor UI and redirecting after login. It is also required by features that need a stable external origin, including SSO callbacks and passkeys.
For a direct connection on the default HTTPS port, the external address would be:
https://buttons-studio.example:4443
If an approved reverse proxy or Kubernetes ingress exposes Buttons at the standard HTTPS port, the external address might instead be:
https://buttons-studio.example
Enter an absolute URL beginning with https://. Include the port when it is part of the address people use. The hostname in this address must be covered by the HTTPS certificate.
After choosing All interfaces (0.0.0.0), open Buttons from another machine using the configured external address. Remember that Buttons External Address tells Buttons its public URL; it does not by itself change the listen address, open a firewall port, configure DNS, or create a reverse proxy.
Listening on all interfaces makes the Editor UI available to every network that can reach that port. Keep Buttons on a trusted network and do not expose the Editor port directly to the public internet.
A new or cleared Buttons system opens the First-time setup page. It says Create a local admin user to protect your installation.
Enter the administrator username in Username.
Enter a password that meets every requirement shown on the page:
At least 8 characters
Contains a lowercase letter
Contains an uppercase letter
Contains a number
Contains a special character
Enter the same password in Confirm password.
Select Create admin user.
Buttons creates the account, signs you in, and opens Home. The left navigation gives you access to areas such as Position, Connect, Workflow, Cuelist, Tags, Routing, Auth, and Settings. Some items can appear under More when the browser window is short.
The first account is the system administrator. On an unlicensed system, Auth is visible but not yet interactive: user and role management need a paid license tier. Do not use this account as a shared account. Store its credentials securely, and never include real credentials in screenshots, documentation, tickets, or support messages.
The automatically generated certificate encrypts the connection, but browsers do not trust it automatically. For a permanent installation, replace it with a certificate issued for the hostname people use to open Buttons.
Open Settings → Certificates.
Under Incoming connections (HTTPS), select Upload beside Upload certificate files.
Choose the server certificate and its matching RSA private key.
Select Save and restart.
Buttons checks that the certificate and private key match, saves them, and restarts the HTTPS service. Reopen Buttons at the configured Buttons External Address. Keep the private key secure and do not include it in tickets, screenshots, or documentation.
In a Kubernetes deployment, the certificate can be managed externally. When it is, the certificate page identifies it as Certificate managed by Kubernetes and does not offer replacement controls.
Environment Settings → Editor Listen Address is set to All interfaces (0.0.0.0).
The browser uses the host's real hostname or IP (not 0.0.0.0 or 127.0.0.1) and the configured HTTPS port.
The network and host firewall allow the browser to reach that port.
If the normal sign-in page appears instead of First-time setup, the system already has its first user. Sign in with an existing account or use Reset Admin Password from the watchdog on the host machine.
