docs
FAQ

Frequently Asked Questions

General Questions

What is GSwarm?

GSwarm is a robust Go-based supervisor for Gensyn RL Swarm that provides automatic restart capabilities, dependency management, comprehensive logging, and Telegram monitoring. It's designed to enhance the user experience of running Gensyn RL Swarm.

Is GSwarm affiliated with the official Gensyn team?

No. GSwarm is NOT affiliated with or endorsed by the official Gensyn team. This is an independent, community-developed supervisor tool. We cannot modify the core RL Swarm functionality, training algorithms, or blockchain integration.

What can GSwarm do?

GSwarm can:

  • Automatically restart the RL Swarm process on errors
  • Manage Python dependencies automatically
  • Provide comprehensive logging with timestamps
  • Handle interactive prompts when flags are missing
  • Monitor performance in real-time
  • Send Telegram notifications about blockchain activity
  • Manage configuration through environment variables

What can GSwarm NOT do?

GSwarm cannot:

  • Modify training algorithms
  • Change blockchain smart contracts
  • Alter model architectures
  • Modify core hivemind functionality
  • Change the official Gensyn protocol

Installation & Setup

What are the system requirements?

  • Go 1.21+ (for building the supervisor)
  • Python 3.10+ (for the RL Swarm application)

How do I install GSwarm?

Option 1: Install with Go (Recommended)

go install github.com/Deep-Commit/gswarm/cmd/gswarm@latest

Option 2: Build from source

git clone https://github.com/Deep-Commit/gswarm.git
cd gswarm
make build
make install

Why can't I find the gswarm command after installation?

Make sure your Go bin directory is in your PATH:

For bash/zsh:

export PATH=$PATH:$(go env GOPATH)/bin

For fish:

set -gx PATH $PATH (go env GOPATH)/bin

Add this to your shell configuration file to make it permanent.

Usage

What's the difference between interactive and non-interactive mode?

  • Interactive Mode (default): Prompts for all necessary configuration
  • Non-interactive Mode: Uses provided flags, prompts only for missing required values

How do I run GSwarm in non-interactive mode?

Provide all configuration via command line flags:

gswarm --org-id YOUR_ORG_ID --hf-token YOUR_TOKEN --model-size 7

What are the valid model sizes?

Valid model sizes are: 0.5, 1.5, 7, 32, 72 (in billions of parameters).

What are the valid game types?

Valid game types are: gsm8k and dapo.

How do I handle HuggingFace tokens?

  • If provided via --hf-token: Uses the provided token without prompting
  • If not provided: Prompts interactively asking if you want to push models to HuggingFace Hub

Telegram Monitoring

How do I set up Telegram monitoring?

  1. Create a bot with @BotFather (opens in a new tab)
  2. Get your chat ID by sending a message to your bot
  3. Run gswarm --telegram and follow the prompts

What notifications will I receive?

You'll receive notifications about:

  • Vote changes (increases/decreases)
  • Reward changes
  • Balance changes
  • Welcome message on setup

How often does the Telegram service check for updates?

The service checks for updates every 30 seconds by default.

Can I use Telegram monitoring with multiple users?

Currently, the service supports one chat ID per configuration. For multiple recipients:

  1. Add multiple users to a Telegram group
  2. Use the group chat ID instead of individual chat IDs
  3. Create multiple bot instances if needed

Troubleshooting

"python3 not found" error

Ensure Python 3.10+ is installed and in PATH:

python3 --version

"Requirements installation failed" error

  • Ensure requirements.txt exists in your RL Swarm directory
  • Check network connectivity for pip install

"HF token prompt appears when not expected"

Use --hf-token YOUR_TOKEN to provide the token via command line:

gswarm --hf-token YOUR_TOKEN --org-id YOUR_ORG_ID

"Invalid model-size value" error

Use one of the valid values: 0.5, 1.5, 7, 32, 72

gswarm --model-size 7

"Invalid game type" error

Use either gsm8k or dapo:

gswarm --game gsm8k

"Bot token invalid" error

  • Verify your bot token from @BotFather
  • Use --update-telegram-config to re-enter it

"Chat ID not found" error

  • Make sure you've sent a message to your bot
  • Check the getUpdates URL response
  • Use --update-telegram-config to re-enter it

"No notifications received" from Telegram

  • Check that your bot is active
  • Verify the chat ID is correct
  • Ensure you have blockchain activity to monitor

Configuration

How do I use environment variables?

All flags can be set via environment variables with the GSWARM_ prefix:

export GSWARM_TESTNET=true
export GSWARM_MODEL_SIZE=7
export GSWARM_ORG_ID=your-org-id
export HUGGINGFACE_ACCESS_TOKEN=your-token
gswarm

Where are logs stored?

Logs are written to logs/gensyn_rl_swarm_go.log by default.

How do I enable debug mode?

Set the environment variable for verbose logging:

export SWARM_DEBUG=1
gswarm

Can I use custom requirements files?

Yes, use the --requirements flag:

gswarm --requirements requirements-gpu.txt

Development

How do I build from source?

git clone https://github.com/Deep-Commit/gswarm.git
cd gswarm
make build
make install

How do I run tests?

make test
make test-coverage

How do I contribute to GSwarm?

  1. Fork the repository on GitHub
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Support

Where can I get help?

  • GitHub Issues: Report bugs and request features
  • Documentation: Check this documentation for answers
  • Community: Join discussions on GitHub

How do I report a bug?

When reporting issues, please include:

  • GSwarm version (gswarm --version)
  • Operating system and version
  • Python version (python3 --version)
  • Go version (go version)
  • Error messages and logs
  • Steps to reproduce the issue

How do I request a feature?

For feature requests:

  • Describe the feature clearly
  • Explain the use case
  • Consider if it fits within the project's scope
  • Check if similar features already exist

Legal & Licensing

What license does GSwarm use?

This project is licensed under the MIT License.

Can I use GSwarm commercially?

Yes, the MIT License allows commercial use.

How can I support the project?

You can support the project by making a donation to:

0xA22e20BA3336f5Bd6eCE959F5ac4083C9693e316

Your support helps us maintain and improve the supervisor tool, add new features, and keep the project free and open source.

API ReferenceChangelog