Getting Started with LuxOS
Deploy LuxOS across your fleet with Luxor Commander, free of charge.
LuxOS is deployed with Luxor Commander, Luxor's fleet management platform. Commander runs in the Luxor web app and talks to your miners through a lightweight Agent installed at your site.
You only need the free Commander Lite plan to deploy LuxOS. Lite lets you install, update and uninstall LuxOS, and change pools, power, temperature and ATM settings in bulk. If you already run your fleet with another tool, such as Foreman or Braiins Manager, you can keep using it: Commander gets LuxOS onto your miners, and your existing tooling takes it from there.
Helpful links
- Miner optimization video (2 minutes): Watch video
- Supported models: Compatible Miners
Before You Start
- Compatible miners: check your models, control boards and hashboards against the Compatible Miners list. Miners must be running stock Bitmain or MicroBT firmware to install LuxOS.
- A Luxor account: sign up if you don't have one yet.
- A machine for the Agent: a Linux or Windows computer, mini PC or VM on the same local network as your miners, with outbound internet access. See the Agent system requirements.
- The EULA: review the LuxOS End User License Agreement before installing.
Prefer a fully local install?
Commander in the Luxor web app is the recommended way to deploy LuxOS. If you'd rather not create a Luxor account or run an Agent, you can install LuxOS fully locally with desktop LuxOS Commander: Windows, macOS (Apple Silicon), macOS (Intel) or Linux. We're working on a lightweight local LuxOS installer that will replace it.
Deploy LuxOS
Create an Agent
Open Commander from the left sidebar of the Luxor app and select Start Now (or Settings → + Agent if you already have one).
- Choose a plan: Commander Lite, which is free, or Commander Pro, which starts with a 60-day free trial. You can change plans at any time.
- Select the Site the Agent belongs to, or create a new one directly from this step.
- Give the Agent a name and a secret, and under Network Settings add the network ranges where your miners live. Each range can be an IP Range (
192.168.0.0-192.168.1.255), an IP List (192.168.14.67) or a CIDR block (10.20.20.0/24). - If your miners don't use factory default credentials, or run MicroBT stock firmware, add the miner username and password under Advanced Settings.
- Click Create New Agent.
Install the Agent
After you create the Agent, Commander shows the install options with your Agent ID and secret already filled in:
- Linux: copy the terminal command and run it on your Agent machine.
- Windows: run the PowerShell command as Administrator, or download the GUI installer and enter your Agent ID and secret.
Once the Agent connects, it scans your IP ranges and your miners appear in the Miners tab within a few minutes. If they don't, see Troubleshooting.
Remove third-party firmware (if needed)
If any miners run another custom firmware, such as Braiins OS or Vnish, return them to stock first. Select them in the Miners tab, open Bulk Actions and run Uninstall Custom Firmware. The miners reboot into stock firmware, ready for LuxOS.
Install LuxOS
- In the Miners tab, use the filters to narrow down by model and firmware, then select the miners to install. We recommend starting with a small batch.
- Open Bulk Actions and add Install LuxOS.
- In the preview, check the compatibility column, and set a Batch Size and Delay to limit how many miners reboot at once.
- Run the action and follow the progress in the Action Log. Each miner's result is recorded individually, so you can retry only the ones that failed.
LuxOS keeps each miner's existing network and pool configuration during install. After a few minutes, the miners boot into LuxOS and start hashing.
Configure Your Miners
Once LuxOS is running, use Bulk Actions to apply settings across your fleet. All of these are included in Commander Lite:
| Action | What it does |
|---|---|
| Change Pool Settings | Set the stratum URL, worker name and password |
| Change Power Settings | Choose a preset profile or a power target |
| Change Temperature Control | Set temperature targets and configure Advanced Thermal Management |
| Fault Recovery | Control automatic hashboard recovery and its limits |
| Run LuxOS Command | Send any LuxOS API command, for example to enable the AutoTuner |
| Sleep / Wake Up | Curtail miners and bring them back |
| Reboot | Restart the selected miners |
For a safe starting point, see Recommended Settings. You can also change settings on a single miner from the LuxOS web interface, or programmatically through the LuxOS API.
Keep LuxOS Up to Date
To upgrade, select your miners and run the Update LuxOS bulk action, choosing the Stable or Preview release channel. As with installs, upgrading in batches limits the number of miners rebooting at the same time. Release notes are in the LuxOS Changelog.
Use LuxOS With Your Existing Fleet Manager
LuxOS exposes a CGMiner-compatible API on port 4028, so third-party fleet management tools can monitor and control LuxOS miners after installation. See Foreman for an example integration, and the LuxOS API reference for the full list of commands.
Frequently Asked Questions
Do I need to pay for Commander to use LuxOS? No. Commander Lite is free and includes everything needed to install, update and configure LuxOS across your fleet.
What does Commander Pro add? Pro adds automation rules, Intelligent Miner, Sitemap, Inventory, Tickets, Reports and VIP support. See Pricing.
My miner model or firmware isn't supported by Commander. What now? Some control boards and recent stock firmware versions require a remote install by the Luxor team. See Remote Install. For a fully local install without a Luxor account, see Before You Start. For scripted or offline installs, there is also the LuxOS Installer command-line tool.
I'm a partner. How do I get credit for the installs I deploy? See the Partner Referral ID program.
If you have any questions, submit a ticket and our team will help.