@r5n/hydra v0.5.0

Overview

Hydra is a powerful CLI tool for managing multiple GitHub self-hosted runners locally. Built by R5N Labs, it simplifies the creation, management, and monitoring of GitHub Actions runners at scale.

✨ Key Features

• 🚀 Parallel Runner Management - Create and manage multiple runners simultaneously using Web Workers
• 🔧 Profile-Based Configuration - Store and reuse configurations with JSON/TOML support
• 📊 Real-Time Status Monitoring - Check runner status with formatted or JSON output
• 🏃 Zero Runtime Dependencies - Fully bundled (~73KB) for optimal performance
• 🎯 Cross-Platform Support - Works on macOS, Linux, and Windows

📦 Installation

# Using Bun (recommended)
bun add -g @r5n/hydra
hydra --help

# Direct usage (no installation)
bunx @r5n/hydra --help

🚀 Quick Start

1. Initialize Configuration

# Interactive setup
hydra init

# Use TOML format
hydra init --toml

2. Create Runners

# Basic usage
hydra create -t YOUR_TOKEN -u https://github.com/org/repo

# Create multiple runners with labels
hydra create -t YOUR_TOKEN -u REPO_URL -m 3 -l "docker,gpu"

# Using a profile
hydra create -p production -t YOUR_TOKEN

3. Monitor Status

# Check runner status
hydra status -t YOUR_TOKEN -u REPO_URL

# JSON output for automation
hydra status -t YOUR_TOKEN -u REPO_URL --json

📖 Commands

hydra init

Initialize a new configuration file with profiles.

Options:

• -t, --toml - Use TOML format instead of JSON

hydra create

Create and register new GitHub runner machines.

Options:

• -t, --token - GitHub Personal Access Token (required)
• -u, --url - GitHub repository/organization URL (required)
• -m, --numberOfMachines - Number of runners to create (default: 1)
• -n, --name - Runner name prefix (default: "runner")
• -l, --labels - Comma-separated custom labels
• -d, --directory - Runners directory (default: "./gh-runners")
• -o, --os - Operating system: osx, linux, windows (default: "osx")
• -O, --overwrite - Overwrite existing runners
• -p, --profile - Use configuration profile
• -c, --config - Configuration file path

hydra run

Start existing GitHub runner machines.

Options:

• -t, --token - GitHub Personal Access Token (required)
• -u, --url - GitHub repository/organization URL (required)
• -m, --numberOfMachines - Number of runners (default: 1)
• -n, --name - Runner name prefix
• -d, --directory - Runners directory
• -p, --profile - Use configuration profile
• -c, --config - Configuration file path

hydra remove

Remove GitHub runner machines.

Options:

• -t, --token - GitHub Personal Access Token (required)
• -u, --url - GitHub repository/organization URL (required)
• -m, --numberOfMachines - Number of runners (default: 1)
• -n, --name - Runner name prefix
• -d, --directory - Runners directory
• -f, --force - Force removal without unregistering
• -p, --profile - Use configuration profile
• -c, --config - Configuration file path

hydra status

Check the status of GitHub runner machines.

Options:

• -t, --token - GitHub Personal Access Token (required)
• -u, --url - GitHub repository/organization URL (required)
• -d, --directory - Runners directory
• -j, --json - Output as JSON
• -p, --profile - Use configuration profile
• -c, --config - Configuration file path

hydra help

Show help information for commands.

hydra help
hydra help create
hydra create --help

🔧 Configuration

Profile System

Hydra supports configuration profiles to simplify runner management across different environments.

Example: hydra.json

{
  "profiles": {
    "default": {
      "name": "runner",
      "numberOfMachines": 1,
      "directory": "./gh-runners",
      "os": "osx"
    },
    "production": {
      "url": "https://github.com/org/repo",
      "name": "prod-runner",
      "numberOfMachines": 3,
      "labels": "production,linux,docker",
      "directory": "/opt/runners/prod",
      "os": "linux"
    },
    "development": {
      "url": "https://github.com/org/dev-repo",
      "name": "dev-runner",
      "numberOfMachines": 2,
      "labels": "development,test",
      "directory": "./dev-runners"
    }
  },
  "defaultProfile": "default"
}

Example: hydra.toml

defaultProfile = "default"

[profiles.default]
name = "runner"
numberOfMachines = 1
directory = "./gh-runners"
os = "linux"

[profiles.production]
url = "https://github.com/org/repo"
name = "prod-runner"
numberOfMachines = 3
labels = "production,linux,docker"
directory = "/opt/runners/prod"
os = "linux"

Environment Variables

• GITHUB_PERSONAL_ACCESS_TOKEN - Default token if not provided via CLI
• HYDRA_CONFIG - Default configuration file path

📂 Directory Structure

./gh-runners/              # Default runner directory
├── machines/
│   ├── 1/                # Runner instance 1
│   │   ├── _diag/        # Diagnostics logs
│   │   ├── _work/        # Job working directory
│   │   ├── config.sh     # Runner configuration
│   │   └── run.sh        # Runner execution script
│   ├── 2/                # Runner instance 2
│   └── .../
└── actions-runner-*.tar.gz  # Downloaded runner package

🔐 Security

Token Requirements

• Repository runners: Token needs repo scope
• Organization runners: Token needs admin:org scope
• Tokens are never stored in configuration files
• Use environment variables for automation

Best Practices

1. Never commit tokens to version control
2. Use read-only tokens when possible
3. Rotate tokens regularly

📊 Examples

CI/CD Pipeline Setup

# Development environment
hydra create -p development -t $GITHUB_TOKEN -m 2

# Production with specific labels
hydra create -p production -t $GITHUB_TOKEN -l "deploy,production"

# Temporary test runners
hydra create -t $GITHUB_TOKEN -u $REPO_URL -n "test" -m 5
hydra remove -t $GITHUB_TOKEN -u $REPO_URL -n "test" -m 5

Monitoring Script

#!/bin/bash
# Check runner status and alert if offline

STATUS=$(hydra status -p production -t $GITHUB_TOKEN --json)
OFFLINE=$(echo $STATUS | jq '[.[] | select(.status == "offline")] | length')

if [ $OFFLINE -gt 0 ]; then
  echo "Alert: $OFFLINE runners are offline!"
fi

🐛 Troubleshooting

Common Issues

1. "Invalid GitHub token"

   • Verify token permissions (repo/admin:org scope)
   • Check token expiration

2. "Runner configuration failed"

   • Check network connectivity
   • Verify GitHub URL format
   • Ensure write permissions in runner directory

3. "No runners found"

   • Verify runner directory path
   • Check if runners were created successfully
   • Ensure profile name is correct

Debug Mode

# Run with debug logging
DEBUG=* hydra create -t TOKEN -u URL

# Check runner logs
cat ./gh-runners/machines/1/_diag/*.log

🤝 Contributing

Contributions are welcome! Please see the main repository for contribution guidelines.

📄 License

Licensed under the Apache License, Version 2.0. See LICENSE for details.