// getting started, common issues, and how to get help
Two ways to run Bitaxe Baller — pick whichever fits.
A real native app: click the icon, a window opens with the dashboard. No terminal, no Python install, no config files. Code-signed and Apple-notarized.
.dmg from the home page, drag Bitaxe Baller to Applications, launch from Spotlight or Applications. On first launch macOS may show "Bitaxe Baller is an app downloaded from the internet. Are you sure?" — click Open. After that, it never asks again.The dashboard works from a clone of the GitHub repo. You'll get the same UI but in your browser instead of a native window.
git clone https://github.com/465media/bitaxe-baller.git
cd bitaxe-baller
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python app.py
# then open http://localhost:5050 (or :80 with sudo)
Requires Python 3.11+. Works on macOS, Linux, and Windows (via WSL or native Python). Full instructions in the README.
On the host machine (the Mac running the app), the dashboard appears in its own native window when you launch Bitaxe Baller. No browser tab needed.
From other devices on your LAN (phone, iPad, laptop), the same dashboard is reachable in any browser at:
http://bitaxe-baller.local (or :5050 if the app fell back to that port) — via mDNS / Bonjour, no IP neededhttp://<host-ip>:5050 — fallback if mDNS isn't available on the deviceThe app prints all reachable URLs in its startup output if you ever want to see them (open Console.app on the host and filter for Bitaxe Baller).
Either paste your Bitaxe's IP (the one shown on its OLED) into the "+ add device" form, or hit ⚡ scan network and Bitaxe Baller will find it for you. Click the resulting card to open the device's full detail page.
This usually means the page is loaded via a hostname (like localhost or bitaxe-baller.local) and the LAN-info request hasn't returned yet. It should resolve within a second. If it stays stuck, your firewall or browser extensions may be blocking the call to /api/lan-info.
If you see "Bitaxe Baller can't be opened because Apple cannot check it for malicious software", you likely got an unsigned build, or notarization hasn't propagated yet. Right-click (or Control-click) the app and choose Open; macOS will give you a different prompt with an "Open" button. Future signed releases won't show this.
Until we add Windows code signing, expect "Windows protected your PC" on first launch. Click More info, then Run anyway. The app is open source — you can verify its contents on GitHub.
The app tries to bind port 80 (so you get a clean URL like http://bitaxe-baller.local) and falls back to :5050 if it can't (typical when not running as root). When falling back to 5050, the URL becomes http://bitaxe-baller.local:5050. Both work; the only difference is whether you have to type the port. Run the CLI version with sudo to get port 80 cleanly. The packaged Mac/Windows apps handle this for you.
Three usual culprits:
The Bitaxe firmware applies pool config only on a fresh stratum connection. Make sure "restart device after apply" is checked when you submit the pool form (it's on by default). If you unchecked it, manually click the restart button at the top of the device detail page.
The recommendation engine waits ~3 minutes after a device is added or its benchmark is reset before producing real tuning suggestions. This avoids firing on noisy startup data. Just give it a few minutes.
The home page outlines each device card based on the highest-severity recommendation:
The "Max" preset runs at 625 MHz / 1225 mV — that's near the chip-degradation threshold for the BM1370 and is intended for short benchmark sweeps, not 24/7 operation. For daily use we'd recommend Mild OC or Balanced. Always watch the VR temperature — that's the part that fails first on overclocked boards.
One file per device per day, in the logs/ folder next to the app. Filename pattern: <label>_<YYYY-MM-DD>.csv. Open in Excel or pandas to compare tuning settings over time.
No. The app runs entirely on your local network. It connects only to the Bitaxes you tell it about. No telemetry, no analytics, no phone-home.
Two ways to get help: