npm package: @r5n/hydra
Description: A tool for spawning multiple local GitHub self-hosted runners
Author: @ice-chillios
Latest version: 0.5.8

<div align="center">
  <a href="https://github.com/r5n-labs">
    <img src="https://avatars.githubusercontent.com/u/99986752?s=400&v=4" alt="R5N Labs" width="100" height="100">
  </a>

  <p><strong>The GitHub Runner Manager That Actually Scales 🚀</strong></p>
  <p><em>🏊 Made for developers who'd rather be coding than configuring</em></p>
  
  <h1>Hydra</h1>

  <p>
    <a href="https://www.npmjs.com/package/@r5n/hydra">
      <img src="https://img.shields.io/npm/v/@r5n/hydra.svg" alt="npm version">
    </a>
    <a href="https://github.com/r5n-labs/clis/blob/main/packages/hydra/LICENSE">
      <img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License">
    </a>
    <img src="https://img.shields.io/badge/bundle%20size-~73KB-green.svg" alt="Bundle Size">
  </p>
</div>

---

## 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?

<details>
<summary><strong>Create a fleet of runners in seconds</strong></summary>

```bash
$ 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
```
</details>

<details>
<summary><strong>Monitor your runner army</strong></summary>

```bash
$ 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
```
</details>

<details>
<summary><strong>Monitor runner status</strong></summary>

```bash
$ 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)
```
</details>

## 📦 Installation

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

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

## 🚀 Quick Start

### 1. Initialize Configuration

```bash
# Interactive setup
hydra init

# Use TOML format
hydra init --toml
```

### 2. Create Runners

```bash
# 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

```bash
# 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.

```bash
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`

```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`

```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

```bash
# 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

```bash
#!/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

```bash
# 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](https://github.com/r5n-labs/clis) for contribution guidelines.

## 📄 License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.

---