Setting up a local blockchain using MyLocalTon

Install MyLocalTon to spin up a self-contained TON network for development and testing.

MyLocalTon packages validator nodes, a lite-server, explorer, and optional HTTP API into a single JAR so you can prototype locally without touching mainnet. Use it for integration tests, smart-contract dry runs, and demos before deploying to public networks.

Prerequisites

• Java Development Kit (JDK) 21 or newer in your PATH.
• Python 3.9-3.12 if you plan to enable the optional HTTP API bridge.
• On Windows, install the Microsoft Visual C++ 2015+ x64 Redistributable.
• Allocate at least 4 CPU cores, 16 GB RAM, and 20 GB of free disk space for smooth operation.

Download and install

Windows

1. Install the Visual C++ Redistributable.
2. Download the JAR that matches your architecture from the MyLocalTon releases.
   • MyLocalTon-x86-64.jar for x86-64 systems.
   • MyLocalTon-arm64.jar for ARM64 systems.

macOS and Linux

# x86-64
wget https://github.com/neodix42/MyLocalTon/releases/latest/download/MyLocalTon-x86-64.jar
# ARM64
wget https://github.com/neodix42/MyLocalTon/releases/latest/download/MyLocalTon-arm64.jar

Grant execute permissions if you prefer to run the JAR directly: chmod +x MyLocalTon-*.jar.

Build from source

sudo apt install default-jdk ant maven
git clone https://github.com/neodix42/MyLocalTon.git
cd MyLocalTon
mvn clean package assembly:single

The packaged JARs appear under target/ when the build finishes.

Launch the local network

java -jar MyLocalTon-x86-64.jar

Useful arguments:

Flag	Description
nogui	Run in headless mode without the Swing interface.
with-validators=<N>	Start N validator instances (default: 1).
explorer	Launch the bundled block explorer.
ton-http-api	Start the HTTP API bridge (requires Python + ton-http-api).
custom-binaries=<PATH>	Load TON binaries from a custom directory.
ip.addr.X.X	Bind services to a specific local IP.
debug	Increase log verbosity for troubleshooting.

The first run creates the myLocalTon/ workspace alongside the JAR. Validators, liteserver certificates, and logs live in this directory.

Connect CLI tools

MyLocalTon prints the lite-server public key during startup and stores certificates in ./myLocalTon/genesis/bin/certs/.

lite-client -a 127.0.0.1:4443 -b <BASE64_PUBLIC_KEY> -c last
validator-engine-console \
  -a 127.0.0.1:4441 \
  -k $(pwd)/myLocalTon/genesis/bin/certs/client \
  -p $(pwd)/myLocalTon/genesis/bin/certs/server.pub

Replace <BASE64_PUBLIC_KEY> with the key printed in the MyLocalTon logs.

Enable the HTTP API bridge

On Windows, install OpenSSL v1.1.1 first

Install Python dependencies on the host system, then restart MyLocalTon with the ton-http-api flag or enable “Start TON Center” toggle in UI.

# Linux
sudo apt install -y python3 python3-pip
pip3 install --user ton-http-api

# macOS (Homebrew)
brew install python3
python3 -m ensurepip --upgrade
pip3 install --user ton-http-api

# Windows
py -3 -m ensurepip --upgrade
py -3 -m pip install --user ton-http-api

The bridge exposes REST endpoints that mirror the lite-server APIs for tooling that cannot speak the native ADNL protocol.

Monitor and maintain

• Tail myLocalTon/MyLocalTon.log for application-level events.
• Validator logs reside in myLocalTon/genesis/db/log.
• Re-run with debug when reproducing issues.
• Upgrade by downloading the latest JAR, replacing the existing file, and deleting the myLocalTon directory so the genesis state regenerates.

Troubleshooting tips

Symptom	Resolution
JAR fails to start	Verify Java 21+ is installed and the file is not quarantined by the OS (macOS: xattr -d com.apple.quarantine <JAR>).
HTTP API errors	Ensure Python 3.9-3.12 and ton-http-api are installed.
Need a clean reset	Stop the process, delete the myLocalTon folder, and restart the JAR to regenerate the network.

Where to go next

• Graduate to production setups with Setting up a node using MyTonCtrl.
• Explore node roles and responsibilities in the node overview.