From 241d7657e002d1c8ab6992e0c2cffa353d0343e1 Mon Sep 17 00:00:00 2001
From: fastagents <fastagents@users.noreply.github.com>
Date: Thu, 28 May 2026 14:10:11 -0600
Subject: [PATCH 1/2] docs: clarify Scope runner setup

---
 README.md          | 39 +++++++++++++++++++++++++++++++++++++++
 docker-compose.yml |  2 ++
 2 files changed, 41 insertions(+)

diff --git a/README.md b/README.md
index e1a48bd..cce432d 100644
--- a/README.md
+++ b/README.md
@@ -129,6 +129,42 @@ internally at `http://scope-live-runner:8989`. Scope stores persistent shared
 runner data at `/workspace/shared` and session-specific data under
 `/tmp/.daydream-scope/assets`.
 
+## Preloading Models
+
+The runner downloads model files on demand, but production hosts may prefer to
+preload the model cache in the persistent `scope-shared-data` volume before
+serving traffic. Run the preload from a runner container after the stack has
+started:
+
+```bash
+docker compose exec -T scope-live-runner \
+  uv run --extra livepeer python - <<'PY'
+import scope.core.pipelines.registry  # noqa: F401 - initializes pipeline registry
+from scope.server.download_models import download_models
+
+pipelines = [
+    "streamdiffusionv2",
+    "longlive",
+    "krea-realtime-video",
+    "reward-forcing",
+    "memflow",
+    "video-depth-anything",
+    "rife",
+    "scribble",
+    "ltx2",
+]
+
+for pipeline in pipelines:
+    print(f"Downloading models for {pipeline}...")
+    download_models(pipeline)
+PY
+```
+
+The zero-weight/lightweight pipelines do not require model files. If you only
+serve one pipeline, you can keep the same wrapper and remove the other entries.
+The explicit registry import is intentional: it ensures the pipeline registry is
+initialized before `download_models()` looks up pipeline artifacts.
+
 ## Multiple Scope Runners And GPU Selection
 
 Scope currently uses a single GPU per live runner instance. On multi-GPU hosts,
@@ -216,6 +252,9 @@ Expected signs of health:
 - go-livepeer starts with `orchestrator true`, `useLiveRunners true`, and
   `network arbitrum-one-mainnet`.
 - Scope logs show live-runner registration against `http://go-livepeer:8935`.
+- The Scope runner can import its live-runner dependencies. A missing
+  `websockets` package usually means the runner command is missing
+  `uv run --extra livepeer`.
 - `https://${DOMAIN}` reaches the go-livepeer service through Caddy.
 - Watchtower logs show only labeled services are monitored.
 
diff --git a/docker-compose.yml b/docker-compose.yml
index 9e212f9..8da7b79 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -10,6 +10,8 @@ services:
     command:
       - uv
       - run
+      - --extra
+      - livepeer
       - livepeer-scope
       - --host
       - 0.0.0.0

From 380d8cf65b6af646893293fe5afb15134b38c964 Mon Sep 17 00:00:00 2001
From: fastagents <fastagents@users.noreply.github.com>
Date: Thu, 28 May 2026 16:38:14 -0600
Subject: [PATCH 2/2] docs: narrow Scope runner setup guidance

---
 README.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/README.md b/README.md
index cce432d..87b3767 100644
--- a/README.md
+++ b/README.md
@@ -252,9 +252,6 @@ Expected signs of health:
 - go-livepeer starts with `orchestrator true`, `useLiveRunners true`, and
   `network arbitrum-one-mainnet`.
 - Scope logs show live-runner registration against `http://go-livepeer:8935`.
-- The Scope runner can import its live-runner dependencies. A missing
-  `websockets` package usually means the runner command is missing
-  `uv run --extra livepeer`.
 - `https://${DOMAIN}` reaches the go-livepeer service through Caddy.
 - Watchtower logs show only labeled services are monitored.