x86-64 VM or unprivileged LXC, 2 vCPU, 4 GB RAM, 64 GB disk and a permanent LAN IPv4 address.
ODINOS OFFICIAL GUIDE
From clean server
to first accepted share.
This guide covers the supported OdinOS path: a self-hosted controller, a bootable x86-64 CPU worker, your own miner package and a Flight Sheet that ties everything together.
GPU status
GPU discovery, drivers and tuning are on the roadmap. The current production guide is for Intel/AMD x86-64 CPU workers.
01 / START HERE
Before you begin
OdinOS keeps the dashboard, packages, credentials and telemetry on your own controller. The hosted OdinOS service is used only for licences, signed release metadata and protected downloads.
4 GB RAM minimum for a typical RandomX worker, wired DHCP and an 8 GB or larger USB drive or SSD.
The controller must be reachable through HTTPS. Do not use 127.0.0.1 for a physical worker.
OdinOS does not bundle a miner and never creates or holds your wallet.
1Install
controller
→
controller
2Flash
worker
→
worker
3Add miner,
wallet & pool
→
wallet & pool
4Assign
Flight Sheet
→
Flight Sheet
5Verify
shares
shares
02 / CONTROLLER
Install the controller
Start with a clean Debian 12 or Debian 13 x86-64 server. Run the public installer as root; it downloads the signed Community release and worker image, verifies SHA-256 checksums and installs the systemd service.
Prepare the server
Assign a permanent LAN IPv4 address before installation. The address becomes part of the generated HTTPS certificate and worker configuration.
Run the verified installer
DEBIAN / ROOT SHELL
sudo apt-get update && sudo apt-get install -y curl ca-certificates
curl -fsSL https://getodinos.com/install.sh | sudo bashFor unattended setup, pipe the installer to sudo ODIN_CONTROLLER_IP=192.168.1.50 bash.
Open the dashboard
The installer prints the URL and the command that reveals the generated administrator password. Open https://CONTROLLER-IP:8090. Import and trust the public controller certificate on administrator devices instead of repeatedly bypassing certificate warnings.
Secure the first login
Open Settings, enable two-factor authentication and store all eight recovery codes in a password manager. Use Keep me signed in only on a trusted device.
Do not expose port 8090 to the Internet
For public access, put the controller behind a properly configured HTTPS reverse proxy with a publicly trusted certificate. Never expose Proxmox management or worker service ports.
03 / WORKER
Add your first worker
A worker is the CPU machine that runs the miner. The downloadable image contains Debian, the unprivileged agent, root console service, updater, Huge Pages and MSR setup. It contains no miner or wallet.
Download the image
In the controller, open Settings → Worker image, or use Add worker → Flash a worker drive.
Flash an 8 GB+ drive
Use balenaEtcher to write the .img.xz file directly to a USB drive or SSD. The selected drive is erased. An SSD is recommended for continuous use.
Create worker.json
Open Add worker → Flash a worker drive. Enter the controller's reachable HTTPS URL, optional worker name and the public CA certificate when using the self-signed controller certificate. Download worker.json.
Copy, connect and boot
Copy worker.json to the root of the ODINBOOT partition. Safely eject the drive, connect wired Ethernet and boot it on the worker. Disable Secure Boot in BIOS/UEFI.
Wait for enrollment
The worker obtains an address over DHCP, creates its own identity and appears in Workers. A one-time token expires after 30 minutes; create a fresh file if it expires before first boot.
Flashing many workers with one file
Tick One file for many drives (farm key) and leave the worker name empty. Each machine creates a distinct identity and generated name. Rotate the farm key when staging is finished. Rotation prevents new enrollment with old files and does not disconnect existing workers.
Never clone an enrolled drive
Each worker owns a unique identity. Reflash the clean image when moving a drive to another machine or controller.
04 / MINER PACKAGE
Add the miner you choose
OdinOS has no miner whitelist. Upload a Linux x86-64 binary, script, .tar.gz or .zip, or let the controller import a public release asset from a direct HTTPS download link.
Direct download link
- Open Miners → Add miner.
- Select Download link.
- Paste the direct asset URL, not a web download page.
- Enter name, version, archive format and relative entrypoint.
- Add the publisher's SHA-256 when available.
- Choose Download and save miner.
Local upload
- Select Local file.
- Choose a package up to 256 MiB.
- Set the entrypoint, such as
xmrigorminer/start.sh. - Save the immutable revision.
Package rules
The miner must target Linux x86-64 and run in the foreground. Bundle required libraries or install them on the worker. Shell wrappers should end with exec ./miner …. Hive custom h-*.sh packages are not directly compatible.
05 / START MINING
Build and assign a Flight Sheet
A Flight Sheet is an immutable mining configuration: coin, wallet, pool, miner revision, arguments, monitoring and protection. Editing a source object does not change a running worker until the sheet is assigned again.
Create a wallet
Open Wallets → Add wallet. Enter the coin ticker, payout address and a clear label. OdinOS stores the address only on your controller.
Create a pool
Open Pools → Add pool. Use the same coin ticker, then enter the Stratum host, port and password. Add a backup pool when supported.
Create the sheet
Open Flight Sheets. Choose the wallet, pool, miner and algorithm. Enter miner arguments one per line, without surrounding quotes.
Choose monitoring
Select the matching adapter: XMRig HTTP, cpuminer/ccminer TCP, DERO output or custom JSON. A miner can run without an adapter, but hashrate and watchdog data remain unknown.
Assign to workers
Save, select Assign, choose one or more compatible workers and confirm. Each worker downloads the exact saved package and configuration revision.
Verify real work
Open the worker's Miner logs. Confirm the pool connection, Huge Pages/MSR result, non-zero hashrate and accepted shares.
Useful placeholders
%WAL%Wallet address%WORKER_NAME%Current worker name%URL%Primary pool URL%PASS%Primary pool password%ALGO%Selected algorithm%COIN%Coin ticker%URL2%Backup pool URL%PASS2%Backup pool passwordUse the _JSON variants inside quoted JSON strings, for example %WAL_JSON%. Placeholders are substituted once and are never added automatically as command-line flags.
06 / OPERATIONS
Monitor and control safely
Farm health
Use the worker list for online state, miner status, hashrate, shares, temperatures, load, RAM, power estimate and agent version.
Start, stop, restart
Open a worker and use Profile for miner controls. Wait for the applied revision and agent confirmation before treating an action as complete.
Read the miner output
The Miner logs tab shows bounded stdout/stderr. It is the source of truth for Huge Pages, MSR tuning, pool connection and accepted work.
Remote console
Open Manage → Remote access → Open root terminal. It is a real UID 0 Bash shell and allows one 15-minute session per worker.
Watchdogs
Configure mining statistics and protection in the Flight Sheet. Set realistic hashrate and temperature rules and test them on one worker.
Telegram
Configure Settings → Notifications for offline, recovered, miner failure, watchdog, thermal and update alerts.
Root means full host control
Anyone with controller administrator access can operate enrolled workers as root. Long commands should run as a persistent systemd unit because closing the browser terminal ends attached processes.
07 / UPDATES & LICENCE
Stay current without surrendering control
Community runs two workers without a licence. Paid tiers offer two update schemes: lower annual pricing for 12 months of signed releases, or a higher one-time price for lifetime OdinOS updates. Both preserve use of the installed version; an expired annual update period never stops the controller or miners.
Activate a plan
- Open Settings → Subscription and updates.
- Copy the public Controller key.
- Choose annual or lifetime updates and the required worker tier.
- Submit the option and Controller key through the private purchase channel provided by OdinOS.
- Complete the confirmed payment process, then paste the returned activation key into the same Settings page.
Install updates
- Open Settings → Controller update.
- Check the version and changelog.
- Install the signed controller release.
- Enable automatic worker updates, or assign them manually from Updates.
- Watch the one-worker-at-a-time rollout and health confirmation.
Controller updates back up the database and roll back on a failed health check. Agent binary updates also restore the previous binaries when a fresh heartbeat does not arrive.
08 / PHONE & TABLET
Install OdinOS from your browser
The dashboard is a Progressive Web App (PWA). It can live on the Home Screen, use the OdinOS icon and open in its own app window while remaining the same interface served by your controller.
iPhone and iPad
Use Safari
- Open your controller's HTTPS address in Safari and sign in.
- Tap the Share button in the Safari toolbar.
- Scroll through the actions and choose Add to Home Screen.
- Keep or edit the name, then tap Add.
- Launch OdinOS from its new Home Screen icon.
Android phones and tablets
Use Chrome
- Open your controller's HTTPS address in Chrome and sign in.
- Open the ⋮ browser menu.
- Choose Install app. On some devices it appears as Add to Home screen.
- Confirm with Install or Add.
- Launch OdinOS from the Home Screen or app drawer.
Samsung Internet: open the menu and choose Add page to → Home screen.
Why this is better than a heavy companion app
The installed interface is served by that controller, so it always matches the controller version you are running.
Update the controller once. Close and reopen the Home Screen app to load its new dashboard shell—there is no separate mobile release to wait for.
No large native bundle duplicates the dashboard. The shortcut keeps only a small public shell cache; live data still comes directly from your controller.
No App Store or Google Play account, fee, review delay or regional listing is required. Each controller origin installs as its own app.
HTTPS is required
Use a publicly trusted certificate for the cleanest phone installation. The PWA never caches authenticated API responses, credentials, wallets, telemetry or console data. Live control still requires a network connection to your controller.
09 / TROUBLESHOOTING
Find the failing boundary
The worker never appears
- Confirm the worker can reach the controller HTTPS URL;
127.0.0.1points to the worker itself. - Create a fresh
worker.jsonif the one-time token is older than 30 minutes. - Check wired DHCP, controller and firmware clocks, and the supplied CA certificate.
- Disable Secure Boot and inspect the local worker screen for setup errors.
The miner downloads but does not start
- Confirm Linux x86-64 compatibility and the exact relative entrypoint.
- Check executable permissions, LF line endings, shebang and missing shared libraries.
- Enter arguments one per line and keep the miner in the foreground.
- Open Miner logs for the actual exit message.
The miner runs but hashrate is unknown
- Select a statistics adapter that matches the miner.
- For XMRig, enable the local HTTP API; for compatible cpuminer forks, enable the loopback TCP API.
- Keep APIs on
127.0.0.1. A custom miner can write OdinOS JSON statistics atomically every 3–10 seconds.
Huge Pages or MSR is not active
- Inspect the miner log; reservation alone is not proof that the miner uses Huge Pages.
- Check
/run/odinos/hugepages.jsonandjournalctl -u odin-hugepagesthrough the root console. - For MSR, check
cat /sys/module/msr/parameters/allow_writes. Unsupported CPUs or kernels continue without tuning.
An update is unavailable or fails
- Check subscription status and update expiry under Settings.
- Confirm controller Internet access and correct system time.
- Read the controller update log. Worker update stages and rollback state appear in Updates and the worker row.
10 / SECURITY
Production checklist
No matching guide section
Try “worker”, “miner”, “updates”, “Huge Pages” or “licence”.