MyTonCtrl and TON use separate images. The official TON image supplies binaries
and Fift resources to a shared volume, with its init.sh entrypoint bypassed.
The MyTonCtrl image initializes and runs the node using those mounted artifacts.
It requires the artifacts to be mounted before startup. Node state, keys,
wallets, downloaded dumps and controller settings persist in a standard Docker
volume or an optional host data directory, mounted at /var/ton-work inside the container.
Use the Compose quick setup below, or follow
the examples without Docker Compose.
For an existing ton-docker-ctrl installation, follow
the migration wizard before starting this image.
Install Docker and Compose on Linux, plus skopeo and jq on the host for
image tag lookups (on Debian/Ubuntu: sudo apt-get install skopeo jq).
Prepare an empty deployment directory:
mkdir mytonctrl-docker
cd mytonctrl-docker
wget -O install.sh https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/docker/install.sh
bash install.shAlternatively, run the installer directly from an empty deployment directory:
wget -qO- https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/docker/install.sh | bashBy default, the installer downloads only .env and compose.yml into the
current directory. For a full archive liteserver, use
--archive instead. It refuses existing environment
or Compose files.
It prepares the setup without installing Docker or starting containers.
Retrieve the newest stable version tags published in GHCR. Each command prints
one full image reference to copy into .env as TON_IMAGE or MYTONCTRL_IMAGE:
skopeo list-tags docker://ghcr.io/ton-blockchain/ton |
jq -er --arg arch "$(uname -m | sed 's/^x86_64$/amd64/; s/^aarch64$/arm64/')" '
.Tags | map(select(test("^v[0-9]+(\\.[0-9]+)+(-[0-9]+)?(-" + $arch + ")?$")))
| sort_by([sub("-(amd64|arm64)$"; "") | ltrimstr("v") | splits("[.-]") | tonumber])
| last // error("No stable TON image tag found")
| "ghcr.io/ton-blockchain/ton:\(.)"'
skopeo list-tags docker://ghcr.io/ton-blockchain/mytonctrl |
jq -er '
.Tags | map(select(test("^v[0-9]+\\.[0-9]+\\.[0-9]+$")))
| sort_by(ltrimstr("v") | split(".") | map(tonumber))
| last // error("No stable MyTonCtrl image tag found")
| "ghcr.io/ton-blockchain/mytonctrl:\(.)"'The TON lookup includes tags for the host architecture (amd64 or arm64)
and tags without an architecture suffix. For example, the output may be
ghcr.io/ton-blockchain/ton:v2026.08-amd64 and
ghcr.io/ton-blockchain/mytonctrl:v1.0.2; the actual versions change as images are
published. These commands query published image tags, independently of GitHub
releases, and select the highest version rather than the most recently built tag.
See the TON package
and MyTonCtrl package.
Avoid using the latest tag for either image. It can move to another build
without an explicit version change in your configuration. Pin a version tag or
digest in .env, choose the data storage,
then start the containers and open the console.
The default --branch master selects master assets and
ghcr.io/ton-blockchain/mytonctrl:latest; replace that default in .env before
starting. For dev assets and the dev image, use:
wget -qO- https://raw.githubusercontent.com/ton-blockchain/mytonctrl/dev/docker/install.sh | bash -s -- --branch devUse --image IMAGE and --ton-image IMAGE to select published controller and
TON images, and --help to view setup options. The download commands require
these installer files on the selected branch; startup requires its image tag
to have been published by GitHub Actions.
The commands below use the downloaded compose.yml. Keep the same .env
volume names, optional host data directory and Compose project name throughout
the setup's lifetime. Compose uses host networking for Linux nodes. See
Docker setup for
standalone Docker commands, existing TON mounts and runtime details.
Both Compose files use the original Docker-managed named volume when
TON_WORK_HOST_DIR is empty or unset. Existing installations keep using the
same volume, including custom names selected by TON_WORK_VOLUME:
TON_WORK_VOLUME=mytonctrl-ton-work
TON_WORK_HOST_DIR=To place the node database, keys, wallets, controller state, controller logs and
dump cache on a separate disk, set TON_WORK_HOST_DIR to an absolute directory
on the Docker host. For example, after mounting your data disk at /mnt/ton:
findmnt --mountpoint /mnt/ton &&
sudo mkdir -p /mnt/ton/ton-work
df -h /mnt/ton/ton-workSet this in .env:
TON_WORK_HOST_DIR=/mnt/ton/ton-workCompose bind-mounts that directory at /var/ton-work; keep -W and
DUMP_CACHE_DIR as container paths. With a nonempty host path, TON_WORK_VOLUME
is unused and the small script and binary artifact volumes remain Docker-managed.
Compose's short mount syntax creates a missing host directory automatically,
so prepare it explicitly and verify the storage device before starting. See Docker's
bind mount options.
Mount the disk before starting the container, including after a host reboot.
Check that df shows the intended data filesystem. Directory existence does
not establish that the intended disk is mounted. Use a dedicated child directory
on that disk and keep the same path during image upgrades and recovery.
Changing the mount does not move existing data. With the old Compose setup, stop the controller first; this also stops its validator and background service:
docker compose stop mytonctrlPrepare an empty directory on the mounted data disk as above. Copy the old volume while the node is stopped, using its actual volume name and an already available controller image:
OLD_TON_WORK_VOLUME=mytonctrl-ton-work
TON_WORK_HOST_DIR=/mnt/ton/ton-work
MYTONCTRL_IMAGE=ghcr.io/ton-blockchain/mytonctrl:v1.0.2
docker volume inspect "$OLD_TON_WORK_VOLUME" >/dev/null &&
docker run --rm --pull never --network none --user 0 --entrypoint /bin/sh \
--mount "type=volume,src=$OLD_TON_WORK_VOLUME,dst=/old,readonly" \
--mount "type=bind,src=$TON_WORK_HOST_DIR,dst=/new" \
"$MYTONCTRL_IMAGE" -eu -c 'test -z "$(ls -A /new)"; cp -a /old/. /new/'This copies the database, keys, configuration and cached dumps with ownership
and permissions preserved. The destination must be empty. Install the updated
Compose file, set TON_WORK_HOST_DIR in .env to the destination, and
keep the other image, port and installer settings. Then start the setup:
docker compose up -d --no-build --pull never
docker compose exec mytonctrl mytonctrl --cmd statusKeep the old volume until you have verified the copied installation and backup. Do not run the old and new controllers against the same data concurrently.
Use the interactive wizard to migrate an existing
ton-blockchain/ton-docker-ctrl
installation on the same Linux host. Install Python 3.8 or newer and Docker
Compose, then run this from a terminal on that host:
wget -O migrate.sh https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/docker/migrate.sh
sudo bash migrate.shThe migration requires root privileges to preserve the donor's file ownership,
read private keys and inspect Docker storage for disk-space checks. Membership
in the docker group alone is insufficient. If already in a root shell, run
bash migrate.sh without sudo.
For the dev version, download from dev and run sudo bash migrate.sh --branch dev.
Use bash migrate.sh --help for options. Download the script before running it;
the wizard needs an interactive terminal for its questions and confirmations.
Before proceeding, take an independent backup or storage snapshot. The selected destination needs enough free space for a complete additional copy of the old node; archive databases can require many terabytes. It must be separate from all of the old installation's data directories. Keep the old container, image, volumes and deployment files until migration is verified.
The wizard checks the migration metadata directory, the selected TON work storage and Docker storage separately. Its budget includes the full data copy, legacy controller copy, identity staging, backup archive, controller import, temporary backup extraction, exported TON binaries and their running snapshot. It copies node data directly into the selected storage, without another staging copy of the database. If storage locations share a filesystem, it adds their requirements together. Estimates assume no compression or sparse-file savings and retain at least 10% or 1 GiB of extra space per storage area for metadata, logs and initial growth. Images are pulled while the old node is running; the wizard checks the remaining space again after pulling and immediately before downtime. It also rechecks after stopping the node, before backup creation and before startup. Insufficient space stops migration and preserves the original data. Keep monitoring free space as the migrated node syncs and its database grows.
The wizard identifies the old container and asks you to review its network, node mode, advertised IP, ports, retention settings and replacement images. It asks for the node storage type first, then requests confirmation before stopping the old node and before starting the replacement:
- Host directory (default): asks for the migration directory, suggesting
<current-directory>/migration, then asks for the TON work directory, suggesting<migration-directory>/ton-work. The wizard setsTON_WORK_HOST_DIRto that directory. Choose a path on your mounted data disk to keep node data off the root filesystem. - Docker volume: asks for a new volume name, suggesting
mytonctrl-ton-work. The wizard leavesTON_WORK_HOST_DIRempty and setsTON_WORK_VOLUMEto the selected name. It uses<current-directory>/migrationfor deployment files, backups and rollback instructions automatically, without asking for a migration directory. This uses Docker's volume storage for node data, so check which disk backs it.
Compose files are stored in <migration-directory>/deployment. If the automatic
migration directory already contains a previous migration, run the wizard from
another directory. If the suggested volume already exists, enter a new name.
The wizard rejects nonempty destinations, reused volumes and paths overlapping
the original data. The migration journal and final output record the selected
storage. The Compose project and controller container are both named mytonctrl.
The wizard stops if that container name or project already exists, preserving
the existing deployment. Artifact volumes still have independent names.
It downloads .env.example and generates <migration-directory>/deployment/.env.
If the destination already contains only deployment/.env, the wizard asks before
replacing it and saves the original as .env.before-migration. Declining cancels
migration before stopping the old node. Your current directory's .env is untouched.
It then:
- Disables the old container's automatic restart, then stops its controller and validator before taking the copy.
- Copies the entire TON work directory directly to the chosen host directory or Docker volume, and saves controller state, wallets, private keys, console settings and network configuration for import.
- Downloads this repository's
.env.exampleand Compose file, configures the new deployment, and imports the saved identities and controller settings. - Checks the backup, configuration and copied key files, then starts the new node after confirmation and prints status, console and rollback commands.
To open the migrated console, use the printed Compose command ending in
exec mytonctrl mytonctrl, which includes both configuration files. You can
also use the fixed container name directly:
sudo docker exec -it mytonctrl mytonctrlThe migration retains the blockchain database, archive history and cached
downloads; it does not request another dump download. The original data
stays intact and the old container remains stopped. Sources and build tools from
the old image are replaced by prebuilt binaries and Fift resources from the
separately selected TON_IMAGE.
Network selection is independent of node mode. Review the detected values; migration preserves the existing installation rather than converting its role or switching networks.
| Existing installation | Migration behavior |
|---|---|
| Mainnet | Keeps the saved mainnet configuration and uses -n mainnet. |
| Testnet | Keeps the saved testnet configuration and uses -n testnet. Select a compatible TON image; the old TON_BRANCH=testnet is not an image tag and does not carry over. |
| Validator | Keeps its validator wallet, ADNL identity, election/staking settings and node keys. Never run both installations with these keys at the same time. |
| Liteserver | Keeps its liteserver key, TCP port and retention settings so existing clients can continue using it. |
| Collator | Keeps existing collator ADNL keys, registrations, validator whitelist, collation options and delegated collators. Restores the saved mode without creating another collator. |
| Single-nominator | Keeps validator and single-nominator mode flags, wallets, pool files and staking settings. |
| Nominator-pool v2 | Keeps the v2 pool files, addresses and staking settings. |
| Nominator-pool v1 (deprecated) | Keeps the existing v1 pool and mode; migration does not convert it to v2. |
| Liquid-staking | Keeps controller lists, liquid pool address, wallets and loan settings. |
| Archive node, on either network | Keeps saved node and staking modes, complete history, permanent storage and retention settings before the first start. It does not bootstrap a new archive. |
Saved mode flags take precedence over stale installation environment settings.
An explicitly disabled validator remains disabled, including paused staking nodes.
For collators, the generated -m none -p ... restores the backup without fresh
collator setup; the restored controller still runs in its saved collator mode.
Ambiguous legacy mode schemas and conflicting validator/liteserver/collator flags
must be resolved using the old controller first. A separate collator.service
is an additional service and requires its own migration; the supported collator
mode runs inside validator-engine.
Use a TON image compatible with the existing database first; upgrade TON
separately after confirming migration. Check available releases in the
official TON package.
The new setup uses host networking. Allow the retained node UDP/QUIC and
liteserver TCP ports through the host firewall; keep the console port private.
Unusual layouts, multiple local console/liteserver endpoints, auxiliary services
or different-host/IP moves need review before migration; the wizard stops when
it cannot safely handle the detected configuration.
Bounded archive imports using --sync-shards-upto also require a separate review.
Use the commands printed by the wizard to inspect status, wallet and ADNL
addresses, network, ports and logs. For archive nodes, also verify historical
queries and retained archive files. Successful startup alone does not establish
that all required data and identities have been preserved.
On failure, the wizard stops the replacement and leaves the old node stopped. For rollback, stop the new deployment and confirm its validator has exited, then start the original container using its original data and image; follow the printed rollback script, which also restores the original restart policy. Never attach the old engine to the new database copy. Transactions broadcast after migration are not undone by rollback; reconcile validator elections, stake and wallet state before resuming the old controller.
Do not use docker compose down -v, prune volumes or delete the old data during
migration. The wizard never deletes the source installation automatically.
The new migration data volume is marked external in the migration override, so
Compose does not remove it with down -v;
a host directory also stays intact.
To deliberately remove migrated volume data, stop and remove the replacement
container first, retain an independent backup, then run
sudo docker volume rm <selected-TON_WORK_VOLUME>.
Use the same installation options as the host installer,
provided through MYTONCTRL_ARGS in the .env created by quick setup.
The default installation arguments install a mainnet validator using a prepared
dump. Replace the template's latest image tags with pinned versions, for example:
TON_IMAGE=ghcr.io/ton-blockchain/ton:v2026.08-amd64
MYTONCTRL_IMAGE=ghcr.io/ton-blockchain/mytonctrl:v1.0.2
TON_WORK_HOST_DIR=
MYTONCTRL_ARGS=-m validator -n mainnet -d
PUBLIC_IP=Leave PUBLIC_IP blank to autodetect the public IPv4 address, or set the address
the node should advertise. The entrypoint validates it before initialization.
Avoid latest; pin version tags or digests in TON_IMAGE and MYTONCTRL_IMAGE.
Run these commands on the host with skopeo and jq installed to retrieve the
newest stable published image references, then copy their output into .env:
skopeo list-tags docker://ghcr.io/ton-blockchain/ton |
jq -er --arg arch "$(uname -m | sed 's/^x86_64$/amd64/; s/^aarch64$/arm64/')" '
.Tags | map(select(test("^v[0-9]+(\\.[0-9]+)+(-[0-9]+)?(-" + $arch + ")?$")))
| sort_by([sub("-(amd64|arm64)$"; "") | ltrimstr("v") | splits("[.-]") | tonumber])
| last // error("No stable TON image tag found")
| "ghcr.io/ton-blockchain/ton:\(.)"'
skopeo list-tags docker://ghcr.io/ton-blockchain/mytonctrl |
jq -er '
.Tags | map(select(test("^v[0-9]+\\.[0-9]+\\.[0-9]+$")))
| sort_by(ltrimstr("v") | split(".") | map(tonumber))
| last // error("No stable MyTonCtrl image tag found")
| "ghcr.io/ton-blockchain/mytonctrl:\(.)"'These examples use v2026.08-amd64 for x86-64 hosts; the TON lookup selects
tags for the host architecture. .env requires literal image references;
shell commands and $(...) substitutions are not executed there.
Installation arguments apply when initializing an empty work volume. Existing
installations keep their configuration; use console commands for later changes.
Keep -u, -B, -S and -W fixed when reusing a work volume. The controller user
defaults to root; -u USER selects the controller service account. The TON node
runs as validator.
For example, to install a testnet liteserver with telemetry disabled:
MYTONCTRL_ARGS=-m liteserver -n testnet -tDocker supports these adaptations of the host arguments:
| Option | Docker behavior |
|---|---|
-c, --config |
Accepts a URL or an absolute path to a mounted network configuration file. For a custom network, use -n custom -c URL or -n custom -c /mounted/global.config.json. |
-e, --env-file |
Reads a mounted file of KEY=value data. Compose already loads .env; standalone Docker uses --env-file .env. |
-a/-r/-b, --author/--repo/--branch |
Select the checkout when building the controller image, then select MYTONCTRL_IMAGE. These source-selection arguments are unavailable at runtime. |
-g/-v, --node-repo/--node-version |
Select TON_IMAGE to choose prebuilt TON binaries. These source-selection arguments are unavailable at runtime. |
--print-env, --help |
Print parsed installation settings or help and exit. |
-s, --no-startup-checks |
Docker extension: add to MYTONCTRL_ARGS to skip console startup checks. Installation flags are kept separate from console arguments. |
Mount files referenced by -c, -p or -e into the controller using Compose
volumes or Docker's --mount option. --archive also requires a mounted
prebuilt tonutils-storage executable, which install.sh --archive prepares
automatically; follow archive node setup.
With Docker, Compose and jq installed on a Linux amd64 or arm64 host, run the
installer with --archive in a new deployment directory. Choose
pinned image references using the lookup commands; the following
TON image example is for amd64:
mkdir mytonctrl-archive
cd mytonctrl-archive
wget -O install.sh https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/docker/install.sh
bash install.sh --archive \
--ton-image ghcr.io/ton-blockchain/ton:v2026.08-amd64 \
--image ghcr.io/ton-blockchain/mytonctrl:v1.0.2The installer prepares .env and compose.yml, installs
the archive Compose configuration as
compose.override.yml, and queries GitHub for the latest tonutils-storage
release tag before downloading its executable for the host architecture. It sets
MYTONCTRL_ARGS=-m liteserver -n mainnet --archive and DUMP=false automatically.
Compose loads the override and exports the tool with the TON binaries.
Keep all four generated files in the deployment directory for future starts
and image upgrades.
Use empty node storage with room for the full history, download/import working
space and continued growth; this can require many terabytes. The default uses
a Docker volume. For a dedicated disk, set TON_WORK_HOST_DIR in .env as
described in storage setup. For testnet,
change -n mainnet to -n testnet in MYTONCTRL_ARGS and select a compatible
pinned TON image. Then start the archive installation:
docker compose pull
docker compose up -d --no-build --pull never
docker compose logs -f mytonctrlThe archive mode downloads history from block 1, enables --permanent-celldb,
and sets archive and state retention to 1000000000 seconds. Leave ADD_SHARD
unset to synchronize all shards. Initial download, import and synchronization
can take a long time. In another terminal, check progress and validator settings:
docker compose exec mytonctrl mytonctrl --cmd status
docker compose exec mytonctrl mytonctrl --cmd 'installer status'installer status should show the permanent cell database flag and retention
values described above. After synchronization, query an early masterchain block
through the local liteserver to check historical access:
docker compose exec mytonctrl bash -ic \
'_mytonctrl_lite_client -c "byseqno -1 8000000000000000 1"'Verify current block progress as well. These installation settings apply to empty
storage; changing .env does not rebuild missing history in an existing node.
To retain an existing archive installation, use
migration.
After editing .env, pull the selected images and start the setup from
the deployment directory:
docker compose pull
docker compose up -d --no-build --pull never
docker compose logs -f mytonctrlThe one-shot ton-exporter service uses the same controller image to copy its
packaged exporter script into a shared script volume. ton-binaries then runs
that script in the official TON image and exits after exporting artifacts.
These three services use two images. The mytonctrl service keeps the node and
controller running. Allow the configured validator and QUIC UDP ports and
liteserver TCP port through the host firewall; keep the validator console port
private.
Open the console or run a command using the same console arguments as the host utility:
docker compose exec mytonctrl mytonctrl
docker compose exec mytonctrl mytonctrl --cmd "get modes"In Docker mode, status displays image references instead of Git commits:
Version mytonctrl: ghcr.io/ton-blockchain/mytonctrl:v1.0.2
Version validator: ghcr.io/ton-blockchain/ton:v2026.08-amd64
The controller reference is embedded when building the image. The TON reference comes from the exported release copied into the running container; exporting a newer release leaves this display unchanged until the controller restarts. Mounted binaries without exported image metadata display an unknown image.
Console defaults can also be set in .env using MYTONCTRL_CONFIG,
MYTONCTRL_WALLETS and MYTONCTRL_CMD. Use -s in MYTONCTRL_ARGS for the startup
check default. Explicit console arguments take precedence for options with values.
The publishing workflows use dev for commits to dev, latest for commits to
master, and a required tag input for manual builds.
Open an interactive Bash shell to use the image's local node shortcuts:
docker compose exec mytonctrl bash
# Without Compose: docker exec -it mytonctrl bash
getstats
last
config34
syncThese are Bash commands; enter them outside the MyTonCtrl> prompt.
| Alias | Query |
|---|---|
config32, config34, config36 |
Local network configuration parameters 32, 34 and 36. |
elid |
Elector's active election ID. |
participants |
Elector's participant list. |
getstats |
Local validator console statistics. |
last |
Latest masterchain block known to the local liteserver. |
sync |
Age of that block in seconds. |
egrep |
grep -E with automatic color. |
The aliases use the container's active TON binaries and keys. They read the
console and liteserver ports from db/config.json with jq on every invocation,
so they follow ports configured in .env or retained during migration. Custom
-W work directories are supported. They require the corresponding node
endpoints to have been initialized; local results can lag while syncing.
last and sync override the usual Linux commands in Bash; use command last
or command sync to call those tools. Aliases arrive with the updated controller
image and require no .env or migration script changes.
The controller image includes uv, Python 3.14 and TON's Python benchmark
framework with its generated bindings. The benchmark uses the binaries and
Fift resources supplied by the separate TON image; it does not download a
repository, install dependencies or compile TON when invoked.
View the benchmark options without stopping the node:
docker compose exec mytonctrl mytonctrl --cmd "benchmark -- --help"The benchmark starts a temporary local TON network and measures its workload.
After node initialization completes, stop the live controller and validator
services before running it. Run these commands in your host shell, outside the
MyTonCtrl> prompt (type exit to leave the console):
docker compose exec mytonctrl sudo systemctl stop mytoncore
docker compose exec mytonctrl sudo systemctl stop validator
docker compose exec mytonctrl mytonctrl --cmd "benchmark --nodes 2 --duration 60"Stopping these services keeps the container running. Pass workload options
such as --tps, --shards, --spammers or --sync-test to benchmark. Use
--tmp-dir /mounted/path to select benchmark storage; its default parent is
/var/ton-work/tmp. Each run uses a separate temporary directory and removes
its test network afterward. The container manages --build-dir, --source-dir
and --work-dir to keep benchmark cleanup separate from the live node's data.
Its database, keys, wallet and dump cache are retained.
Restart the live services after the benchmark, including if it failed or was interrupted:
docker compose exec mytonctrl sudo systemctl start validator
docker compose exec mytonctrl sudo systemctl start mytoncoreFor development, use the repository root's compose.yaml, which supports
building the local checkout. The quick setup's compose.yml uses published
images only. On the first setup in a checkout, create its .env:
cp .env.example .envLeave TON_WORK_HOST_DIR blank for the named volume, or select a host directory
as described in storage setup. Keep
MYTONCTRL_IMAGE=mytonctrl:local or choose another local image tag, then run
these commands from that checkout's root:
docker compose -f compose.yaml pull ton-binaries
docker compose -f compose.yaml build mytonctrl
docker compose -f compose.yaml up -d --no-build --pull neverCompose embeds MYTONCTRL_IMAGE as the controller image reference. For a direct
docker build, pass --build-arg MYTONCTRL_IMAGE_REF=mytonctrl:local alongside
-t mytonctrl:local, replacing both values with your chosen image name and tag.
Stop the node and controller while keeping their containers and data:
docker compose stop mytonctrlResume the stopped container:
docker compose restart --no-deps mytonctrlTo remove the service containers while keeping the persistent volumes, use:
docker compose downStart them again with docker compose up -d --no-build --pull never.
Retrieve the newest stable TON image reference for the host architecture using
skopeo and jq on the host:
skopeo list-tags docker://ghcr.io/ton-blockchain/ton |
jq -er --arg arch "$(uname -m | sed 's/^x86_64$/amd64/; s/^aarch64$/arm64/')" '
.Tags | map(select(test("^v[0-9]+(\\.[0-9]+)+(-[0-9]+)?(-" + $arch + ")?$")))
| sort_by([sub("-(amd64|arm64)$"; "") | ltrimstr("v") | splits("[.-]") | tonumber])
| last // error("No stable TON image tag found")
| "ghcr.io/ton-blockchain/ton:\(.)"'Review compatibility with your network and database, then copy the full output
into TON_IMAGE in .env, or pin a specific compatible version or digest.
Avoid latest. Pull the selected image and export its binaries:
docker compose pull ton-binaries
docker compose run --rm ton-binariesThe running controller keeps using its private copy of the previous TON binaries and resources. Adopt the newly exported TON release when ready:
docker compose restart --no-deps mytonctrlEvery controller start, restart or recreation selects the currently exported
TON release. Updating TON_IMAGE in .env alone does not export new binaries.
For a published image, retrieve the newest stable MyTonCtrl image reference using
skopeo and jq on the host:
skopeo list-tags docker://ghcr.io/ton-blockchain/mytonctrl |
jq -er '
.Tags | map(select(test("^v[0-9]+\\.[0-9]+\\.[0-9]+$")))
| sort_by(ltrimstr("v") | split(".") | map(tonumber))
| last // error("No stable MyTonCtrl image tag found")
| "ghcr.io/ton-blockchain/mytonctrl:\(.)"'Copy the full output into MYTONCTRL_IMAGE in .env, or pin another version
or digest. Avoid latest. Pull the image and recreate the controller:
docker compose pull mytonctrl
docker compose run --rm --no-deps ton-exporter
docker compose up -d --no-deps --no-build --pull never mytonctrlFor a local development setup, update
the checkout and keep its local MYTONCTRL_IMAGE tag in .env. From that same
checkout's root, build and recreate using its compose.yaml:
docker compose -f compose.yaml build mytonctrl
docker compose -f compose.yaml run --rm --no-deps ton-exporter
docker compose -f compose.yaml up -d --no-deps --no-build --pull never mytonctrlBoth methods refresh the packaged exporter script, preserve the work volume and
reuse node keys, wallets, settings and an unfinished dump download. An upgrade
during initialization resumes the original installation using its saved settings;
it does not select a newer dump or discard the existing archive.
Recreation also adopts the currently exported TON release. Use these image
updates for container deployments; the console's update and upgrade commands
are disabled and display instructions to update the corresponding Docker image.
A container restart alone does not replace its controller image or reload .env
changes.
These examples use Docker directly on Linux, with the same two images and persistent volumes as the Compose setup. Run them from your deployment directory. Keep the image and volume variables available in your shell; in a new terminal, set them again to the values used for this installation.
Prepare an empty directory and download the environment template:
mkdir mytonctrl-docker &&
cd mytonctrl-docker &&
wget -O .env https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/.env.exampleEdit .env with the same installation arguments
and PUBLIC_IP settings described above. For a published controller, set
MYTONCTRL_IMAGE to a pinned version from the lookup commands above in that
file. Then set the following shell variables to match your chosen image
references and volume names in .env:
TON_IMAGE=ghcr.io/ton-blockchain/ton:v2026.08-amd64
MYTONCTRL_IMAGE=ghcr.io/ton-blockchain/mytonctrl:v1.0.2
TON_SCRIPTS_VOLUME=mytonctrl-ton-scripts
TON_ARTIFACTS_VOLUME=mytonctrl-ton-artifacts
TON_WORK_VOLUME=mytonctrl-ton-work
TON_WORK_HOST_DIR=
docker pull "$MYTONCTRL_IMAGE"
docker pull "$TON_IMAGE"
docker volume create "$TON_SCRIPTS_VOLUME"
docker volume create "$TON_ARTIFACTS_VOLUME"
if [ -n "$TON_WORK_HOST_DIR" ]; then
TON_WORK_MOUNT="type=bind,src=$TON_WORK_HOST_DIR,dst=/var/ton-work"
else
docker volume create "$TON_WORK_VOLUME"
TON_WORK_MOUNT="type=volume,src=$TON_WORK_VOLUME,dst=/var/ton-work"
fiThe default uses a named volume. For a host directory, set TON_WORK_HOST_DIR
in both your shell and .env, prepare it on your mounted disk as described in
storage setup, then run the mount-selection
block above. Keep TON_WORK_MOUNT available for startup and image upgrades.
Docker's --env-file
passes settings to the container; it does not choose the image, volume names or
host path in these shell commands. Keep MYTONCTRL_ARGS unquoted as in .env.example,
and use literal values rather than ${VARIABLE} substitutions in .env.
Copy the exporter bundled in the controller image into the script volume:
docker run --rm --pull never --network none --entrypoint /bin/sh \
--mount "type=volume,src=$TON_SCRIPTS_VOLUME,dst=/scripts" \
"$MYTONCTRL_IMAGE" -eu -c '
staged_script=$(mktemp /scripts/.export-ton.sh.XXXXXX)
trap "rm -f \"$staged_script\"" EXIT
cp /usr/local/lib/mytonctrl/export-ton.sh "$staged_script"
chmod 444 "$staged_script"
mv -f "$staged_script" /scripts/export-ton.sh
'Export TON's binaries and Fift resources using the official image with its
init.sh entrypoint replaced. This helper exits after publishing the artifacts:
docker run --rm --pull never --network none --entrypoint /bin/sh \
--env "TON_IMAGE_REF=$TON_IMAGE" \
--mount "type=volume,src=$TON_ARTIFACTS_VOLUME,dst=/ton-artifacts" \
--mount "type=volume,src=$TON_SCRIPTS_VOLUME,dst=/scripts,readonly" \
"$TON_IMAGE" /scripts/export-ton.shStart the controller with the artifact volume read-only and your selected data
storage mounted read-write. These examples use the default container work
path /var/ton-work; if you select a different path with -W, change the work
mount destination to that container path.
docker run -d --name mytonctrl --pull never --network host \
--restart unless-stopped --stop-timeout 75 --env-file .env \
--mount "type=volume,src=$TON_ARTIFACTS_VOLUME,dst=/ton-artifacts,readonly" \
--mount "$TON_WORK_MOUNT" \
"$MYTONCTRL_IMAGE"
docker logs -f mytonctrlOpen the console in another terminal, or run a single command:
docker exec -it mytonctrl mytonctrl
docker exec mytonctrl mytonctrl --cmd statusStop the container while retaining its data, then start it again when needed:
docker stop mytonctrl
docker start mytonctrlStopping uses the 75-second grace period configured above. Starting or restarting
retains the container's image and environment. Recreate it using the controller
upgrade commands below to load a changed image or .env file.
Set TON_IMAGE to the desired tag or digest in .env and in your shell, then
pull and export it. Check the available tags in the
official TON container package
and replace the example release below with your selected tag:
TON_IMAGE=ghcr.io/ton-blockchain/ton:v2026.08-amd64
docker pull "$TON_IMAGE"
docker run --rm --pull never --network none --entrypoint /bin/sh \
--env "TON_IMAGE_REF=$TON_IMAGE" \
--mount "type=volume,src=$TON_ARTIFACTS_VOLUME,dst=/ton-artifacts" \
--mount "type=volume,src=$TON_SCRIPTS_VOLUME,dst=/scripts,readonly" \
"$TON_IMAGE" /scripts/export-ton.shThe running controller continues using its existing TON binaries. Adopt the newly exported release when ready:
docker restart mytonctrlThis keeps the work volume, keys, wallets and downloaded dump data.
Set MYTONCTRL_IMAGE to the desired tag or digest in .env and in your shell.
Pull it and refresh the packaged exporter for future TON exports:
MYTONCTRL_IMAGE=ghcr.io/ton-blockchain/mytonctrl:v1.0.2
docker pull "$MYTONCTRL_IMAGE"
docker run --rm --pull never --network none --entrypoint /bin/sh \
--mount "type=volume,src=$TON_SCRIPTS_VOLUME,dst=/scripts" \
"$MYTONCTRL_IMAGE" -eu -c '
staged_script=$(mktemp /scripts/.export-ton.sh.XXXXXX)
trap "rm -f \"$staged_script\"" EXIT
cp /usr/local/lib/mytonctrl/export-ton.sh "$staged_script"
chmod 444 "$staged_script"
mv -f "$staged_script" /scripts/export-ton.sh
'
docker stop mytonctrl
docker rm mytonctrl
docker run -d --name mytonctrl --pull never --network host \
--restart unless-stopped --stop-timeout 75 --env-file .env \
--mount "type=volume,src=$TON_ARTIFACTS_VOLUME,dst=/ton-artifacts,readonly" \
--mount "$TON_WORK_MOUNT" \
"$MYTONCTRL_IMAGE"Keep the same volume names, optional host data directory and installation paths. The recreated container reuses the node database, keys, wallets and settings; interrupted initialization resumes with its existing dump cache. It also adopts the currently exported TON release. There is no need to export TON again for a controller-only update.
Remove this setup's container and its artifact/script volumes:
In named-volume mode, these commands also delete node keys, wallets, blockchain data and dumps. Back them up first. With a host path, its directory remains intact.
docker stop mytonctrl
docker rm mytonctrl
docker volume rm "$TON_ARTIFACTS_VOLUME" "$TON_SCRIPTS_VOLUME"
if [ -z "$TON_WORK_HOST_DIR" ]; then
docker volume rm "$TON_WORK_VOLUME"
fiThe helper containers were removed automatically after exporting. For complete host data removal, follow data cleanup. Optionally, remove the downloaded images when other containers no longer use them and delete the local environment file:
docker image rm "$MYTONCTRL_IMAGE" "$TON_IMAGE"
rm -f .envUse a controller image containing the recovery fixes, then follow the image
upgrade commands above with the same TON_WORK_VOLUME or TON_WORK_HOST_DIR
and installation paths.
The container resumes initialization automatically, including installations
left by an older image with an empty .initializing marker. Keep the existing
work storage and marker. In named-volume mode, docker compose down -v deletes
the downloaded dump and node data. With a host directory, that command removes
only the script/artifact volumes and retains node data. Use docker compose down
without -v to retain all storage in either mode.
The default DUMP_CACHE_DIR=/var/ton-work/dump-cache is inside the persistent
work volume. Mount persistent storage there if you choose a cache outside the
work volume. Partial downloads resume the same pinned archive. Complete
archives are verified and reused locally; older caches without metadata look
up the existing archive's dated metadata rather than downloading today's dump.
If that metadata is unavailable, startup reports the problem and preserves the
archive. An interrupted extraction restarts from the cached archive while
preserving node keys and configuration. The archive is removed only after the
whole installation completes, reclaiming its disk space.
Follow progress with docker compose logs -f mytonctrl. In another terminal,
inspect initialization, dump, service and local resource status:
docker compose exec mytonctrl mytonctrl --cmd statusOpening docker compose exec mytonctrl mytonctrl also shows overall status.
Unavailable node/chain fields display n/a while initialization is in progress;
the controller's background tasks start after its client settings are ready.
Error summaries appear on stdout, while full tracebacks remain in the persistent
controller log at /var/ton-work/controller/mytoncore/mytoncore.log.
An extracted dump means the downloaded archive has been unpacked into the work
volume. The validator may still need to import archive blocks and catch up with
the network. It must start and accept console commands before installation can finish.
During this stage, console status shows local data and service state without
running validator-dependent startup checks. A service shown as starting or
running (initializing) has not yet completed initialization.
The validator writes directly to the container's stdout/stderr, available through Docker logs. If it keeps restarting, inspect recent messages and service exit status:
docker compose logs --since 30m --tail 300 mytonctrl
docker compose exec mytonctrl systemctl show validator --property=SubState,ExecMainStatusInstaller failures and their full tracebacks are saved in
/var/ton-work/controller/mytoninstaller.log. Keep the data volumes while
diagnosing a failed start; retries reuse the extracted database.
Initialization status: ready means installation and client configuration are
complete. Blockchain synchronization continues afterward. Docker status shows
masterchain lag in seconds and shardchain lag in blocks separately; compare
both over time rather than treating the shard block gap as elapsed seconds.
Inspect the engine's messages in Docker logs and process state when it restarts:
docker compose logs --since 30m --tail 300 mytonctrl
docker compose exec mytonctrl systemctl show validator --property=SubState,MainPID,ExecMainStatusFilter recent diagnostics for database or worker failures:
docker compose logs --since 30m mytonctrl |
grep -E 'FATAL_ERROR|Unexpected Status|STATUS:|import-db-slice|apply-block|celldb'Compare the timestamps inside the messages. Existing /var/ton-work/log and
log.threadN.log files may contain historical entries from older images; current
validator messages go to Docker logs. A running validator process can also be a
replacement started by Supervisor after a crash; check block progress as well as
process state.
For raw progress counters, run this twice about a minute apart. It reads the saved console settings, including the actual configured port:
docker compose exec mytonctrl /opt/mytonctrl/venv/bin/python -c '
import json
import subprocess
from pathlib import Path
config = json.loads(Path("/var/ton-work/controller/mytoncore/mytoncore.db").read_text())["validatorConsole"]
subprocess.run([
config["appPath"], "-k", config["privKeyPath"], "-p", config["pubKeyPath"],
"-a", config["addr"], "-v", "0", "--cmd", "getstats",
], check=True, timeout=15)
'Compare masterchainblock, masterchainblocktime and
shardclientmasterchainseqno; increasing block numbers establish progress.
A changing start_time indicates validator restarts. State serialization
counters describe a separate background task.
Check the saved network addresses and current I/O activity:
docker compose exec mytonctrl jq '{addrs,fullnode,fullnodeslaves}' /var/ton-work/db/config.json
docker compose exec mytonctrl iostat -xz 1 5
docker compose exec mytonctrl vmstat 1 5Verify the advertised IP and ports in this saved configuration, since changing
installation options in .env does not rewrite an initialized node. High disk
activity can delay catch-up; inspect I/O latency and queue sizes. Allocated swap
alone does not show active swapping; check vmstat's si and so columns.
During initial sync, controller queries can use public liteservers. A public server's latest block or zerostate banner describes that query, rather than the local node's progress. Failed queries now report their exit code instead of treating those banners as valid configuration data. Custom overlay messages also need to be evaluated separately from the validator engine's own failure.
An Error : 652 : timeout from import-db-slice.cpp with an actor named
!apply(-1,...) means applying an imported masterchain block failed. In
TON commit 3d478cb,
the application request has a 600-second deadline, and a failed result triggers
a fatal assertion. Supervisor then restarts the engine. This deadline covers
block application, including database and state operations; the archive download
has a separate timeout. MyTonCtrl cannot increase this deadline through an
installer argument.
High disk latency or competing database workloads can prevent timely block
application. TON's troubleshooting guide
also identifies storage performance as a cause of archive import timeouts.
Use iostat to inspect latency and queues, rather than relying on disk utilization
alone. If another full node such as gton shares the storage, temporarily pause
it using its own service manager and compare TON's block progress and disk
latency. Change one setting at a time so the comparison is meaningful.
For a machine running many validator threads, a lower thread count is another reversible trial. Record the existing value, then try 32 threads using the existing installer command:
docker compose exec mytonctrl mytonctrl --cmd 'installer status'
docker compose exec mytonctrl mytonctrl --cmd 'installer set_node_argument --threads 32'
docker compose exec mytonctrl mytonctrl --cmd 'installer status'
docker compose exec mytonctrl systemctl show validator --property=SubState,MainPID,ExecMainStatusThis changes the persistent validator service and restarts the validator with
the same database and keys. Compare raw block counters and I/O readings over
at least 15 minutes, including the former ten-minute crash interval. If it does
not help, restore the recorded thread count with the same command. For example,
use installer set_node_argument --threads 127 if the previous value was 127.
Changing CUSTOM_PARAMETERS in .env applies only during first installation;
use the installer command to adjust an existing node.
For a short diagnostic window, enable detailed engine logs, collect messages
with docker compose logs, then restore normal verbosity to limit log traffic:
docker compose exec mytonctrl mytonctrl --cmd 'installer set_node_argument --verbosity 3'
# After collecting the engine's logs and progress counters:
docker compose exec mytonctrl mytonctrl --cmd 'installer set_node_argument --verbosity 1'Both commands restart the validator. Preserve the data volume when diagnosing
timeouts. The message Too much metadata in the database, do only partial check
means a bounded metadata check
reached its inspection limit; that message alone does not establish database
corruption or require a new dump.
For a setup without Compose, replace docker compose exec mytonctrl with
docker exec mytonctrl, and use docker logs --since 30m --tail 300 mytonctrl.
Retain the work volume while diagnosing synchronization or engine failures.
Remove this Compose setup's containers, named volumes and service images:
When TON_WORK_HOST_DIR is blank, this deletes the node data volume, including
keys, wallets, blockchain data, controller settings and downloaded dumps. Save a
backup outside these volumes first. It also deletes the TON artifacts and
packaged script volume. When TON_WORK_HOST_DIR is set, that external directory
remains intact, including all node data.
docker compose down --volumes --rmi all --remove-orphansThe cleanup applies to the services and named volumes in this Compose file; see Compose down reference for flag details. To also remove the files downloaded by quick setup after teardown, run:
rm -f .env compose.yml compose.override.yml tonutils-storage install.shTo erase the node data too, first stop and remove the containers, save any required backup elsewhere, and verify the exact directory you selected. For the example path in this guide, permanently delete it with:
sudo rm -rf -- /mnt/ton/ton-workReplace that example with your actual TON_WORK_HOST_DIR when it differs.