Apppublic

spacetimebends/runr

sourceHugging Faceupdated 4mo agoView on Hugging Face

0likes

App README

runr

Automatically set up and run any GitHub repository using AI-powered dependency resolution.

runr https://github.com/karpathy/nanoGPT

That's it. runr clones the repo, reads every dependency file, resolves conflicts via an LLM, creates an isolated virtual environment, installs everything, and runs the project — self-healing up to 5 times if anything goes wrong.

Install

bash

pip install runr
# or, for latest:
pip install git+https://github.com/runr-cli/runr

Requires Python 3.10+. Optionally install uv for faster installs:

bash

pip install uv

Setup

Set your Groq API key (get one free at console.groq.com):

bash

export GROQ_API_KEY=gsk_...

Usage

bash

# Run a GitHub repo
runr https://github.com/karpathy/nanoGPT

# Run a local repo
runr ./my_local_project

# Force Python version
runr https://github.com/user/repo --python 3.11

# CPU-only (skip CUDA deps)
runr https://github.com/user/repo --no-gpu

# Preview plan without running
runr https://github.com/user/repo --dry-run

# Override entry point
runr https://github.com/user/repo --entry src/train.py

# Verbose (shows install logs + resolved requirements)
runr https://github.com/user/repo --verbose

# Private repo
runr https://github.com/org/private-repo --token ghp_...
# or set GITHUB_TOKEN env var

What happens

◆ runr v0.1.0

● Cloning karpathy/nanoGPT...         ✓  (2.3s)
● Detecting dependencies...           ✓  14 imports detected, 2 dep files
● Environment: Python 3.11.9, Darwin arm64, CPU only
● Resolving conflicts...              ✓  12 packages resolved
● Creating environment & installing...✓  installed via uv in 18.4s
● Entry point: python train.py

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[live repo output streams here]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Successfully completed after 1 attempt(s)

If the run fails, runr self-heals:

✗ Run failed (attempt 1/5)
  Error: No module named 'flash_attn'

◆ Healing...
  → pip install flash-attn==2.3.0
  Installing flash-attn compatible with CUDA 12.1

✓ Fix applied
● Retrying... ✓ Success

How it works

Step	Module	What it does
Clone	`cli.py`	Clones to a temp directory; never touches your original files
Detect	`detector.py`	Reads requirements.txt, setup.py, pyproject.toml, environment.yml, Dockerfile, scans .py imports
Resolve	`resolver.py`	Sends everything to Groq `llama-3.3-70b-versatile`; gets back a pinned requirements.txt
Install	`installer.py`	Creates venv via `uv venv` (falls back to `python -m venv`), installs pinned deps
Run	`runner.py`	Streams live output; on failure passes error to healer
Heal	`healer.py`	LLM returns a structured fix: install package / modify file / set env var

Caching

Resolved requirements are cached in ~/.runr/cache/ keyed by a SHA-256 hash of all dependency files. Same repo + same deps = instant resolution skip. Use --no-cache to force a fresh resolve.

Logs

Full logs are written to ~/.runr/logs/<repo>_<timestamp>.log.

Environment detection

runr automatically detects:

—Python version and OS/arch
—CUDA version (nvcc --version, nvidia-smi)
—GPU presence
—Already-installed packages (avoids re-pinning what's there)

Supported dependency files

—requirements.txt
—requirements-dev.txt
—setup.py
—setup.cfg
—pyproject.toml
—environment.yml (conda)
—Dockerfile (extracts RUN pip install lines)
—Implicit imports scanned from all .py files

Error handling

Error	How runr handles it
torch CUDA mismatch	Detects CUDA version, installs correct `+cu*` build
Package not on PyPI	LLM skips or finds alternative
Python version mismatch	Reads `requires-python`, suggests correct version
Missing system deps	Prints human-readable install instructions
Private repo	Prompts for `--token` or `GITHUB_TOKEN`
Notebook-only repo	Launches `jupyter notebook`

License

MIT