Skip to main content

Hathor Forge 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

When to use Hathor Forge​

Reach for Hathor Forge instead of connecting to testnet when you want:

  • Local development with no network dependency — everything runs on your machine, so you can work offline and without waiting on public infrastructure.
  • Fast iteration — the local miner produces blocks on demand, so transactions confirm in seconds rather than at network cadence.
  • Isolated testing of Blueprints and Nano Contracts — deploy, break, and reset freely without affecting anyone else or spending testnet funds.
  • Reproducible CI/CD environments — spin up a clean, private network per pipeline run.

Use testnet instead when you need to validate against real network conditions, multi-party interactions, or the exact software versions running in production.

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.

  • MCP Server: Exposes a Model Context Protocol endpoint so AI tools and agents can interact with the local Hathor environment programmatically — starting the node, creating and funding wallets, and querying the blockchain. See MCP implementation in Hathor Forge.

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 18+ (LTS recommended)
  • Nix — required for the CLI method, optional otherwise
  • Rust 1.70+ — required only for the Repository Clone method (Tauri builds the desktop app from Rust source)

Platform support: Nix and the CLI method run on Linux and macOS. Windows users should use WSL2.

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
  1. Install dependencies:
npm install
  1. 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.

  1. 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
FlagDescription
--startAuto-start all local services
--wallet-onlyStart only wallet-headless + MCP server
--no-minerSkip CPU miner
--no-walletSkip wallet-headless
--no-tx-miningSkip 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-settingsPersist 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

Here, dev-server is a helper command provided inside the Nix dev shell (entered via nix develop); it is not a global executable. It starts the frontend and the Tauri desktop app together, equivalent to npm run tauri dev.

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:

ServicePort
Fullnode API8080
Stratum (mining)8000
Wallet Headless8001
Block Explorer3001
MCP Server9876

Verifying your setup​

Once Hathor Forge is running, confirm the stack came up:

  • Full node: curl http://localhost:8080/v1a/version returns the node version as JSON.
  • Block Explorer: open http://localhost:3001 in a browser — you should see blocks being produced.
  • Wallet service: curl http://localhost:8001/ responds (the headless wallet is up on port 8001).

If you started Forge via the desktop app, each service also shows a running/stopped indicator in the UI.

:::warning Local development only

Hathor Forge is designed for local development. Do not use it in production, and do not expose its services (node, wallet, explorer, MCP) to public networks — the wallet service is unauthenticated and can move funds.

:::

Next steps​

Was this page helpful?