docs
Getting Started

Getting Started

Basic Usage

Interactive Mode (Default)

When run without any flags, the supervisor will prompt for all necessary configuration:

cd /path/to/gensyn-rl-swarm
gswarm

Command Line Mode

You can provide all configuration via command line flags for non-interactive operation:

gswarm --config-path config.yaml --hf-token YOUR_TOKEN --identity-path identity.pem --org-id YOUR_ORG_ID --contract-address 0x... --game gsm8k
gswarm --requirements requirements-cpu.txt
gswarm --model-size 32 --big-swarm --org-id YOUR_ORG_ID

Beautiful CLI Help

GSwarm features a beautiful, comprehensive help system:

# Show main help
gswarm --help
 
# Show version information
gswarm version
 
# Show help for specific command
gswarm help version

Command Line Options

FlagDescriptionDefaultEnvironment Variable
--testnetConnect to the TestnetfalseGSWARM_TESTNET
--big-swarmUse big swarm (Math Hard) instead of small swarm (Math)falseGSWARM_BIG_SWARM
--model-sizeParameter count in billions (0.5, 1.5, 7, 32, 72)0.5GSWARM_MODEL_SIZE
--hf-tokenHuggingFace access token for model pushingHUGGINGFACE_ACCESS_TOKEN, GSWARM_HF_TOKEN
--org-idModal ORG_ID (required for testnet)GSWARM_ORG_ID
--identity-pathPath to identity PEM fileswarm.pemGSWARM_IDENTITY_PATH
--contract-addressOverride smart contract addressAuto-detectedGSWARM_CONTRACT_ADDRESS
--gameGame type ('gsm8k' or 'dapo')Auto-detectedGSWARM_GAME
--config-pathPath to YAML config fileAuto-detectedGSWARM_CONFIG_PATH
--cpu-onlyForce CPU-only modefalseGSWARM_CPU_ONLY
--requirementsRequirements file path (overrides default)GSWARM_REQUIREMENTS
--interactiveForce interactive mode (prompt for all options)falseGSWARM_INTERACTIVE

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

HuggingFace Token Handling

The supervisor intelligently handles 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
# No prompt for HF token (provided via command line)
gswarm --hf-token YOUR_TOKEN --org-id YOUR_ORG_ID
 
# Will prompt for HF token (not provided)
gswarm --org-id YOUR_ORG_ID

Non-Interactive Mode Examples

gswarm \
  --org-id YOUR_ORG_ID \
  --identity-path /path/to/identity.pem \
  --hf-token YOUR_HF_TOKEN \
  --model-size 7 \
  --big-swarm \
  --cpu-only
gswarm \
  --org-id YOUR_ORG_ID \
  --identity-path /path/to/identity.pem \
  --hf-token YOUR_HF_TOKEN \
  --model-size 0.5 \
  --cpu-only

Key Benefits of Non-Interactive Mode:

  • No manual input required during startup
  • Perfect for automated deployments and scripts
  • Consistent configuration across runs
  • Faster startup time

Examples

# Interactive mode (default)
gswarm
 
# Non-interactive mode with all options
gswarm --testnet --big-swarm --model-size 7 --org-id YOUR_ORG_ID --hf-token YOUR_TOKEN
 
# CPU-only mode
gswarm --cpu-only --model-size 0.5
 
# Custom requirements file
gswarm --requirements requirements-gpu.txt
 
# Show version
gswarm version

How It Works

Dependency Management

  • Checks Python 3.10+ availability
  • Installs dependencies from requirements.txt or requirements-*.txt
  • Supports custom requirements files

Process Management

  • Starts and supervises the RL Swarm process with provided arguments
  • Streams output in real-time
  • Monitors for error patterns

Error Handling

  • Detects specific error messages
  • Automatically restarts the process
  • Implements exponential backoff

Configuration Modes

  • Command Line Mode: Uses provided flags, prompts only for missing required values
  • Interactive Mode: Prompts for all configuration interactively

Logging

Logs are written to logs/gensyn_rl_swarm_go.log with:

  • Timestamps with microsecond precision
  • Process IDs for tracking
  • All stdout/stderr output
  • Supervisor events (starts, restarts, errors)

Example log entry:

2024-01-01 12:00:00.000000 Starting RL Swarm with config: config.yaml
2024-01-01 12:00:01.123456 [PID 12345] >> Starting RL Swarm...
2024-01-01 12:00:02.234567 [PID 12345] >> Loading configuration...

Debug Mode

Set environment variable for verbose logging:

export SWARM_DEBUG=1
gswarm

Troubleshooting

Common Issues

"Requirements installation failed"

  • 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
  • The prompt only appears when no token is provided

"Invalid model-size value"

  • Use one of the valid values: 0.5, 1.5, 7, 32, 72
  • Example: gswarm --model-size 7

"Invalid game type"

  • Use either gsm8k or dapo for the game parameter
  • Example: gswarm --game gsm8k

Next Steps

Now that you understand the basics, you can:

  1. Explore Telegram Monitoring for real-time notifications
  2. Check out Advanced Usage for more complex configurations
  3. Review the API Reference for detailed command options
InstallationTelegram Monitoring