bug: Docker driver pulls every tag of a repository when `--from` has no tag

[mpereira]

User Story

As someone creating a sandbox from an image reference without a tag,
I want OpenShell to pull only latest, as docker pull does,
so that one sandbox doesn't download the repository's whole tag history.

Problem Statement

pull_image() in crates/openshell-driver-docker/src/lib.rs passes the reference to the Engine API as fromImage with no tag. When neither a tag nor a digest is given, the daemon pulls every tag in the repository, the same as docker pull --all-tags. The docker CLI appends :latest to a bare reference before calling the API. Given that, I'd say pulling only "latest" would follow the principle of least surprise.

With the default image_pull_policy of if_not_present, this happens the first time an untagged image is used. A reference with a tag or digest is pulled correctly. From reading the code, the Podman and VM drivers pull a single tag, but I only ran Docker.

Impact / Why This Matters

openshell sandbox create --from nicolaka/netshoot spent minutes pulling and left 20 images across 37 tags in the local store, about 9.5 GB by listed size. OpenShell used only latest. On Docker Hub, each of those tags also counts against the pull-rate limit.

The workaround is to always pass a tag, for example --from nicolaka/netshoot:v0.16. Nothing says you need to, so you only find out from docker images afterwards (and from the long image pull step in openshell sandbox create)

Acceptance Criteria

• On the Docker driver, --from <repo> with no tag or digest pulls only <repo>:latest.
• References with a tag or digest are pulled unchanged.
• Unit tests cover the normalization, including localhost:5000/img, where the colon isn't a tag separator.

Reproduction Steps

1. docker rmi $(docker images nicolaka/netshoot -q) to remove local copies.
2. openshell sandbox create --name test-sandbox --detach --from nicolaka/netshoot
3. docker images nicolaka/netshoot lists every published tag, not just latest.

(The netshoot image has USER root, so the command from step #2 fails, but that's unrelated.)

Environment

• OpenShell 0.1.2 (Homebrew) on macOS 26.2 arm64, local Docker gateway. The pull code is the same on current main.
• Docker Engine 29.4.0 (linux/arm64)

Logs

$ docker images nicolaka/netshoot
nicolaka/netshoot   latest   7f199a2cf92c   3 months ago    653MB
nicolaka/netshoot   v0.16    7f199a2cf92c   3 months ago    653MB
nicolaka/netshoot   v0.15    e8aef26f9613   8 months ago    637MB
nicolaka/netshoot   v0.14    3be5270ddd56   15 months ago   622MB
... [a bunch more]
nicolaka/netshoot   v0.1     f6a4dd84d730   4 years ago     410MB
nicolaka/netshoot   test     18dc8492ac15   5 years ago     367MB
nicolaka/netshoot   edge     f2cea5d9c42d   7 years ago     188MB

[efegokdemir]

I'd like to work on this. I'll reproduce the bare-image reference handling against current main and add focused normalization coverage for tags, digests, and registry ports.

[elezar]

📋 triage-agent

Triage Assessment

Classification: validated-bug

Summary

The Docker compute driver sends an untagged image reference to the Engine API without selecting latest. Docker documents that this request pulls all tags. The reported behavior is supported by current code and the API contract; confidence in the defect is high. The report contains sufficient user story, impact, acceptance criteria, reproduction steps, and environment details.

Investigation

• In the Docker image preparation path, the default if_not_present policy calls pull_image() after a local inspection miss. always also calls it; a cache hit or never avoids the pull.
• pull_image() supplies the reference unchanged as from_image and leaves the separate tag unset. The Docker Engine API contract specifies all-tags behavior when neither tag nor digest is supplied. In contrast, docker image pull defaults an untagged reference to latest. Explicit tags and digests select a specific reference.
• This is owned by openshell-driver-docker. The acceptance criteria are observable and consistent with the user story, including localhost:5000/img: its registry port does not specify an image tag. The separate Docker runtime-image pull helper has the same request pattern, so bare configured runtime references have related exposure. This assessment does not establish a defect in Podman or VM.
• The reported v0.1.2 is the latest stable release in GitHub release metadata. Remote main checked during triage still contains the request pattern. PR #4045 proposes a fix for this issue but is closed and unmerged; its comments show the contributor vouch gate. It is not a released fix. Searches of open and closed issues found no canonical duplicate.
• Validation here was source/API-contract analysis plus an independent principal-engineer review, not a fresh end-to-end all-tags pull. The reported subsequent USER root rejection does not invalidate the pull observation: image preparation precedes workload identity validation.

Impact Signals

• Affected users/scope: Docker-driver sandbox creators using bare repository references when an actual pull occurs. Scope is not intrinsically limited to the reporter's macOS/arm64 host. The report shows minutes of unexpected latency and many unrelated local image tags.
• Regression: Unknown; the earliest affected release and introduction point were not established. Present in reported v0.1.2 and current main.
• Workaround: Supply :latest, another explicit tag, or a digest. This avoids the request ambiguity but requires users to know about it before using a supported bare reference.
• Evidence quality: High for the causal defect (code plus documented Engine semantics, consistent with reporter output); quantitative resource impact is reporter-supplied. The approximately 9.5 GB is summed listed image size, not measured unique disk consumption or downloaded bytes. Incremental bandwidth, shared-layer storage, and Docker Hub pull-limit consumption were not independently measured.

Human Decision Required

Decide whether OpenShell should address this issue. If yes, apply state:accepted, associate it with a roadmap item, or do both, and decide whether the work remains human-owned. Either action records acceptance; roadmap placement additionally records sequencing.

To queue investigation or planning for an unattended agent, also apply agent:plan-requested. You can instead directly ask an agent to use create-spike or build-from-issue on this issue; it will warn about missing expected workflow labels and continue without changing them. If no, close it as not planned and record the rationale.