The optimal IOTA Train at Home setup on a Mac: complete guide

New to Train at Home? Start with what IOTA Train at Home actually is if you want the background first. This guide assumes you already know that, and focuses on one question: how do you set up a Mac so it contributes steadily, without babysitting it every day?

What "optimal" means here

There is no official minimum-spec sheet and no published Mbps threshold to hit. The two official sources that matter — the Train at Home FAQs↗ and the Train at Home user guide↗ — are both qualitative: "A stable internet connection helps your computer stay connected to the network and send results back. If your connection drops often, your contribution may be lower, which is normal," and "Keep the laptop powered and on a stable network for steady rewards."

So "optimal" here does not mean the fastest possible line or the most powerful Mac. It means uptime and stability: a Mac that stays powered on, stays connected, and keeps the official app running for long, uninterrupted stretches. Everything below is built around that priority, in the order it usually matters.

Prerequisites

• macOS. Train at Home currently only supports macOS (Linux support is announced as "coming soon" in the official user guide). This guide and subnera were last checked against macOS 26.6.2.
• Power. A laptop should stay on AC power, not battery — sleep and low-battery throttling are the two easiest ways to silently stop contributing overnight.
• A stable network connection, wired or Wi-Fi. Official guidance doesn't require Ethernet, but a dropped or power-saving Wi-Fi interface is a common, easy-to-miss cause of interrupted uploads.

Install and first run

If you haven't installed the official app yet, follow the dedicated install guide step by step, then come back here. The short version: download the app from the official site, open the .dmg, and wait for the status indicator to show "Connected" before you do anything else.

Keep the Mac awake

This is the single highest-leverage step, and it's easy to get wrong. Train at Home does not hold its own power assertion. On a Mac actually running the miner, pmset -g assertions shows sleep prevention coming only from generic system daemons (powerd, runningboardd) or from a separate tool like caffeinate — never from the Train at Home app or its worker process itself. This matches the official FAQ directly: "Training stops automatically. Nothing continues running when the app is closed or your computer goes to sleep."

In other words: the app relies entirely on you (or macOS) keeping the machine awake. If nothing else is holding a sleep assertion, an idle Mac will sleep and your contribution stops.

The full walkthrough, flag by flag, lives in the keep-awake guide. The short version, from man caffeinate on this Mac:

• -d — prevent the display from sleeping.
• -i — prevent idle system sleep.
• -m — prevent disk idle sleep.
• -s — prevent system sleep, but only while on AC power.
• -u — declare the user "active"; without -t, this only has a momentary effect.

For a long-running miner, the practical combination is:

caffeinate -dims

Leave that Terminal window open (or run it as a background job) for as long as you want Train at Home to keep training. Verify it's actually holding an assertion with:

pmset -g assertions
pmset -g

If you'd rather not keep a terminal command running, the built-in alternative is System Settings → Energy → "Prevent automatic sleeping when the display is off". This isn't a Train at Home feature — it's a general macOS setting — but it achieves a similar result without caffeinate.

Network and ports: what to check, what to leave alone

Train at Home talks to the network in three ways: a local control connection, an outbound API, and peer-to-peer transfers. You don't need to configure any of them for a normal setup, but it helps to know what's normal so you can tell a real problem apart from noise.

• 127.0.0.1:8010 is the local control connection between the official app and its worker process — loopback only, never reachable from outside your Mac. Never expose this port or connect to it yourself; it isn't a public API, and the app already owns the one connection it needs.
• Outbound HTTPS (443) goes to the orchestrator (iota.api.macrocosmos.ai), to Cloudflare R2 for model weights, and to Hugging Face for tokenizer/model assets. None of this needs inbound port forwarding.
• Peer-to-peer transfer uses iroh↗, a QUIC-based transport, over an ephemeral UDP port that changes between runs — there is no fixed or configurable P2P port to forward. Iroh is designed to work behind NAT without port forwarding or UPnP, using hole-punching with a relay fallback.

If you want to double-check your own setup, three safe, read-only checks:

1. lsof -nP -i — see what the app and its worker are actually listening on and connected to.
2. Grep the CLI log (~/Library/Logs/IOTA Train at Home/<date>-cli.log) for No routable peers — this line means the app couldn't find a P2P peer for a given transfer at that moment.
3. Grep the same log for Registered with P2P node ID — its presence (or repeated absence) over time tells you whether this run ever established a P2P identity.

As a general precaution, consider avoiding VPNs while training: a VPN sits between your Mac and the network path Train at Home relies on, and the extra hop and NAT/tunneling it adds are a common source of exactly the kind of latency and connectivity noise this section is about.

For the full picture — including how to read the registry entry the orchestrator holds for your own machine — see the network and ports guide.

Bandwidth: don't trust a single number

Train at Home runs a built-in speed test a few times a day and reports the result upstream. There is no published local pass/fail threshold for it — grepping a full day of CLI logs for anything resembling a bandwidth minimum turns up nothing, which suggests it's telemetry rather than a local gate.

What we could confirm, on one Mac and one gigabit fiber line, in one afternoon of testing: the embedded speed test auto-picks a server with no user control, and the result depends heavily on which server it lands on, not on the actual line:

Source	Download	Upload
macOS networkQuality (multi-stream)	~995 Mbps	~715 Mbps
Embedded speed test, nearby server	266–371 Mbps	289–301 Mbps
Embedded speed test, distant server	13.8–15.5 Mbps	28.7–30.0 Mbps

Same Mac, same line, same afternoon — a "15 Mbps" reading and a "370 Mbps" reading, purely because of which test server got picked. If your Train at Home speed test looks alarmingly low, that's the first thing to rule out before assuming your connection is the problem: run macOS's own networkQuality in Terminal and compare. The speed test guide walks through this in more detail, including what else to rule out (a VPN, a busy uplink, Wi-Fi vs. Ethernet).

Monitoring: seeing what the official app doesn't show

The official Train at Home app's own UI doesn't expose your real queue position — a known gap, not a rendering bug — so if you want to know where you actually stand, you have two options:

1. Read it yourself. The queue position, phase and registration status are all written to the CLI log in plain text. This guide shows exactly what to grep for.
2. Let a tool do it. subnera is a small, read-only menu bar app that tails that same log and shows the queue position, phase and throughput directly in your menu bar — see how to install it. If you're running more than one Mac, subnera hub adds a single dashboard for the whole fleet — see the multi-Mac guide.

Neither tool talks to the official app's local control port, and neither is required to use Train at Home — they only make the existing log easier to read.

The 10-point checklist

1. Confirm the official app shows "Connected" after install (install guide).
2. Plug the Mac into AC power — don't rely on battery for an overnight run.
3. Start a keep-awake assertion (caffeinate -dims, or the System Settings equivalent) — see the keep-awake guide.
4. Verify it's actually active with pmset -g assertions.
5. Use a stable network connection; avoid VPNs while training.
6. Don't touch 127.0.0.1:8010 — it's not a port you need to configure.
7. If you see repeated "No routable peers" warnings, read the network guide before assuming something is broken.
8. If a speed test result looks unreasonably low, compare it against networkQuality before blaming your line (speed test guide).
9. Install subnera to see your real queue position and phase without digging through logs (install guide).
10. If something still looks stuck, check the troubleshooting guide before restarting the app — a restart re-queues you at the back.

Related guides

• What is IOTA Train at Home?
• Install and set up Train at Home on macOS
• Keep your Mac awake with caffeinate
• Network, ports and P2P
• Reading your queue position in the log
• Installing subnera
• Running Train at Home on several Macs
• Troubleshooting Train at Home
• Rewards and payouts
• Why your speed test looks low