SubVortex Auto Upgrader

---

Effortless Updates for Your Miner & Validator

Github SubVortex • Discord Bittensor • Discord SubVortex

---

Testnet: 92 • Mainnet: 7

---

• Introduction
• Prerequisites
• Release Channels
• Quick Setup
• Quick Start
• How It Works
• Monitoring & Logs
• Quick Upgrade
• Quick Restart
• Quick Stop
• Quick Clean
• Installation
  • Auto Upgrader
  • Miner
  • Validator
  • Other
• Tools
  • Wandb
• Good to Know
• Troubleshooting
• Support Scope
• License

🚀 Introduction

Keeping your miner and validator up to date shouldn't be a chore.

The SubVortex Auto Upgrader automates upgrades for your SubVortex miner and validator. It ensures that your components are always running the latest version—without manual intervention.

Whether you're managing a single node or an entire fleet, the Auto Upgrader provides a reliable and flexible solution. Choose to run it as a standalone process, a system service, or in a Docker container.

Simple to set up. Easy to monitor. Zero stress upgrades.

⚠️ Note: The Auto Upgrader does not manage or upgrade Subtensor nodes themselves. It is the responsibility of each miner to install, upgrade, and maintain their own Subtensor node to ensure proper functionality and synchronization with the network.

⚙️ Prerequisites

⚠️ Architecture Notice
The SubVortex Auto Upgrader currently supports only x86_64 (amd64) servers.
arm64 support is not yet available but is a work in progress.
We’re actively collaborating with OTF to bring full compatibility as soon as possible.

Before you begin, make sure you clone the Auto Upgrader repository:

git clone https://github.com/eclipsevortex/SubVortex.AutoUpgrader.git

Then, configure your environment:

1. Update the main Auto Upgrader .env file at:

   subvortex/auto_upgrader/.env
   

Here's a breakdown of the key variables:

• SUBVORTEX_GITHUB_TOKEN: GitHub token used to pull Docker images and download release assets from the GitHub registry. It is highly recommended to create a Personal Access Token (PAT) from your GitHub account for this purpose. See Personal Access Token for instructions.

• SUBVORTEX_PRERELEASE_ENABLED:
  Set to true if you want the Auto Upgrader to apply both releases and pre-releases. Default is false.

• SUBVORTEX_EXECUTION_METHOD:
  Defines how the neuron and its components will be installed by the Auto Upgrader. Options are process, service, or container. Default is service.

• SUBVORTEX_PRERELEASE_TYPE:
  Specifies a single prerelease identifier you want to be notified about. Options are alpha (use ONLY in DEVNET) or rc (use ONLY in TESTNET). Remove this variable to receive notifications from latest (use in MAINNET) prerelease types. Default is an empty string, which disables prerelease notifications.

• SUBVORTEX_EXECUTION_ROLE:
  Specifies the type of neuron running on this machine. Options are miner and validator. Default value is miner. The Auto Upgrader uses this to decide how the machine should upgrade.

• SUBVORTEX_WORKING_DIRECTORY:
  Working directory used by the Auto Upgrader. Recommended default: /var/tmp/subvortex

• SUBVORTEX_CHECK_INTERVAL:
  Interval in seconds to check if new releases are available. Default 30 seconds.

• SUBVORTEX_REDIS_HOST: Host of the redis instance. Provide it ONLY if you are a validator. Default localhost

• SUBVORTEX_REDIS_PORT: Port of the redis instance. Provide it ONLY if you are a validator. Default 6379.

• SUBVORTEX_REDIS_INDEX: Index of the redis database. Provide it ONLY if you are a validator. Default 0

• SUBVORTEX_REDIS_PASSWORD: Password of the redis database. Provide it ONLY if you are a validator.

2. Update the environment variables inside the subvortex/auto_upgrader/environment folder.

   • For miners, edit files matching env.subvortex.miner.*
   • For validators, edit files matching env.subvortex.validator.*

3. Update the templates inside the subvortex/auto_upgrader/template folder. Recommended to keep as it is.

🧪 Release Channels

Release Type	Description	Recommended Usage
alpha	Experimental, unstable builds	DEVNET only
rc	Release Candidates (pre-launch)	TESTNET only
(empty)	Latest stable public release	MAINNET only

🚀 Quick Setup

⚠️ Note: This step is usually not required. The Auto Upgrader automatically handles setup for you. Use this only if you encounter issues or need to manually prepare a specific version.

To setup the Auto Upgrader in a quick way, you can run

./scripts/quick_setup.sh --neuron validator --release v3.0.1

It will download and unzip the neuron's assets of the SubVortex for the requested version.

Use -h to see the options

🚀 Quick Start

To install the Auto Upgrader in a quick way, you can run

./scripts/quick_start.sh --execution <EXECUTION_METHOD>

It will install and start the Auto Upgrader using the EXECUTION_METHOD, which defaults to service.

Use -h to see the options

🔧 How It Works

When setting up the Auto Upgrader, you can choose from three execution modes: process, service, or container. The default mode is service

🧩 Process & Service Modes

In these modes, the Auto Upgrader checks GitHub every SUBVORTEX_CHECK_INTERVAL seconds for new releases. When a new version is available, it:

1. Downloads and unzips the archive for your neuron type (SUBVORTEX_EXECUTION_ROLE) into SUBVORTEX_WORKING_DIRECTORY
2. Install the new version
3. Updates the symlink to point to the new version
4. Cleans up the previous version

➡️ The execution directory for SubVortex will now be located under $HOME/subvortex, with each version in its own subdirectory and a symlink pointing to the current version. You no longer need to clone the SubVortex repository manually — and can safely remove any old local copies you previously cloned.

🐳 Docker Mode

Here, the Auto Upgrader also checks GitHub every SUBVORTEX_CHECK_INTERVAL seconds. When a new release is found:

1. It pulls the floating tag that matches your desired release type (SUBVORTEX_PRERELEASE_TYPE)
2. It starts the updated container

Note: In Docker mode, the Auto Upgrader only runs if the neuron isn’t installed or during rollback to version 2.3.3. Outside of that, upgrade responsibilities are delegated to Watchtower for seamless updates.

📈 Monitoring & Logs

You can monitor the Auto Upgrader's behavior through logs, which vary depending on the SUBVORTEX_EXECUTION_METHOD you chose during setup:

• 🔧 service mode
  Logs are stored in:

  /var/log/subvortex-auto-upgrader/
  

  View logs in real time with:

  tail -f /var/log/subvortex-auto-upgrader/subvortex-auto-upgrader.log

• 🧩 process mode (PM2)
  Logs are managed by PM2 and located at:

  /root/.pm2/logs/
  

  To follow logs:

  pm2 log subvortex-auto-upgrader

• 🐳 container mode (Docker)
  Logs are available via Docker:

  docker logs subvortex-auto-upgrader -f

  Or for specific components (e.g., miner neuron):

  docker logs subvortex-auto-upgrader -f

🔍 Tips

• Add | grep ERROR or | grep WARN to quickly identify issues.
• For persistent monitoring, consider integrating with systemd journal, a log aggregator, or Prometheus log exporters.
• Always ensure your logs are rotated or cleared periodically to avoid storage bloat.

🔄 Quick Upgrade

To upgrade the Auto Upgrader when a new release has been deployed, you can run

./scripts/auto_upgrader/auto_upgrader_upgrade.sh --execution <EXECUTION_METHOD>

It will upgrade and restart the Auto Upgrader using the EXECUTION_METHOD, which defaults to service.

Use -h to see the options

🔄 Quick Restart

To stop/start the Auto Upgrader workspace and/or dumps in a quick way. Optionally to remove the current version.

./scripts/quick_restart.sh --execution <EXECUTION_METHOD>

It will restart the Auto Upgrader using the EXECUTION_METHOD, which defaults to service.

Use -h to see the options

🛑 Quick Stop

To stop the Auto Upgrader in a quick way, you can run

./scripts/quick_stop.sh --execution <EXECUTION_METHOD>

It will stop and teardown the Auto Upgrader using the EXECUTION_METHOD, which defaults to service.

Use -h to see the options

🧹 Quick Clean

To clean the Auto Upgrader workspace and/or dumps. Optionally to remove the current version.

./scripts/quick_clean.sh

Use -h to see the options

🔑 Personal Access Token

To allow the system to pull Docker images and release assets from GitHub, you need to generate a GitHub Personal Access Token (PAT).

1. Go to GitHub Settings → Developer Settings → Personal Access Tokens.

2. Choose Fine-grained tokens (recommended) or Classic (still supported).

3. Create a new token with at least the following permissions:

   • read:packages
   • read:org (required if the repository is under an organization)
   • public_repo (sometimes required for public repositories)

4. Set the token to read-only access where possible.

5. Copy and save the token securely.

Then, copy that token as value of SUBVORTEX_GITHUB_TOKEN in the main Auto Upgrader .env file.

🛠️ Installation

⚠️ Important: Use this section only if you’re experiencing issues with the quick setup.

Auto Upgarder

To manage the Auto Upgrader, refer to the user guide

Miner

⚠️ Important: It is highly recommended to install the Miner using the Auto Upgrader!

To manage the Miner manually and/or find out for the logs, refer to the user guide

Validator

⚠️ Important: It is highly recommended to install the Validator using the Auto Upgrader!

To manage the Validator manually and/or find out for the logs, refer to the user guide

Other

To manage anything else, refer to the scripts folder and check each subdirectory—each one represents a different tool or service required for the Auto Upgrader.

For each of them, the same structure applies:

• <tool|service>_setup.sh – prepares and configures the tool or service
• <tool|service>_start.sh – launches the tool or service
• <tool|service>_stop.sh – stops the tool or service gracefully
• <tool|service>_teardown.sh – fully removes and cleans up the tool or service

🛠️ Tools

Wandb

To login to wandb, run

./scripts/wandb/wandb_login.sh --api-key <WANDB_API_KEY>

To force relogin to wandb, run

./scripts/wandb/wandb_login.sh --api-key <WANDB_API_KEY> --relogin

💡 Good to Know

After installing a version through the Auto Upgrader, you can directly run various management scripts for the Miner and/or Validator. For detailed usage and available commands, refer to the SubVortex documentation

🔧 Troubleshooting

🐛 Issue: Auto Upgrader is mixing the versions or can not upgrade

Cause: The work directory may have some existing version causing an issue for the Auto Upgrader Solution: Clean the working directory

./scripts/quick_clean.sh

The script will clean the Auto Upgrader workspace and/or dumps. Optionally removes the current version.

Use option -h to see the different options.

Once cleaned, restart the auto upgrader by running

./scripts/quick_restart.sh

Use -h to see the options

🐛 Issue: Environment variable changes aren't applied after upgrade/downgrade in miner container

Cause: Watchtower does not refresh the var env when upgrading/downgrading Solution: Force to recreate (not rebuild) the image

./scripts/miner/quick_restart.sh

The script will restart all the miner's components in a way that environment variable will be reloaded

🐛 Issue: Environment variable changes aren't applied after upgrade/downgrade in validator container

Cause: Watchtower does not refresh the var env when upgrading/downgrading Solution: Force to recreate (not rebuild) the image

./scripts/validator/quick_restart.sh

The script will restart all the validator's components in a way that environment variable will be reloaded

🐛 Issue: Working directory is not synched and I can not install any new version

Cause: This is likely caused by a manual change or a bug that needs fixing. Solution: Clean your working directory entirely with the following command:

./scripts/quick_clean.sh --remove

Then, manually remove any miner and/or validator services based on the execution type you previously selected:

• service
• process
• container

To understand how each service is cleaned, set up, started, or stopped, refer to the relevant deployment folder for each neuron:

subvortex/
  └── [miner|validator]/
        └── [neuron|redis]/
              └── deployment/
                    └── [process|service|docker]

📘 You can find more details and actions in the SubVortex Repo.

🤝 Support Scope

SubVortex only provides support for components related to SubVortex mining and validating activities.

This includes:

• Auto Upgrader installation and usage
• SubVortex Miner and Validator management
• Logging, upgrades, and troubleshooting SubVortex-specific services

⚠️ Node Support Disclaimer We do not offer support for general Subtensor node operations. SubVortex is designed to scale nodes, not maintain them. As such, we cannot guarantee reliability or provide assistance with node-specific issues like syncing, peering, or Subtensor registration.

If you need help with Subtensor nodes, try one of the following resources:

• Bittensor #general channel on Discord
• Bittensor #faq channel on Discord
• Church of Rao #subtensor channel on Discord

If new user, join us first

• Bittensor - Join us
• Church of Rao - Join us

Thank you for understanding!

🪪 License

This repository is licensed under the MIT License.

# The MIT License (MIT)
# Copyright © 2024 Eclipse Vortex

# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
# documentation files (the “Software”), to deal in the Software without restriction, including without limitation
# the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
# and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

# The above copyright notice and this permission notice shall be included in all copies or substantial portions of
# the Software.

# THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
# THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
# DEALINGS IN THE SOFTWARE.