Clarify macOS and API port setup for blockchain node quickstart

[Devpen787]

Summary

• add the macOS Apple silicon release path to the node quickstart
• add matching macOS download commands for the node and circuits assets
• keep the Linux x86_64 example release links consistent with release 0.1.2
• add a small API port collision check before running the local verification commands

Related to #213.

Why

I dogfooded the headless Logos Blockchain node quickstart from logos-co/logos-docs#213.

On an Apple silicon Mac, the latest 0.1.2 release includes runnable macos-aarch64 node and circuits assets, but the quickstart prerequisites only mention Linux x86_64 and Raspberry Pi. The macOS binary ran locally, init generated user_config.yaml, and --check-config passed.

I also hit a local port collision on 8080. The node logged that it could not bind the API server, but the process continued running. Because another local service was already listening on 8080, the guide's curl localhost:8080/... checks returned a response from the wrong service. After changing api.backend.listen_address to 127.0.0.1:18080, the documented API checks worked with the adjusted port.

Evidence

• Release checked: logos-blockchain/logos-blockchain latest release 0.1.2
• Downloaded and extracted:
  • logos-blockchain-circuits-v0.4.2-macos-aarch64.tar.gz
  • logos-blockchain-node-macos-aarch64-0.1.2.tar.gz
• Ran:
  • ./logos-blockchain-node --version
  • ./logos-blockchain-node --help
  • ./logos-blockchain-node init ...
  • ./logos-blockchain-node --check-config user_config.yaml
  • ./logos-blockchain-node user_config.18080.yaml
  • curl -s http://localhost:18080/cryptarchia/info
  • curl -s http://localhost:18080/network/info

./logos-blockchain-node --version output:

logos-blockchain-node 0.1.2
commit:  05f84a5 (tag 0.1.2)
target:  aarch64-apple-darwin
profile: release
rustc:   rustc 1.94.0 (4a4ef493e 2026-03-02)

Observed API output after using port 18080:

{
  "lib": "646088a81f76e6a6ae35b3cc87f33c9081c12b02932604eee427593251f72bec",
  "lib_slot": 0,
  "tip": "646088a81f76e6a6ae35b3cc87f33c9081c12b02932604eee427593251f72bec",
  "slot": 0,
  "height": 0,
  "mode": "Bootstrapping"
}

{
  "listen_addresses": [
    "/ip4/127.0.0.1/udp/3000/quic-v1",
    "/ip4/192.168.1.4/udp/3000/quic-v1"
  ],
  "peer_id": "12D3KooWAqVd6dspmppz6Zu7988avyfoBqPB7tCwT7Yyauq6LWg1",
  "n_peers": 4,
  "n_connections": 4,
  "n_pending_connections": 0
}

Notes

I did not continue to faucet/token steps because the guide says to wait until the node reaches Online mode first.

[kashepavadan]

We've added macOS release paths to the tutorial. Feel free to resolve the conflicts and we'll review the PR again.

[weboko]

Dogfooded on Ubuntu 24.04.4 LTS x86_64. Followed the full quickstart with the changes in this PR applied.

What worked:

• Both URLs (circuits + node) for release 0.1.2 resolve correctly. The original 0.1.3-rc.1 circuits URL also resolves but points to a different asset; pinning both to 0.1.2 is the right call for consistency.
• tar -xf, mv to ~/.logos-blockchain-circuits, init with bootstrap peers, and --check-config all pass cleanly.
• lsof -nP -iTCP:8080 -sTCP:LISTEN works on Linux. Node API came up correctly on the default port.
• Both curl API endpoints (/cryptarchia/info, /network/info) returned expected JSON. Node started and reached Bootstrapping mode. Bootstrap peers at 65.108.203.235 timed out — expected, doc correctly says to use current addresses from the release notes.

Cannot verify: macOS (macos-aarch64) section — running on Linux x86_64. macOS asset URLs verified via HEAD request (HTTP 302 → valid).

Pre-existing gap (not introduced by this PR): jq is used in the curl commands but not listed in prerequisites. Worth a follow-up in the base doc.

Changes are accurate and improve the doc. LGTM.