Train at Home network guide: ports, P2P (iroh), firewall and VPN

Train at Home's networking is mostly invisible by design — you don't configure ports, and you shouldn't try to. This guide covers what it actually connects to, in plain terms, for people who want to understand the traffic they're seeing rather than just trust it. If you haven't read the optimal setup guide yet, it covers the same ground briefly; this is the deeper version.

The short version

Train at Home talks to the network in three separate ways, and none of them need you to open, forward, or configure anything:

1. A local control connection between the official app and its worker process — loopback only, never reachable from outside your Mac.
2. Outbound HTTPS to a handful of fixed hosts — the orchestrator API, Cloudflare R2, and Hugging Face.
3. Peer-to-peer transfers over an ephemeral UDP port, using a transport designed specifically to avoid needing port forwarding.

Local ports

Port	What it is	Should you touch it?
127.0.0.1:8010	The control WebSocket between the official Electron app and its worker (main_pool) process. The worker runs the WebSocket server; the app is the client.	No. It's loopback-only and the app already owns the one connection it needs.
*:8009	Observed listening on all interfaces, not just loopback, during this project's own research.	Nothing to do here — see the warning below.

Never connect to 127.0.0.1:8010 yourself, and never expose it beyond your own Mac. It isn't a public API — it's a private control channel between two processes that are already running on the same machine, and its access token rotates on every restart of the app.

Outbound traffic: what's normal

Train at Home's worker process makes outbound HTTPS (443) requests to:

• The orchestrator API (iota.api.macrocosmos.ai) — registration, heartbeats, run configuration, activations, partitions, weight paths, fleet telemetry, and attestation challenges all go through this one host.
• Cloudflare R2 — model weights are fetched from presigned r2.cloudflarestorage.com URLs the orchestrator hands out. This is plain object storage over HTTPS, not a custom protocol.
• Hugging Face — tokenizer and model assets (an expected dependency, though this project's own research didn't independently capture it as live traffic in its own logging window).

None of this needs an open inbound port, port forwarding, or a firewall exception beyond normal outbound HTTPS, which almost every home network already allows.

The P2P transport: iroh over an ephemeral UDP port

Train at Home's peer-to-peer layer is built on iroh↗, a QUIC-based transport — not a generic or custom P2P protocol. The miner's own log confirms this directly: its periodic "Node registry" dump uses the fields iroh_direct_addresses, iroh_relay_url and p2p_node_ids, which are iroh's own vocabulary.

This matters for one practical reason: iroh's hole-punch-plus-relay design is intended to avoid needing manual port forwarding, using QUIC-level hole-punching with a fallback to a relay server when a direct connection can't be established. There is no fixed P2P port to forward in the first place — the worker binds an ephemeral UDP port that can (and does) change between runs, and no environment variable or command-line flag for a fixed port exists in the app's own launch configuration.

Reading your own reachability: three safe checks

You don't need to (and shouldn't) probe the miner's ports yourself. Three read-only checks are enough to understand what's happening:

1. lsof -nP -i — lists every socket the app and its worker actually hold: what's listening, and what's connected to what. A worker process with zero established sockets is a strong local signal something is wrong.
2. Grep the CLI log for No routable peers — the exact warning line is shaped like No routable peers for layer-<N> (activation <uuid>): 0 node(s) matched. It means the app couldn't find a P2P peer for a specific transfer at that moment.
3. Grep the same log for Registered with P2P node ID — its presence (or repeated absence across recent runs) tells you whether this install has ever established a P2P identity at all.

tail -f ~/Library/Logs/IOTA\ Train\ at\ Home/*-cli.log | grep --line-buffered -E "No routable peers|Registered with P2P node ID"

Firewalls, routers, and VPNs

For a normal home setup, there is nothing to configure on your firewall or router: no inbound port needs opening, and iroh's hole-punching plus relay fallback is built to handle NAT without your involvement. If your router or security software blocks outbound UDP broadly (uncommon on a home connection, more common on some corporate/campus networks), that could plausibly interfere with the P2P path — but this wasn't something this guide's research could test directly.

As a general precaution, consider avoiding VPNs while training — this isn't something Macrocosmos has published guidance about, but a VPN sits between your Mac and the network path Train at Home relies on for both its outbound API calls and its P2P attempts, and is a plausible source of exactly the kind of connectivity noise this guide is about: an extra hop that can break hole-punching, add latency, or drop a connection Train at Home was counting on staying stable.

Checklist

1. Leave 127.0.0.1:8010 alone — never connect to it, never expose it.
2. Don't try to forward a port for P2P; there isn't a fixed one to forward.
3. Confirm outbound HTTPS (443) isn't blocked by any security software.
4. Avoid VPNs while training.
5. If you see repeated "No routable peers" warnings, check whether the miner is still progressing (heartbeats, phase changes) before assuming it's stuck — see the troubleshooting guide.
6. Use lsof -nP -i if you want to confirm the worker actually holds any sockets at all.
7. If your speed test numbers look strange while you're investigating network issues, rule that out separately — see the speed test guide.

For the install and keep-awake side of a stable setup, see the full optimal setup guide. If you're not sure where you stand in the queue in the first place, this guide shows what to read in the log.