SubHub

A subscription aggregation service for Clash/mihomo proxies. Fetches content from multiple airport URLs, caches results, and outputs valid Clash YAML configuration.

Quickstart

See quickstart guide for detailed setup instructions.

Prerequisites

• Python 3.12+ or Docker
• Airport subscription URLs

Local Development

# Install dependencies
uv sync

# Run the service
source .venv/bin/activate
uv run python -m src

Docker

Build and run the container:

# Build the image
docker build -t subhub:latest .

# Run the container
docker run -d \
  -p 8080:8080 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/cache:/app/cache \
  --name subhub \
  subhub:latest

# Check logs
docker logs -f subhub

# Check health
curl http://localhost:8080/health

Using Docker Compose

# Start with docker-compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

API Endpoints

• GET /health - Health check
• GET /subscription/{id} - Get subscription by source ID
• GET /sources - List all sources with status

Configuration

Edit config/config.yaml to add your subscription sources:

sources:
  - id: "a1b2c3d4e5f6789abcdef123"  # Generate with: openssl rand -hex 12
    name: "my-airport"
    url: "https://your-airport.com/sub"
    enabled: true
    cache_expiry: 7200

Documentation

• Quickstart Guide
• HTTP API Contract
• Data Model