Run a compute worker#

A compute worker rents a Linux machine's CPU to the network. It follows the Hub, runs the jobs the Hub assigns to it, and re-checks other workers' results. Its owner locks a bond on the Hub that can be slashed if the worker misbehaves.

This page uses the worker kit and worker-setup.sh, which do every step in one script. If you prefer to set each file up by hand, follow Manual setup instead; the result is the same.

Requirements#

Operating system. Linux on x86-64 with systemd. The testnet scripts are tested on Ubuntu 22.04+ and Debian 12+.

A dedicated machine. On the first public testnet, jobs run as plain processes without a container sandbox (isolation tier T1). Run the worker on a machine or VM that holds nothing else.

No GPU yet. The first public testnet runs CPU jobs only.

Other workers measure your node's bandwidth through that port. A node they cannot reach is measured as zero and gets no work.

How it fits together#

Two machines take part, and the owner key never touches the worker:

1. Make the owner key on your computer and get test-TOG.
2. Set up the worker with the kit.
3. Send the worker a little test-TOG.
4. Build the registration on the worker, sign and send it from your computer.
5. Start the worker and check that it is registered.

1. Owner key and test-TOG#

On your own computer, with the release's tog-cli:

mkdir -p ~/tog && cd ~/tog
(umask 077; head -c 32 /dev/urandom > owner.key)
tog-cli address owner.key            # your owner address, 40 hex digits

Keep an offline copy of owner.key. Whoever has it controls the bond.

Get test-TOG for that address from the faucet. One request gives 10 100 test-TOG: the 10 000 bond plus enough for fees.

2. Get the release and the worker kit#

Download the release binaries (tog-worker, tog-signer, tog-executor, tog-cli) and check their SHA-256 sums against the ones published with the release:

curl -fsSLO <RELEASE_URL>/tog-linux-x86_64.tar.gz
curl -fsSLO <RELEASE_URL>/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
tar xzf tog-linux-x86_64.tar.gz      # -> bin/

Download the worker kit for the network and unpack it. It holds the genesis, the calibration kernel set, the network table, network.env (network id and bootnodes), a client.toml for your own computer, and worker-setup.sh:

curl -fsSL <WORKER_KIT_URL> | tar xz  # -> worker-kit/

Copy worker-kit/client.toml and genesis.borsh to ~/tog on your own computer as well; tog-cli uses them to reach the Hub.

3. Set up the worker#

On the worker, as root:

cd worker-kit
./worker-setup.sh setup . --bin ../bin --public-ip <PUBLIC_IP>

This creates the tog and tog-signer users, makes the worker's keys inside the signer's directory, writes the configs and systemd units under /opt/tog, and starts the signer and the executor. Options:

Open the port:

ufw allow 30333/tcp

4. Fund the worker's own account#

The worker pays small amounts from its own account while it re-checks other jobs. Print its address on the worker, then send it 10 test-TOG from your computer:

/opt/tog/worker-setup.sh address                 # on the worker

tog-cli transfer --to <WORKER_ADDRESS> --amount 10 \
  --key owner.key --config client.toml --data-dir ~/tog/cli   # on your computer

5. Register#

Bond. A worker bonds 10 000 test-TOG on the public testnet. The registration takes it from the owner's free balance.

On your computer, read the owner's next nonce:

tog-cli account <OWNER_ADDRESS> --config client.toml --data-dir ~/tog/cli
# free    10090 TOG
# nonce   1

On the worker, build the unsigned registration. REGION is your country as two capital letters, such as DE:

/opt/tog/worker-setup.sh register <OWNER_ADDRESS> <NONCE> <REGION>

It describes the machine, runs the calibration kernels and writes /opt/tog/worker/register.borsh. The file holds no secret. Copy it to your computer and, within about 10 minutes (300 Hub blocks), sign and send it with the owner key:

tog-cli send register.borsh --key owner.key --config client.toml --data-dir ~/tog/cli
# RegisterWorker signed by <owner address>
# RegisterWorker included by height N

6. Start and check#

/opt/tog/worker-setup.sh start        # starts togd
/opt/tog/worker-setup.sh status       # each unit: active or not
journalctl -u tog-worker -f

togd logs genesis checked, light client started and then registered worker worker=<id> … cores=N. That last line means it found its registration on the Hub.

From your computer:

tog-cli worker <WORKER_ADDRESS> --config client.toml --data-dir ~/tog/cli

shows the worker's owner, status (Active), bond and measured bandwidth. Bandwidth is measured by other workers during the first sessions after you start. From another machine, check that the port is reachable:

nc -vz <PUBLIC_IP> 30333

If something does not work, see Troubleshooting.

Managing the worker#

All of these run on your own computer with the owner key.

After unbond-worker the worker takes no new jobs, and the bond returns after 14 days. Stop the three units then, and keep the keys and the signer journal.

Slashing#

The bond can be slashed when the worker's result for a job does not match the network's check, or when it claims a job and lets it expire without finishing it. A small fee is also paid from the bond each time another worker measures your node. A worker key that was ever slashed or jailed cannot be used again; a new registration needs fresh keys.