> ## Documentation Index
> Fetch the complete documentation index at: https://companyname-a7d5b98e-v2-pagination.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a node with MyTonCtrl

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

export const Aside = ({type = "note", title = "", icon = "", iconType = "regular", children}) => {
  const asideVariants = ["note", "tip", "caution", "danger"];
  const asideComponents = {
    note: {
      outerStyle: "border-sky-500/20 bg-sky-50/50 dark:border-sky-500/30 dark:bg-sky-500/10",
      innerStyle: "text-sky-900 dark:text-sky-200",
      calloutType: "note",
      icon: <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="w-4 h-4 text-sky-500" aria-label="Note">
          <path fill-rule="evenodd" clip-rule="evenodd" d="M7 1.3C10.14 1.3 12.7 3.86 12.7 7C12.7 10.14 10.14 12.7 7 12.7C5.48908 12.6974 4.0408 12.096 2.97241 11.0276C1.90403 9.9592 1.30264 8.51092 1.3 7C1.3 3.86 3.86 1.3 7 1.3ZM7 0C3.14 0 0 3.14 0 7C0 10.86 3.14 14 7 14C10.86 14 14 10.86 14 7C14 3.14 10.86 0 7 0ZM8 3H6V8H8V3ZM8 9H6V11H8V9Z"></path>
        </svg>
    },
    tip: {
      outerStyle: "border-emerald-500/20 bg-emerald-50/50 dark:border-emerald-500/30 dark:bg-emerald-500/10",
      innerStyle: "text-emerald-900 dark:text-emerald-200",
      calloutType: "tip",
      icon: <svg width="11" height="14" viewBox="0 0 11 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="text-emerald-600 dark:text-emerald-400/80 w-3.5 h-auto" aria-label="Tip">
          <path d="M3.12794 12.4232C3.12794 12.5954 3.1776 12.7634 3.27244 12.907L3.74114 13.6095C3.88471 13.8248 4.21067 14 4.46964 14H6.15606C6.41415 14 6.74017 13.825 6.88373 13.6095L7.3508 12.9073C7.43114 12.7859 7.49705 12.569 7.49705 12.4232L7.50055 11.3513H3.12521L3.12794 12.4232ZM5.31288 0C2.52414 0.00875889 0.5 2.26889 0.5 4.78826C0.5 6.00188 0.949566 7.10829 1.69119 7.95492C2.14321 8.47011 2.84901 9.54727 3.11919 10.4557C3.12005 10.4625 3.12175 10.4698 3.12261 10.4771H7.50342C7.50427 10.4698 7.50598 10.463 7.50684 10.4557C7.77688 9.54727 8.48281 8.47011 8.93484 7.95492C9.67728 7.13181 10.1258 6.02703 10.1258 4.78826C10.1258 2.15486 7.9709 0.000106649 5.31288 0ZM7.94902 7.11267C7.52078 7.60079 6.99082 8.37878 6.6077 9.18794H4.02051C3.63739 8.37878 3.10743 7.60079 2.67947 7.11294C2.11997 6.47551 1.8126 5.63599 1.8126 4.78826C1.8126 3.09829 3.12794 1.31944 5.28827 1.3126C7.2435 1.3126 8.81315 2.88226 8.81315 4.78826C8.81315 5.63599 8.50688 6.47551 7.94902 7.11267ZM4.87534 2.18767C3.66939 2.18767 2.68767 3.16939 2.68767 4.37534C2.68767 4.61719 2.88336 4.81288 3.12521 4.81288C3.36705 4.81288 3.56274 4.61599 3.56274 4.37534C3.56274 3.6515 4.1515 3.06274 4.87534 3.06274C5.11719 3.06274 5.31288 2.86727 5.31288 2.62548C5.31288 2.38369 5.11599 2.18767 4.87534 2.18767Z"></path>
        </svg>
    },
    caution: {
      outerStyle: "border-amber-500/20 bg-amber-50/50 dark:border-amber-500/30 dark:bg-amber-500/10",
      innerStyle: "text-amber-900 dark:text-amber-200",
      calloutType: "warning",
      icon: <svg className="flex-none w-5 h-5 text-amber-400 dark:text-amber-300/80" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" aria-label="Warning">
          <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path>
        </svg>
    },
    danger: {
      outerStyle: "border-red-500/20 bg-red-50/50 dark:border-red-500/30 dark:bg-red-500/10",
      innerStyle: "text-red-900 dark:text-red-200",
      calloutType: "danger",
      icon: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor" className="text-red-600 dark:text-red-400/80 w-4 h-4" aria-label="Danger">
          <path d="M17.1 292c-12.9-22.3-12.9-49.7 0-72L105.4 67.1c12.9-22.3 36.6-36 62.4-36l176.6 0c25.7 0 49.5 13.7 62.4 36L494.9 220c12.9 22.3 12.9 49.7 0 72L406.6 444.9c-12.9 22.3-36.6 36-62.4 36l-176.6 0c-25.7 0-49.5-13.7-62.4-36L17.1 292zm41.6-48c-4.3 7.4-4.3 16.6 0 24l88.3 152.9c4.3 7.4 12.2 12 20.8 12l176.6 0c8.6 0 16.5-4.6 20.8-12L453.4 268c4.3-7.4 4.3-16.6 0-24L365.1 91.1c-4.3-7.4-12.2-12-20.8-12l-176.6 0c-8.6 0-16.5 4.6-20.8 12L58.6 244zM256 128c13.3 0 24 10.7 24 24l0 112c0 13.3-10.7 24-24 24s-24-10.7-24-24l0-112c0-13.3 10.7-24 24-24zM224 352a32 32 0 1 1 64 0 32 32 0 1 1 -64 0z"></path>
        </svg>
    }
  };
  let variant = type;
  let gotInvalidVariant = false;
  if (!asideVariants.includes(type)) {
    gotInvalidVariant = true;
    variant = "danger";
  }
  const iconVariants = ["regular", "solid", "light", "thin", "sharp-solid", "duotone", "brands"];
  if (!iconVariants.includes(iconType)) {
    iconType = "regular";
  }
  return <>
      <div className={`callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border ${asideComponents[variant].outerStyle}`} data-callout-type={asideComponents[variant].calloutType}>
        <div className="mt-0.5 w-4" data-component-part="callout-icon">
          {}
          {icon === "" ? asideComponents[variant].icon : <Icon icon={icon} iconType={iconType} size={14} />}
        </div>
        <div className={`text-sm prose min-w-0 w-full ${asideComponents[variant].innerStyle}`} data-component-part="callout-content">
          {gotInvalidVariant ? <p>
              <span className="font-bold">
                Invalid <code>type</code> passed!
              </span>
              <br />
              <span className="font-bold">Received: </span>
              {type}
              <br />
              <span className="font-bold">Expected one of: </span>
              {asideVariants.join(", ")}
            </p> : <>
              {title && <p className="font-bold">{title}</p>}
              {children}
            </>}
        </div>
      </div>
    </>;
};

<Aside type="caution" title="Handle validator keys like production secrets.">
  Keep recovery phrases offline, restrict shell access, and rehearse new procedures on testnet before touching wallets that hold real stake.
</Aside>

## Plan the environment

### Supported operating systems

MyTonCtrl is highly recommended to install on the following distributions:

* Ubuntu 22.04 LTS
* Ubuntu 24.04 LTS

### Hardware sizing by role

| Role               | CPU                                       | RAM    | Storage                                  | Network         | Traffic                              | Notes                                                            |
| ------------------ | ----------------------------------------- | ------ | ---------------------------------------- | --------------- | ------------------------------------ | ---------------------------------------------------------------- |
| 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 | ≥20 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 from the internet to the node and leave all outbound ports open. The port is assigned randomly during MyTonCtrl installation but can be set before via the `VALIDATOR_PORT` environment variable. To check the port after installation, refer to the `Node ports` field on `status` command output.

### Prepare the operator account

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

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
wget https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/scripts/install.sh
sudo bash install.sh
```

The interactive wizard walks through:

1. Selecting mainnet vs. testnet (or supplying a custom network config).
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](/ecosystem/nodes/cpp/mytonctrl/overview#install-mytonctrl) for installer flags and environment variables when you need unattended deployments.

### Verify services and synchronization

After installation, launch MyTonCtrl console via `mytonctrl` command and check the status:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
mytonctrl

MyTonCtrl> status
```

Wait until the node is synchronized: verify that `Local validator out of sync` and `Masterchain out of sync` both show ≤3 seconds.

### Baseline maintenance tasks

* `MyTonCtrl> create_backup` creates a snapshot of the current state (private keys and configs). It is highly recommended to make a backup of the node and store it in a secure space.
* `MyTonCtrl> update` updates MyTonCtrl CLI.
* `MyTonCtrl> upgrade` updates Node software.

### Operational discipline

For all nodes:

* Track network announcements via [`@tonstatus`](https://t.me/tonstatus) and enable notifications.
* Keep hardware aligned with the [minimum system requirements](#hardware-sizing-by-role); upgrade storage promptly if metrics show saturation.

For validator nodes:

* Monitor RAM, disk, CPU, and bandwidth dashboards. Contact [`@validators_help_bot`](https://t.me/validators_help_bot) if metrics or efficiency drop below target.
* Rerun `check_ef` or consult the [efficiency API](https://toncenter.com/api/qos/index.html#/) when diagnosing performance.

## Liteserver quickstart

### Activate liteserver services

If the node was not installed with `liteserver` mode enabled, activate it via `enable_mode liteserver`:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
MyTonCtrl> enable_mode liteserver
MyTonCtrl> status_modes
```

### Configure endpoints and proxies

Print the local liteserver configuration — its IP, port, and public key:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
MyTonCtrl> installer plsc
```

Create a new network config:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
MyTonCtrl> installer clcf
```

The command writes a `/usr/bin/ton/local.config.json` file with the full network configuration, ready for clients to connect to the local liteserver.

### Open the liteserver port

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

   ```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
   sudo apt install -y ufw
   sudo ufw allow ssh
   sudo ufw allow <port>
   sudo ufw enable
   sudo ufw status
   ```

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

## Archive liteserver quickstart

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

### Prepare storage with ZFS

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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](https://archival-dump.ton.org/)).

### Install and download archive data

[Run the installer](#install-mytonctrl), 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 out of sync` field to become green number before serving traffic.

### Troubleshooting imports

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

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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`](https://t.me/tonstatus) and [`@tonstatus_notifications`](https://t.me/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](/ecosystem/nodes/cpp/mytonctrl/alerting).
* Contact validator support via [`@validators_help_bot`](https://t.me/validators_help_bot); regular node operators can use [`@ton_node_help`](https://t.me/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](/ecosystem/nodes/cpp/mytonctrl/overview) for advanced automation.