- name
- repo-runner
- description
- Bootstrap and run a GitHub project by following its docs (README/docs), with safeguards for untrusted install/run steps. Use when the user gives a GitHub repo and asks to run it locally.
Repo Runner (run a GitHub project)
Goal: given a GitHub URL or a downloaded folder, get the project running as its docs intend, without guessing dangerously.
Inputs to ask for
- Repo source: GitHub URL (preferred) or local path
- Target:
dev(local dev server) /build/test - Constraints: allow installing deps? allow running postinstall scripts? allow Docker?
Safety rules (must follow)
- Treat repo code as untrusted.
- Before running
npm/pnpm/yarn install(or anycurl | bash), ask for confirmation. - Never paste or store secrets. If
.envis needed, ask user to provide values out-of-band.
Workflow
- Clone / prepare workspace
- Clone to <openclaw-workspace>/projects/<repo> (create projects/ if missing) - Typical workspace path is $HOME/.openclaw/workspace, but don’t assume. - If already exists, ask before git pull or deleting anything.
- Find the canonical docs
- Prefer README.md + docs/ + CONTRIBUTING.md - Extract: prerequisites (Node/Python/Docker/Go/Rust), install steps, env vars, run command(s), ports.
- Detect project type(s)
- From the repo-runner skill directory (typically <openclaw-workspace>/skills/repo-runner), run: bash scripts/detect_project.sh <repoDir> - A repo can match multiple types (e.g. type=node + type=docker). Use docs to choose the canonical path.
- Set up prerequisites
- Verify required runtimes exist (Node/pnpm/yarn, Python, Docker, Go, Rust) - If missing, propose options (install locally, use Docker, or switch to a supported env)
- Configure env
- If .env.example exists, copy to .env only after confirmation - Ask user to fill required keys
- Install dependencies (after confirmation, based on project type)
- Node (when package.json exists) - Prefer lockfile-safe commands: - pnpm install --frozen-lockfile (if pnpm-lock.yaml) - yarn install --frozen-lockfile (if yarn.lock) - npm ci (if package-lock.json) - If unsure, run: bash scripts/suggest_node_commands.sh <repoDir>
- Python (when pyproject.toml / requirements.txt exists) - Create and use a virtualenv (don’t install into system Python). - Typical patterns (follow docs first): - python -m venv .venv && source .venv/bin/activate - pip install -r requirements.txt - If pyproject.toml: use the tool specified by docs (commonly poetry install or pip install -e .).
- Rust (when Cargo.toml exists) - cargo build / cargo test / cargo run (follow docs for features/flags)
- Go (when go.mod exists) - go test ./... - go run . or go build ./... (follow docs for main package path)
- Docker (when docker-compose.yml / Dockerfile exists) - Prefer the documented compose path when present: - docker compose up (or docker-compose up depending on docs)
- Run
- Use the docs’ recommended run target (dev server, CLI, compose stack, etc.) - Capture logs, detect common failures, iterate
Common outputs to report back
- Exact commands run (copy/paste friendly)
- URL/port to open
- Next steps (build/test) and known caveats