Repositories without a config

Most repositories have never heard of QuickRun. When there is no quickrun.yml, QuickRun works out how to start the repository itself, in this order:

1. a root run script — quickrun.ps1, quickrun.sh, run.ps1, run.sh
2. another launcher's config, currently Pinokio
3. detection from the files that are there

Whatever comes out of that is a plan like any other: the command list is shown, nothing runs until you approve it, and the log window says where the plan came from as its first line.

To see the result without running anything:

quickrun detect            # in the repository
quickrun detect ./my-repo --save   # write it to quickrun.yml

--save never overwrites an existing file. It is the quickest way to turn a detected or foreign config into one you can edit and commit.

Pinokio

A Pinokio app ships a pinokio.js next to install.js and start.js, whose exported run array is a list of { method, params } steps. QuickRun reads those scripts and translates them, so a Pinokio repository runs from the GitHub page like anything else — without Pinokio installed.

Pinokio	Becomes
install.js / install.json	setup steps
start.js / start.json	the tasks
shell.run message	the command, one shell per step
shell.run path	cwd
shell.run venv	a python -m venv step, then activation in front of each command
shell.run env	the task's env
on: [{ event, done: true }]	readyWhen.log, with a JavaScript /…/i flag preserved
local.set url	the address QuickRun opens when the task is ready
when	evaluated; a step whose condition is false is left out
script.start	the named script is read inline, its params become {{args}}
fs.download	a curl -L -o step
git, python, uv, node in a command	a tool requirement, checked before the run

{{ … }} templates are evaluated, including the ternaries those scripts pick their command with: {{platform === 'win32' && gpu === 'amd' ? 'python main.py --directml' : 'python main.py'}}. platform, arch, cwd, gpu, args and local are provided.

What QuickRun does not do

Pinokio scripts may be JavaScript functions rather than literals — module.exports = async (kernel) => { … }. Those ask Pinokio's own runtime for a free port or the machine's GPU list, and QuickRun cannot read them. It says so instead of guessing: if the start script is a function there is nothing to run and detection takes over; if only the install script is, the app still starts but the log says the install was skipped.

The same applies to a when condition QuickRun cannot evaluate, to fs.link's shared model drive, and to steps asking for sudo — each is left out and counted in the log. conda is Pinokio's own bundled environment; a script that needs it gets a note rather than a broken run.

Which accelerator

Scripts branch on gpu. QuickRun decides without executing anything: nvidia when nvidia-smi is on the PATH, apple on macOS, otherwise unknown — which is the CPU variant, and always works. Override it when you know better:

QUICKRUN_GPU=amd quickrun run https://github.com/pinokiofactory/comfy

Detection

When nothing else says how to start the repository, QuickRun looks at what is in it. Every candidate is shown with the command it would run; the highest-ranked one is used, and the others are listed so you can pick another with --config or a committed quickrun.yml.

Marker	Command	Address
quickrun.sh, run.sh, run.ps1	the script	—
docker-compose.yml	docker compose up	the first published port
package.json with dev, start or serve	npm run … (pnpm, yarn, bun when a lockfile says so)	--port in the script, else the framework's default
.csproj (Microsoft.NET.Sdk.Web)	dotnet run --project …	launchSettings.json, else pinned to 5000
.csproj (Aspire, OutputType Exe)	dotnet run --project …	—
.csproj (WPF, WinForms, Avalonia, WinExe)	dotnet run --project …	none - it waits for the window
manage.py	python manage.py runserver	8000
app.py with streamlit	python -m streamlit run app.py	8501
app.py/main.py with gradio	python app.py	7860
requirements.txt, pyproject.toml, uv.lock	a .venv, uv run or poetry run	fastapi 8000, flask 5000
Procfile	every process, the web one first, $PORT pinned to 8080	8080
.replit	its run = line	a --port it names
Makefile, Taskfile.yml, justfile	make run, task dev, just run	—
Cargo.toml, go.mod, pom.xml, build.gradle	cargo run, go run ./..., mvn spring-boot:run, ./gradlew bootRun	Spring 8080

A test or benchmark project is never offered as something to start.

A desktop application has no address to wait for, so a detected one gets readyWhen: {window: true} instead: the run counts as ready when the window is there, brings it to the front, and shows the process id. Without that, dotnet run reports success while the app is still building and the window is nowhere to be seen.

The address is what makes a detected run useful: it becomes a readyWhen check and an open, so QuickRun waits for the app and hands you the link instead of leaving you to find it in the log. A guessed port that turns out wrong costs a readiness timeout, not the run — and if the app prints its address, the log window picks that up as well.