General Overview

Hathor Forge is an all-in-one local blockchain development environment created for the Hathor Network. Instead of having to configure multiple services manually on your device, Hathor Forge gives you a ready-to-run stack that allows you to:

• Run a local blockchain node
• Create and manage wallets
• Mine tokens locally and automatically.
• Deploy and test Blueprints/Nano Contracts

Hathor Forge provides a user-friendly interface to interact with the local blockchain, making it easier for you to test and debug your applications.

What does Hathor Forge do?

When you start Hathor Forge, it automatically orchestrates multiple services that normally require manual setup and also enables different tools for them. These include:

• Hathor Node (hathor-core): A local instance of the Hathor blockchain network, allowing you to test transactions, token creation, and smart contracts without needing to connect to the mainnet or testnet.

• Headless Wallet Service: A local wallet management system that lets you create and manage wallets, addresses, and keys.

• CPU Miner (cpuminer): This can generate blocks so your network actually progresses as you develop and test your applications.

• Explorer: This layer serves as a tool for visualizing blocks, transactions, and addresses.

• API Layer: This is the backend of the Explorer, which provides RESTful endpoints for interacting with the local blockchain programmatically.

• Desktop App (Tauri + React): This is the Hathor Forge UI that will let you control and monitor everything.

Running Hathor Forge

There are currently three ways to get started with Hathor Forge depending on your preferences and needs.

We recommend the CLI method as the most straightforward way to use Hathor Forge, as it does not require any additional setup or cloning of repositories.

Prerequisites

• Git
• Node.js (LTS version recommended)
• Nix (optional, but recommended for the CLI method)

Repository Clone

To run Hathor Forge from the source code, make sure you have Rust installed in your device. Then, follow these steps:

1. Clone the repository:

git clone https://github.com/HathorNetwork/hathor-forge 
cd hathor-forge

2. Install dependencies:

npm install

3. Start the application:

npm run tauri dev

CLI (No GUI Needed)

You can also run the application directly with Nix, which requires no clone or installation.

1. Make sure you have Nix installed and configured on your system.

tip

You can find the installation page for NixOS here.

2. Once you have Nix set up, you can run one of the following commands to start Hathor Forge depending on your preference:

# Start everything: node + miner + wallet service + MCP server
nix run github:HathorNetwork/hathor-forge -- --start

# Start without the miner
nix run github:HathorNetwork/hathor-forge -- --start --no-miner

# Connect wallet-headless to an external node
nix run github:HathorNetwork/hathor-forge -- --wallet-only --fullnode-url http://mynode:8080

Available CLI Flags

Flag	Description
--start	Auto-start all local services
--wallet-only	Start only wallet-headless + MCP server
--no-miner	Skip CPU miner
--no-wallet	Skip wallet-headless
--no-tx-mining	Skip tx-mining-service
--fullnode-url <URL>	Connect to an external fullnode
--tx-mining-url <URL>	Connect to an external tx-mining-service
--mining-address <ADDR>	Custom mining reward address
--mcp-port <PORT>	MCP server port (default: 9876)
--save-settings	Persist flags to ~/.config/hathor-forge/cli-settings.json
--settings-file <PATH>	Custom settings file path

Downloadable Desktop App

Finally, you can opt to download the desktop application from the Releases page, where you can also build from the source using the following commands:

nix develop      # enter dev shell
npm install
dev-server       # starts frontend + Tauri

tip

If you are using the desktop application, make sure to move the installer/app to the Applications folder (for macOS) or the equivalent on your OS, to ensure that it has the necessary permissions to run all services correctly.

Services / Tools Ports

When you run Hathor Forge, it will automatically start the services and tools mentioned above. Here are the default ports they run on:

Service	Port
Fullnode API	8080
Stratum (mining)	8000
Wallet Headless	8001
Block Explorer	3001
MCP Server	9876