@r5n/hydra

The GitHub Runner Manager That Actually Scales 🚀

🏊 Made for developers who'd rather be coding than configuring

Hydra

Overview

Tired of manually setting up GitHub Actions runners? Hydra transforms hours of tedious work into a single command. Create, manage, and monitor dozens of self-hosted runners with the simplicity you've been craving.

✨ Why Hydra?

• 🚀 Lightning Fast - Create 20 runners in the time it takes to manually create 1
• 🔧 Smart Profiles - Define once, deploy anywhere with reusable configs
• 📊 Live Insights - See exactly what your runners are doing in real-time
• 🏃 73KB of Pure Speed - Installs before your coffee finishes brewing
• 🎯 Works Everywhere - macOS, Linux, Windows - we've got you covered

🎯 What Can You Do?

Create a fleet of runners in seconds

$ hydra create -t $TOKEN -u https://github.com/myorg/repo -m 10 -l "gpu,docker"
⠋ Downloading runner package... (2.1s)
✔ Created runner gpu-runner-1
✔ Created runner gpu-runner-2
✔ Created runner gpu-runner-3
✔ Created runner gpu-runner-4
✔ Created runner gpu-runner-5
✔ Created runner gpu-runner-6
✔ Created runner gpu-runner-7
✔ Created runner gpu-runner-8
✔ Created runner gpu-runner-9
✔ Created runner gpu-runner-10
✅ All 10 runners created successfully in 8.3s

Monitor your runner army

$ hydra status -p production
┌─────────────────┬─────────┬───────────┬──────────────┐
│ Name            │ Status  │ Busy      │ Labels       │
├─────────────────┼─────────┼───────────┼──────────────┤
│ prod-runner-1   │ ✅ Idle │ No        │ linux,docker │
│ prod-runner-2   │ ✅ Idle │ No        │ linux,docker │
│ prod-runner-3   │ 🔄 Busy │ Yes (2m)  │ linux,docker │
│ prod-runner-4   │ ✅ Idle │ No        │ linux,docker │
│ prod-runner-5   │ ❌ Offline │ -      │ linux,docker │
└─────────────────┴─────────┴───────────┴──────────────┘
Summary: 3 idle, 1 busy, 1 offline

Monitor runner status

$ hydra status -p production
🔍 Checking runner status...
✅ Runner 1: Online (idle)
✅ Runner 2: Online (busy - job #1234)
✅ Runner 3: Online (idle)
   ✓ Created runner-4
   ✓ Created runner-5

🔍 Monitoring continues... (press Ctrl+C to stop)

📦 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

The Magic of Profiles 🎭

Stop typing the same commands over and over. Profiles let you define your runner configurations once and reuse them everywhere:

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

• Never commit tokens to version control
• Use read-only tokens when possible
• 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

• "Invalid GitHub token"

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

• "Runner configuration failed"

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

• "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 diagnostics (if needed)
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.