Skip to main content

​
Run a Kaspa Node

Running a Kaspa node allows you to participate directly in the Kaspa network. By running a node, you help validate transactions and maintain the security of the blockchain. This guide will walk you through the process step-by-step, regardless of your technical experience.

​
System Requirements

These requirements align with the Crescendo guide.

​
Minimum

  • CPU: 8 CPU cores
  • Memory: 16 GB RAM
  • Storage: 256 GB SSD
  • Network: 5 MB/s (≈ 40 Mbit/s) bandwidth

​
Preferred for higher performance (preferred for public node)

  • CPU: 12–16 CPU cores
  • Memory: 32 GB RAM
  • Storage: 512 GB SSD
  • Network: Higher bandwidth for robust peer support
Run your node on a dedicated computer that stays online 24/7. Shutting it down frequently hurts network connectivity and increases sync time.

​
What is Docker?

Docker is a tool that packages software into “containers” - think of it like a self-contained box that has everything the software needs to run. This makes it easy to run complex applications without worrying about installation conflicts or dependencies.
Don’t worry if you’ve never used Docker before! This guide will walk you through everything.

​
Step 1: Install Docker Desktop

First, we need to install Docker Desktop on your computer.
  • Windows
  • macOS
  • Linux

​
Windows Installation

Requirements:
  • Windows 10 64-bit (Pro, Enterprise, or Education) or Windows 11
  • At least 16 GB of RAM
Installation Steps:
  1. Download Docker Desktop
  2. Run the Installer
    • Double-click the downloaded Docker Desktop Installer.exe file
    • If prompted by Windows User Account Control, click “Yes” to allow the installer to run
    • Follow the installation wizard - the default settings work well for most users
  3. Restart Your Computer
    • After installation completes, restart your computer when prompted
  4. Start Docker Desktop
    • After restarting, Docker Desktop should start automatically
    • Look for the Docker icon (a whale) in your system tray (bottom-right corner of your screen)
    • If it doesn’t start automatically, search for “Docker Desktop” in your Start menu and open it
  5. Verify Installation
    • Open Command Prompt (search for “cmd” in the Start menu)
    • Type this command and press Enter: 
      docker --version
    • You should see something like Docker version 24.0.0, build xyz
If you encounter issues with WSL 2 (Windows Subsystem for Linux), Docker Desktop will guide you through the setup process.

​
Step 2: Download the Kaspa Node Image

Now that Docker is installed, we need to download the official Kaspa node software.
  • Windows
  • macOS
  • Linux
  1. Open Command Prompt (search for “cmd” in the Start menu)
  2. Type this command and press Enter: 
    docker pull kaspanet/rusty-kaspad:latest
  3. Wait for the download to complete - this may take a few minutes depending on your internet speed
  4. You’ll see progress bars showing the download status
The official Kaspa node image is maintained by the Kaspa development team and is available at https://hub.docker.com/r/kaspanet/rusty-kaspad.

​
Step 3: Create a Data Directory

Your Kaspa node needs a place to store blockchain data. Let’s create a dedicated folder for this.
  • Windows
  • macOS
  • Linux
  1. Open File Explorer
  2. Navigate to your C: drive (or wherever you have plenty of space)
  3. Create a new folder called kaspa-data
  4. Note the full path - it should be something like C:\kaspa-data
Alternatively, using Command Prompt:
mkdir C:\kaspa-data
Make sure you have at least 256 GB of free space in the location where you create this folder. The blockchain data will grow over time.

​
Step 4: Start Your Kaspa Node

Now we’re ready to start the Kaspa node! This is where the magic happens.
  • Windows
  • macOS
  • Linux
In Command Prompt, run this command (replace C:\kaspa-data with your actual path if different):
docker run -d --name kaspa-node --restart unless-stopped -v C:\kaspa-data:/app/data -p 16110:16110 -p 16111:16111 -p 17110:17110 -p 18110:18110 kaspanet/rusty-kaspad:latest
What this command does:
  • docker run: Starts a new container
  • -d: Runs it in the background (detached mode)
  • --name kaspa-node: Names the container “kaspa-node” so you can easily reference it
  • --restart unless-stopped: Automatically restarts the node if it crashes or your computer reboots
  • -v C:\kaspa-data:/app/data: Connects your kaspa-data folder to the container
  • -p 16110:16110 -p 16111:16111 -p 17110:17110 -p 18110:18110: Opens ports (see Understanding the Ports)
  • kaspanet/rusty-kaspad:latest: Uses the latest version of the Kaspa node software
If the command runs successfully, you’ll see a long string of characters (the container ID). This means your node is now running!

​
Step 5: Monitor Your Node

Your node is now running, but it needs time to synchronize with the Kaspa network. Let’s check on its progress.
  • Docker Desktop
  • Terminal Commands
If you’re using Docker Desktop on Windows or macOS, you can monitor your node using the graphical interface:
  1. Open Docker Desktop
    • Click the Docker icon in your system tray (Windows) or menu bar (macOS)
    • Select “Dashboard” or just open the Docker Desktop application
  2. Find Your Node
    • You’ll see a list of running containers
    • Look for the container named kaspa-node
    • It should show a green “Running” status
  3. View Logs
    • Click the kaspa-node container
    • Open the “Logs” tab to see real-time output (auto-updates)
  4. Check Resource Usage
    • See CPU, memory, and network usage in container details
  5. Container Actions
    • From Docker Desktop, you can easily:
      • Stop the container (Stop button)
      • Start it again (Start button)
      • Restart it (Restart button)
      • Delete it (Delete button - be careful!)
Docker Desktop lets you manage the node without terminal commands.

​
Understanding Synchronization

When you first start your node, it needs to download and verify the existing data on the Kaspa blockchain. This process is called “synchronization” or “syncing.”
  • Initial sync time: Several hours to a day, depending on your internet speed and computer performance
  • What’s happening: Your node is downloading blocks and verifying transactions
  • Normal behavior: High CPU and network usage during initial sync
Your node is fully synced when you see messages like “Accepted block …” appearing regularly.

​
Step 6: Make Your Node Public (Optional)

The heart of Kaspa is its network of public nodes. By making your node public, you’re contributing directly to the decentralization and resilience of the Kaspa network.

​
What Does “Public” Mean?

A public node allows other nodes in the Kaspa network to connect to it for peer-to-peer communication. This helps:
  • Strengthen the network: More public nodes mean better network connectivity
  • Support new nodes: Help other nodes sync faster
  • Increase decentralization: Distribute network load across more participants

​
Requirements for a Public Node

  • Stable internet connection: Your node should be online consistently
  • Sufficient bandwidth: You’ll be sharing data with other nodes
  • Port forwarding: Port 16111 (P2P) needs to be accessible from the internet

​
Opening the P2P Port

If your computer is on a private network behind a router that supports UPnP (Universal Plug and Play), you can easily open the P2P port (16111) using this command:
  • Linux/macOS
  • Windows
  • Manual Router Configuration
sudo docker run --rm --network=host alpine sh -c 'apk add miniupnpc; upnpc -r 16111 tcp'
What this command does:
  • Uses a temporary Alpine Linux container to run UPnP commands
  • Installs miniupnpc (a UPnP client)
  • Requests your router to forward port 16111 (TCP) to your computer
  • The container removes itself after completing the task (--rm flag)
If the command fails, you may need to manually configure port forwarding on your router.

​
Verifying Your Public Node

After opening the port, you can verify your node is publicly accessible:
  1. Check your public IP:
  2. Test the port:
    • Use an online port checker to verify port 16111 is open
    • Wait a few minutes after configuration for changes to take effect
  3. Monitor connections:
    • Check your node logs for incoming peer connections
    • You should see messages about peers connecting to your node
Running a public node is entirely optional, but it’s a great way to give back to the Kaspa community and strengthen the network!

​
Considerations

  • Firewall: Make sure your computer’s firewall allows incoming connections on port 16111
  • Dynamic IP: If your ISP assigns you a dynamic IP address, your public IP may change periodically
  • Security: Opening a port is generally safe, but make sure only port 16111 is exposed
  • Bandwidth: Public nodes may use more bandwidth as other nodes connect to sync data

​
Step 7: Managing Your Node

  • Docker Desktop
  • Terminal Commands

​
Using Docker Desktop

​
Stop Your Node

  1. Open Docker Desktop
  2. Find the kaspa-node container in the list
  3. Click the Stop button (square icon)
  4. The container status will change to “Exited”

​
Start Your Node (After Stopping)

  1. Open Docker Desktop
  2. Find the kaspa-node container in the list
  3. Click the Start button (play icon)
  4. The container status will change to “Running”

​
Restart Your Node

  1. Open Docker Desktop
  2. Find the kaspa-node container in the list
  3. Click the Restart button (circular arrow icon)
  4. The node will stop and start again

​
Remove Your Node

If you want to completely remove the node container (but keep your blockchain data):
  1. Open Docker Desktop
  2. Find the kaspa-node container in the list
  3. Stop the container first (if it’s running)
  4. Click the Delete button (trash icon)
  5. Confirm the deletion
Make sure you stop the container before deleting it. Your blockchain data in the kaspa-data folder will be preserved.
To start fresh, you would then need to run the docker run command from Step 4 again.

​
Update Your Node

When a new version of the Kaspa node is released:
  1. Stop and remove the current node:
    • Open Docker Desktop
    • Stop the kaspa-node container
    • Delete the kaspa-node container
  2. Download the latest image:
    • Go to the “Images” section in Docker Desktop
    • Search for kaspanet/rusty-kaspad
    • Click the pull/download icon to get the latest version Or use terminal:
    docker pull kaspanet/rusty-kaspad:latest
  3. Start the node again using the docker run command from Step 4
Your blockchain data will be preserved in the kaspa-data folder!

​
Troubleshooting

Problem: When you type docker --version, you get an error saying “command not found” or “docker is not recognized.”Solution:
  • Make sure Docker Desktop is running (check for the whale icon in your system tray/menu bar)
  • On Windows: Try closing and reopening Command Prompt
  • On macOS/Linux: Try opening a new Terminal window
  • If still not working, restart your computer
Problem: Error message says “port 16110 or 16111 is already allocated.”Solution:
  • Another application is using these ports
  • Check if you already have a Kaspa node running: docker ps
  • If you see kaspa-node already running, stop it first: docker stop kaspa-node
  • Remove the old container: docker rm kaspa-node
  • Try starting the node again
Problem: Error about insufficient disk space.Solution:
  • Free up at least 256 GB of space on your drive
  • Consider moving your kaspa-data folder to a drive with more space
  • Update the -v parameter in the docker run command to point to the new location
Problem: The node has been syncing for many hours.Solution:
  • Initial sync can take 12-24 hours or more - this is normal
  • Check the logs to ensure blocks are still being downloaded: docker logs -f kaspa-node
  • As long as you see new blocks being accepted, the sync is progressing
  • Ensure you have a stable internet connection
Problem: The node container keeps stopping and restarting.Solution:
  • Check the logs for error messages: docker logs kaspa-node
  • Common causes:
    • Insufficient RAM (need at least 16 GB available)
    • Corrupted blockchain data (may need to delete kaspa-data folder and start over)
    • System resource constraints (close other applications)
  • If you see errors about database corruption, you may need to resync from scratch
Problem: The node logs show “permission denied” errors when trying to write data.Solution:
  • This is a common issue on Linux systems
  • Stop the node: docker stop kaspa-node
  • Remove the container: docker rm kaspa-node
  • Set the correct permissions on your data folder: 
    sudo chown 50051:50051 -R ~/kaspa-data
  • Start the node again using the docker run command from Step 4
Why this happens: The Docker container runs as user ID 50051, so the data folder must be owned by this user on Linux systems.

​
Understanding the Ports

Your Kaspa node uses four network ports:
  • Port 16110 (gRPC): The main RPC port for gRPC communication. This is the primary way applications interact with your node.
  • Port 16111 (P2P): Used for peer-to-peer communication with other Kaspa nodes on the network.
  • Port 17110 (Borsh RPC): Used for Borsh-encoded RPC communication. This is a binary serialization format used by some applications.
  • Port 18110 (JSON RPC): Used for JSON-encoded RPC communication. This is useful for applications that prefer JSON over gRPC.
If your goal is to run a public node, it’s sufficient to expose the P2P port (16111).

​
Next Steps

Now that your Kaspa node is running, you can:
  • Support the network: By running a node, you’re helping secure and decentralize Kaspa
  • Make it public: Follow the section above to open your node to the network
  • Monitor performance: Watch the logs to see your node processing transactions in real-time
  • Learn more: Check out the Kaspa Wiki for advanced configuration options

​
Additional Resources

Need Help?

Join the Kaspa Discord community for live support and to connect with other node operators.

​
Congratulations! 🎉

You’re now running your own Kaspa node! This is an important contribution to the Kaspa network’s decentralization and security. Thank you for participating in the network!
⌘I