Native kaspad on macOS guide

Before you start

A Mac with Apple silicon (M1 or newer). There is no build for Intel Macs
A terminal, and sudo
8 processor cores
16 GB of memory, 32 GB recommended
640 GB free on an SSD, 1 TB recommended
A steady connection of 80 Mbit/s (10 MB/s) or more

Download kaspad

Get the official build from the Rusty Kaspa releases page.

Open the releases page and take the newest release, marked Latest.
Under Assets, download the .zip for macOS.
Double-click it in Downloads to unzip it.

Install it

Put kaspad in /usr/local/bin, so it runs from anywhere, and make its data folder.

Replace the path with the one find ~/Downloads -name kaspad -type f prints:

sudo install -m 755 ~/Downloads/PATH/TO/kaspad /usr/local/bin/kaspad
mkdir -p ~/.kaspad/logs
which kaspad
kaspad --version

macOS blocks programs downloaded from the internet. If it refuses to run kaspad, clear the block once:

sudo xattr -d com.apple.quarantine /usr/local/bin/kaspad

Or open System Settings, Privacy & Security, and choose Open Anyway next to kaspad.

It is installed when

which kaspad prints /usr/local/bin/kaspad
kaspad --version prints a version

Run it once

Start it by hand first. Problems are much easier to see here than once it runs in the background.

kaspad --utxoindex --appdir=~/.kaspad

--utxoindex: Keeps an index for balance lookups (recommended)
--appdir: Keeps the chain in ~/.kaspad

It is working when the log shows

kaspad starting, with its version
Peers connecting, 8 or more of them
Headers, then blocks, downloading

Ctrl+C stops it. Next time it carries on syncing where it stopped.

Start it with the Mac

launchd, the Mac's service manager, starts kaspad when you log in and restarts it if it stops.

Save this, replacing USERNAME in all three places with your Mac username:

~/Library/LaunchAgents/com.kaspa.kaspad.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.kaspa.kaspad</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/kaspad</string>
    <string>--utxoindex</string>
    <string>--appdir=/Users/USERNAME/.kaspad</string>
    <string>--rpclisten=127.0.0.1:16110</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/Users/USERNAME/.kaspad/logs/kaspad.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/USERNAME/.kaspad/logs/kaspad.error.log</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.kaspa.kaspad.plist
launchctl list | grep kaspad

It is running when

launchctl lists com.kaspa.kaspad with a process number
The log fills up at ~/.kaspad/logs/kaspad.log
It is running again after you restart the Mac

Day-to-day commands

Everything you'll need once it is running.

Follow the log: tail -f ~/.kaspad/logs/kaspad.log
Errors only: grep -i "error\|warn" ~/.kaspad/logs/kaspad.log | tail -20
Is it synced?: tail -n 50 ~/.kaspad/logs/kaspad.log | grep -i "sync\|height"
Stop, start: launchctl unload ~/Library/LaunchAgents/com.kaspa.kaspad.plist launchctl load ~/Library/LaunchAgents/com.kaspa.kaspad.plist
Disk used, and free: du -sh ~/.kaspad df -h ~
Memory and processor: top -pid $(pgrep kaspad)

Make it public

Optional, and the most useful thing you can do: a public node helps new nodes join and sync. On a hosted server, opening the firewall is usually enough.

Keep the macOS firewall on, and only forward port 16111.

At home, kaspad asks your router to open the port by itself (UPnP), which many routers allow. If it doesn't become public, forward the port by hand:

Find this machine's local address: System Settings, Network, your connection, Details.
Open your router's admin page, usually at 192.168.1.1 or 192.168.0.1.
Forward external TCP port 16111 to that address, port 16111.

Router menus differ. portforward.com has steps for most models.

It is public when

The log shows inbound peers
It appears on KasNodes after the next crawl

Troubleshooting

The usual problems and what fixes them.

bad CPU type in executable

The release is only built for Apple silicon (M1 or newer). On an Intel Mac, build it from source or use Docker.

command not found: kaspad

Check ls -l /usr/local/bin/kaspad exists and echo $PATH includes /usr/local/bin. The full path, /usr/local/bin/kaspad, always works.

macOS keeps blocking kaspad

Clear the quarantine flag: sudo xattr -d com.apple.quarantine /usr/local/bin/kaspad.

The launchd service won't start

Read ~/.kaspad/logs/kaspad.error.log. Usually USERNAME wasn't replaced, the logs folder doesn't exist (mkdir -p ~/.kaspad/logs), or the plist has a typo.

The log file is huge

Delete it and kaspad starts a new one, or rotate it with newsyslog.

It shows 0 peers

It can't reach the network. Check the connection and that nothing blocks outbound traffic, check the log for errors, and restart it.

The disk is filling up

Check what kaspad uses, free some space, or move the data folder to a larger disk by changing --appdir. Keep 640 GB free for it; 1 TB is better.

It isn't public after opening the port

Check the firewall rule and the router rule are both TCP 16111 and point at the right machine. Some hosts and home providers put you behind their own NAT, which blocks inbound connections.

Running? Put your name on it.

Once the node shows up in a crawl you can claim it, pick a public name and follow its rank.

All setup methods Claim my node