How to use the storage daemon

The storage-daemon is the official implementation of TON Storage, distributed as part of the TON software suite. The complete flag and command inventory lives in the TON Storage reference.

Prerequisites

• storage-daemon and storage-daemon-cli binaries from the TON releases page (v2024.01 or newer)
• global.config.json for TON Mainnet or TON Testnet : download from the ton-blockchain/ton repository for mainnet
• Sufficient disk space for the database directory and stored bags
• One open UDP port for ADNL peer connections (default example: 3333)

Start the daemon

storage-daemon \
  -C global.config.json \
  -I <PUBLIC_IP>:3333 \
  -p 5555 \
  -D storage-db \
  -v 3

Flag explanations (source: storage/storage-daemon/storage-daemon.cpp):

• -C / --global-config : path to the TON global config file. Required.
• -I / --ip : public IP address and UDP port for ADNL peer connections, in <IP>:<PORT> form. Use :<PORT> (omitting the IP) to start in client-only mode bound to 127.0.0.1.
• -p / --control-port : TCP port for storage-daemon-cli connections. Choose any free port.
• -D / --db : path to the database directory. Created on first launch. Keys generated on first launch are stored in <DB>/cli-keys/.
• -v / --verbosity : verbosity level 0–10. Level 3 shows informational messages.
• -P / --storage-provider : enable the storage provider subsystem. Required when running a paid provider node.
• -d / --daemonize : detach from the terminal (sets SIGHUP handler).
• -l / --logname : write logs to a file instead of stdout.

Key file security

On first launch the daemon generates a wallet key used for provider payments and stores it in <DB>/cli-keys/. Loss or theft of this key means loss of any funds held by the provider contract.

• Set file permissions to 600 on the cli-keys/ directory: chmod -R 600 <DB>/cli-keys/
• Back up the directory before deploying to mainnet.
• Test the full setup on TON Testnet before running on mainnet.

Connect with storage-daemon-cli

After the daemon starts it writes a server public key to <DB>/cli-keys/server.pub and a client private key to <DB>/cli-keys/client. Use these to authenticate the CLI:

storage-daemon-cli \
  -I 127.0.0.1:5555 \
  -k storage-db/cli-keys/client \
  -p storage-db/cli-keys/server.pub

CLI flag explanations (source: storage/storage-daemon/storage-daemon-cli.cpp):

• -I / --ip : IP and control port of the running daemon.
• -k / --key : path to the client private key file.
• -p / --pub : path to the server public key file.
• -c / --cmd : run a single command and exit (batch mode).

Manage bags

Typical lifecycle commands, grouped by intent. Every command, flag, and argument is documented in the TON Storage reference CLI commands section.

Create a bag from a local file or directory:

create <PATH> -d "<DESCRIPTION>"

Add an existing bag by its BagID and download to <DIR>:

add-by-hash <BAG_ID> -d <DIR>

List all bags held by the daemon:

list

To download only specific files from a bag, use --partial when adding:

add-by-hash <BAG_ID> -d <DIR> --partial file1.txt file2.txt

Files not listed are assigned priority 0 and are not downloaded.

Verify

Run list in the CLI. An empty daemon returns an empty table with no error:

storage-daemon-cli -I 127.0.0.1:5555 -k storage-db/cli-keys/client -p storage-db/cli-keys/server.pub -c "list"

A successful connection returns the bag list (empty on a fresh install). Any authentication error indicates a mismatch between key files and the running daemon instance.

Troubleshoot

• Failed to load global config: the path passed to -C is wrong or the file is malformed. Verify the path and re-download the config file.
• Control port unreachable: confirm the daemon started without error and that the port in -p (daemon) matches -I port (CLI). Check for port conflicts with ss -lntp | grep 5555.
• Not authorized: the client key or server public key does not match the running daemon. Use the key files from the same <DB>/cli-keys/ directory that the daemon generated on startup.
• ADNL connectivity issues: confirm the UDP port in -I is reachable from external peers. Routers and firewalls must forward the UDP port.