Pull worker image on demand at spawn, with progress in the workspace-creation UI #38

Closed
opened 2026-06-21 10:41:01 +02:00 by lz · 0 comments
Owner

Context

Spun out of #37. Once the claude-session probe no longer depends on the worker image (the #37 fix makes onboarding read the volume directly), the only place a worker image must exist locally is the actual worker spawn. That's where image availability should be handled.

Problem

Today spawnWorker inspects the configured worker_image and throws worker image '…' not found locally if it's absent (nexus/src/lib/server/workers/service.ts:178). The operator has no in-product way to obtain a missing image — they must docker pull/build it out of band.

Proposal

When the configured image isn't present locally at spawn time, docker.pull() it instead of throwing, and surface pull progress in the workspace-creation UI.

  • Proxy already allows it — tecnativa/docker-socket-proxy has IMAGES: 1 + POST: 1 (docker-compose.yml), which covers POST /images/create. No allowlist change needed for anonymous/public pulls. (Private-registry auth via X-Registry-Auth is out of scope for v1.)
  • Async spawn — spawn currently is a single synchronous POST → 201 with no progress channel (nexus/src/routes/api/workers/+server.ts). Introduce a status='pulling' worker state so the POST can return immediately while the pull runs.
  • Progress channel: SSE (decided during #37 brainstorm) — a new Server-Sent Events endpoint streams docker.modem.followProgress layer/% events to a real progress bar in NewWorker.svelte. One-way, no WebSocket upgrade plumbing.

Notes / open questions for its own spec

  • Worker images may be local builds with no registry backing — pull will fail for those; surface a clear "not found locally and not pullable from a registry" error.
  • Interaction with the existing label-allowlist (listWorkerImages filters by org.nexus.worker=true): a freshly-pulled image must carry the label to be spawnable; decide whether to validate the label post-pull.
  • Decide how status='pulling' interacts with the 10s health reconcile loop (don't reap a worker mid-pull).

Relationship

  • Depends on / follows #37 (containerless probe).
  • Spec to be written separately.
## Context Spun out of #37. Once the claude-session probe no longer depends on the worker image (the #37 fix makes onboarding read the volume directly), the **only** place a worker image must exist locally is the actual worker spawn. That's where image availability should be handled. ## Problem Today `spawnWorker` inspects the configured `worker_image` and throws `worker image '…' not found locally` if it's absent (`nexus/src/lib/server/workers/service.ts:178`). The operator has no in-product way to obtain a missing image — they must `docker pull`/build it out of band. ## Proposal When the configured image isn't present locally at spawn time, `docker.pull()` it instead of throwing, and surface pull progress in the workspace-creation UI. - **Proxy already allows it** — `tecnativa/docker-socket-proxy` has `IMAGES: 1` + `POST: 1` (`docker-compose.yml`), which covers `POST /images/create`. No allowlist change needed for anonymous/public pulls. (Private-registry auth via `X-Registry-Auth` is out of scope for v1.) - **Async spawn** — spawn currently is a single synchronous `POST → 201` with no progress channel (`nexus/src/routes/api/workers/+server.ts`). Introduce a `status='pulling'` worker state so the POST can return immediately while the pull runs. - **Progress channel: SSE** (decided during #37 brainstorm) — a new Server-Sent Events endpoint streams `docker.modem.followProgress` layer/% events to a real progress bar in `NewWorker.svelte`. One-way, no WebSocket upgrade plumbing. ## Notes / open questions for its own spec - Worker images may be local builds with no registry backing — pull will fail for those; surface a clear "not found locally and not pullable from a registry" error. - Interaction with the existing label-allowlist (`listWorkerImages` filters by `org.nexus.worker=true`): a freshly-pulled image must carry the label to be spawnable; decide whether to validate the label post-pull. - Decide how `status='pulling'` interacts with the 10s health reconcile loop (don't reap a worker mid-pull). ## Relationship - Depends on / follows #37 (containerless probe). - Spec to be written separately.
lz closed this issue 2026-06-23 16:13:56 +02:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
lz/agent-nexus#38
No description provided.