Run a node with MyTonCtrl

Provision hardware, install MyTonCtrl, and follow runbooks for validator, liteserver, or archive roles.

Plan the environment

Supported operating systems

MyTonCtrl is tested on the following distributions (choose one and keep it up to date):

• Ubuntu 22.04 LTS or 24.04 LTS
• Debian 11 or 12

Always create and use a non-root operator with sudo access—running MyTonCtrl as root leads to subtle permission failures later on.

Hardware sizing by role

Role	CPU	RAM	Storage	Network	Traffic	Notes
Full/validator node	16 dedicated cores (32 threads preferred)	128 GB	≥1 TB NVMe SSD or provisioned 64k+ IOPS	≥1 Gbps up/down	64 TB/month typical (peaks ~100 TB)	Leave headroom for elections and snapshots.
Liteserver	16 cores	128 GB	≥1 TB NVMe SSD	≥1 Gbps	~16 TB/month peaks	Hetzner/OVH are acceptable for liteservers (not for validators).
Archive liteserver	16 cores	128 GB	≥12 TB NVMe or ZFS pool with compression	≥1 Gbps	≥16 TB/month	Plan for continuous growth; monitor ZFS capacity.

Disk latency is the common bottleneck. Benchmark storage before going live (MyTonCtrl> benchmark).

Network and ports

• Obtain a static public IPv4 address for each node.
• Forward a single UDP port (default 30303) from the internet to the node and leave all outbound ports open. Verify exposure with netstat -tulpn and third-party scanners.
• Update cloud security groups or on-prem firewalls after installation—use MyTonCtrl> about validator / about liteserver to confirm the chosen port.

Recommended providers

The TON Foundation validates the following instances for validator-class workloads:

Cloud Provider	Instance Type	CPU	RAM	Storage	Network	Public IP	Traffic
GCP	n2-standard-16	32 vCPUs	128 GB	1 TB NVMe SSD	16 Gbps	Static external IP	64 TB/month
Alibaba Cloud	ecs.g6.4xlarge	32 vCPUs	128 GB	1 TB NVMe SSD	Up to 10 Gbps	Elastic IP	64 TB/month
Tencent Cloud	M5.4XLARGE	32 vCPUs	128 GB	1 TB NVMe SSD	Up to 10 Gbps	Elastic IP	64 TB/month
Vultr	Bare metal Intel E-2388G	16C/32T	128 GB	1.92 TB NVMe SSD	10 Gbps	Fixed	64 TB/month
DigitalOcean	General purpose premium Intel	32 vCPUs	128 GB	1 TB NVMe SSD	10 Gbps	Fixed	64 TB/month
Latitude	c3.medium.x86	16C/32T	128 GB	1.9 TB NVMe SSD	10 Gbps	Fixed	64 TB/month
AWS	i4i.8xlarge	32 vCPUs	256 GB	2×3.75 TB Nitro SSD	Up to 25 Gbps	Elastic IP	64 TB/month

Prepare the operator account

If you still need a dedicated operator, create and switch to it before installing MyTonCtrl:

sudo adduser <USERNAME>
sudo usermod -aG sudo <USERNAME>
# reconnect as the new user
ssh <USERNAME>@<SERVER_IP>

Install MyTonCtrl

Run the installer from the operator account with sudo so it can create system users and services:

sudo apt update
sudo apt install -y curl wget git ca-certificates python3-pip
wget https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/scripts/install.sh
sudo bash install.sh -d

The interactive wizard walks through:

1. Selecting mainnet vs. testnet (or supplying a custom global.config.json).
2. Choosing the initial mode (validator or liteserver).
3. Optionally downloading blockchain dumps via TON Storage (recommended for archive builds).
4. Whether to run post-download tasks in the background (useful when pulling large dumps).

Refer to the MyTonCtrl overview for installer flags and environment variables when you need unattended deployments.

Verify services and synchronization

mytonctrl
MyTonCtrl> status
MyTonCtrl> status_fast
MyTonCtrl> status_modes

• status shows the long-form report, including Local validator initial sync status—wait for it to read synchronized before switching roles.
• status_fast prints live metrics such as timeDiff and Local validator out of sync; both should trend toward zero on a healthy node.
• status_modes confirms which modes are currently enabled.

After installation, verify ownership so MyTonCtrl and validator processes can access state and keys:

sudo chown -R validator:validator /var/ton-work/db
sudo chown -R <install_user>:<install_user> /var/ton-work/keys

Baseline maintenance tasks

• MyTonCtrl> create_backup and restore_backup safeguard your configs and keys—run before upgrades and after major changes.
• MyTonCtrl> set sendTelemetry true sends telemetry to the MyTonCtrl developers so they can surface TON status alerts and diagnose emerging issues.
• MyTonCtrl> update followed by upgrade applies MyTonCtrl and binary updates; schedule regular maintenance windows.
• MyTonCtrl> settings_status reviews every setting, its owner mode, and the current value.
• Use tail -F /var/ton-work/log* and journalctl -u validator -f during troubleshooting; reduce verbosity again if you temporarily ran installer set_node_argument --verbosity 3.

Validator quickstart

You need: a fully synchronized node, validator mode not active elsewhere, and at least the current minimum stake (approximately 300,000 TON; check tonscan.com/validation for live numbers).

Prepare the validator wallet (one-time)

1. List existing wallets: MyTonCtrl> wl. The installer usually creates validator_wallet_001.

2. If you need a dedicated wallet, create one (example):

   MyTonCtrl> nw 0 validator_wallet v3 1001
   

3. Fund the wallet, inspect recent activity with vas <wallet_name>, then activate it:

   MyTonCtrl> aw validator_wallet
   

4. Tell MyTonCtrl which wallet to use for elections:

   MyTonCtrl> set validatorWalletName "validator_wallet"
   MyTonCtrl> get validatorWalletName
   

5. Export and store the private key offline: MyTonCtrl> ew validator_wallet.

Need more wallet operations? See the wallet command reference.

Enable validator mode

Disable conflicting roles (liteserver cannot run alongside validator) and switch modes:

MyTonCtrl> disable_mode liteserver
MyTonCtrl> enable_mode validator
MyTonCtrl> status_modes
MyTonCtrl> about validator

Confirm that validator shows as enabled and note the advertised ADNL port for firewall rules.

Configure staking policy

Assign either a fixed stake or a percentage of wallet balance:

MyTonCtrl> set stake 500000
# or
MyTonCtrl> set stakePercent 99

get stake / get stakePercent display the stored values; adjust before each election window if your balance changes.

Election routine

Use the same sequence every election cycle (automate with cron if desired):

MyTonCtrl> status_fast
MyTonCtrl> ve
MyTonCtrl> check_ef

• Wait until Local validator out of sync is below 20 before running ve.
• ve submits election messages, check_ef reports the previous and current round efficiency.
• MyTonCtrl automatically splits balances into two stakes when the Elector accepts your bid; withdrawals become available in the following election per protocol rules.

Operational discipline

• Track network announcements via @tonstatus and enable notifications.
• Keep hardware aligned with the minimum system requirements; upgrade storage promptly if metrics show saturation.
• Leave telemetry enabled (set sendTelemetry true) so telemetry continues reaching the MyTonCtrl developers and they can warn the community about issues.
• Monitor RAM, disk, CPU, and bandwidth dashboards. Contact @mytonctrl_help_bot if metrics or efficiency drop below target.
• Re-run check_ef or consult the efficiency API when diagnosing performance.

Liteserver quickstart

You need: a synchronized full node with validator mode disabled (liteserver cannot run alongside validator on the same machine).

Activate liteserver services

MyTonCtrl> enable_mode liteserver
MyTonCtrl> status_modes

Configure endpoints and proxies

MyTonCtrl> installer
Installer> enable LS
Installer> plsc
Installer> exit

• enable LS deploys the liteserver daemon.
• plsc prints the client bundle—share it with /var/ton-work/keys/liteserver.pub so lite-clients can connect.
• Regenerate configs at any time with installer clcf.

Open the liteserver port

1. Check the port in /var/ton-work/db/config.json (within the liteservers array).

2. Update security groups or configure ufw on bare-metal hosts:

   sudo apt install -y ufw
   sudo ufw allow ssh
   sudo ufw allow <port>
   sudo ufw enable
   sudo ufw status
   

3. Confirm connectivity by initializing a lite-client using the generated config.

Ongoing care

• Monitor netLoadAvg and CPU via status_fast; scale hardware before saturation.
• Export create_backup after any config change so you can rapidly rebuild liteserver hosts.
• Keep ports private—front them with VPNs or proxies when exposing to public users.

Archive liteserver quickstart

You need: liteserver mode enabled, ≥12 TB of fast storage, and ZFS installed for handling compressed dumps.

Prepare storage with ZFS

sudo apt install -y zfsutils-linux
sudo zpool create data <disk>
sudo zfs set compression=lz4 data
sudo zfs create data/ton-work
sudo zfs set mountpoint=/var/ton-work data/ton-work

Use a dedicated SSD-backed pool and monitor free space—archive size grows continually (check the archive dump index).

Install and download archive data

Run the installer, choose liteserver mode, and answer Yes (1) when prompted to download archive blocks via TON Storage. Allow the job to continue in the background—the download may take days.

Track progress in MyTonCtrl logs and wait for status → Local validator initial sync status to report synchronized before serving traffic.

Troubleshooting imports

Increase verbosity temporarily to review archive import logs, then revert:

MyTonCtrl> installer set_node_argument --verbosity 3
tail -f /var/ton-work/log*
# ...review output...
MyTonCtrl> installer set_node_argument --verbosity 1

If you see repeated Importing archive ... from net messages, investigate storage latency—IOPS may be insufficient.

Snapshot and recovery tips

• Use ZFS snapshots (zfs snapshot data/ton-work@<label>) for fast rollbacks.
• To restore, stop services before zfs rollback: sudo systemctl stop validator.
• Keep off-site backups of /var/ton-work/keys and create_backup archives.

Monitoring and support

• Subscribe to @tonstatus and @tonstatus_notifications for real-time validator alerts.
• Use the private alert bot once your node is stable: MyTonCtrl> enable_mode alert-bot then configure credentials per the alerting guide.
• Contact validator support via @validators_help_bot; regular node operators can use @ton_node_help.
• Audit node health weekly: status_fast, check_ef, disk usage (du -sh /var/ton-work/db), and snapshot consistency.

Once comfortable with these workflows, dive into the detailed command references for advanced automation.