Fix Orbstack Docker Pull

Name: Fix Orbstack Docker Pull
Author: hexbee

hexbee/hello-skills

4 installs
1 repo stars
Updated July 31, 2026
hexbee/hello-skills

Diagnoses and fixes Docker image pull EOF and TLS failures on macOS OrbStack caused by proxies or fake-ip DNS.

About

Diagnoses and fixes Docker image pull failures on macOS OrbStack, especially Docker Hub EOF/TLS/manifest errors caused by system proxies, Clash/TUN fake-ip DNS, or unstable registry access. A developer uses it when docker pull or manifest inspect fails with connectivity errors.

Treats Docker Hub EOF on OrbStack as a network path problem
Diagnoses Clash/TUN fake-ip DNS (198.18.0.x) and proxy misrouting

Fix Orbstack Docker Pull by the numbers

4 all-time installs (skills.sh)
Ranked #1,101 of 1,435 DevOps & CI/CD skills by installs in the Skillselion catalog
Data as of Aug 2, 2026 (Skillselion catalog sync)

npx skills add https://github.com/hexbee/hello-skills --skill fix-orbstack-docker-pull

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/hexbee/hello-skills/fix-orbstack-docker-pull.svg)](https://skillselion.com/skills/hexbee/hello-skills/fix-orbstack-docker-pull)

Installs	4
repo stars	★ 1
Last updated	July 31, 2026
Repository	hexbee/hello-skills ↗

What it does

Diagnoses and fixes Docker image pull EOF and TLS failures on macOS OrbStack caused by proxies or fake-ip DNS.

Files

SKILL.mdMarkdownGitHub ↗

Fix OrbStack Docker Pull

Core Rule

Treat Docker Hub EOF on OrbStack as a network path problem until proven otherwise. Do not assume the image is missing, private, or platform-incompatible before testing a small public image and the daemon's proxy path.

Expected responses that are not failures:

curl -I https://auth.docker.io returning HTTP/2 404 is normal for the auth service root.
curl -I https://registry-1.docker.io returning HTTP/2 404 is normal for the registry root.
curl -I https://registry-1.docker.io/v2/ returning 401 with www-authenticate: Bearer ... is the expected unauthenticated registry response.

Suspicious signals:

docker pull hello-world:latest fails with Head "https://registry-1.docker.io/v2/.../manifests/latest": EOF.
docker buildx imagetools inspect or docker manifest inspect fails while explicit curl -x http://127.0.0.1:<port> succeeds.
registry-1.docker.io resolves to 198.18.0.x, which usually indicates Clash-style fake-ip/TUN routing.
macOS has system HTTP/HTTPS proxy enabled, but OrbStack Docker daemon is still using an unstable automatic proxy path.

Quick Diagnose

Run the bundled read-only diagnostic script first when local shell access is available:

/Users/jiamingfeng/.codex/skills/fix-orbstack-docker-pull/scripts/diagnose-orbstack-docker-pull.sh

If the skill has been installed elsewhere, resolve the script relative to this SKILL.md.

If running manually, collect these facts:

docker version
docker info
orb version
orb config get network_proxy
sed -n '1,120p' ~/.orbstack/config/docker.json
networksetup -getwebproxy Wi-Fi
networksetup -getsecurewebproxy Wi-Fi
dscacheutil -q host -a name registry-1.docker.io
dig registry-1.docker.io
netstat -rn -f inet | grep -E '198\\.18|default|utun'
curl -I --max-time 15 https://registry-1.docker.io/v2/
curl -x http://127.0.0.1:7890 -I --max-time 15 https://registry-1.docker.io/v2/
docker pull hello-world:latest

Adapt the proxy port from networksetup; do not hard-code 7890 unless the system proxy reports it.

Fix Workflow

1. Confirm the issue is general:

docker pull hello-world:latest

If hello-world also fails with Docker Hub EOF, focus on daemon networking rather than the requested image.

2. Find the active macOS proxy:

networksetup -getwebproxy Wi-Fi
networksetup -getsecurewebproxy Wi-Fi
ps aux | grep -Ei 'clash|cyberclash|mihomo|sing-box|surge|stash|v2ray|xray|shadow|proxy' | grep -v grep

If Server: 127.0.0.1 and Port: 7890 appear, the proxy URL is http://127.0.0.1:7890. Use the actual service name if the Mac is not using Wi-Fi.

3. Make OrbStack use the proxy explicitly:

orb config set network_proxy http://127.0.0.1:<port>
orb restart docker

Verify:

orb config get network_proxy
docker pull hello-world:latest

4. If pulls still intermittently EOF or large layers hang, reduce Docker daemon download concurrency:

{
  "max-concurrent-downloads": 1
}

Write that JSON to ~/.orbstack/config/docker.json, preserving any existing daemon settings. Then restart:

orb restart docker
docker pull <image>

5. Continue interrupted pulls instead of cleaning state:

docker pull <image>
docker system df
orb logs docker | tail -80

Docker often retains partially downloaded blobs after an interrupted pull. Avoid docker system prune unless the user explicitly wants to discard partial progress.

Interpretation Guide

registry-1.docker.io resolving to 198.18.0.x is a fake-ip/TUN clue, not the real Docker Hub endpoint.
curl -x http://127.0.0.1:<port> -I https://registry-1.docker.io/v2/ succeeding while direct curl or Docker fails means the explicit proxy path is healthier than auto/TUN routing.
docker manifest inspect may fail from the macOS-side client path even when docker pull succeeds through the daemon path; prioritize docker pull hello-world and the actual target pull for validation.
A long pause during a large layer can still be normal. Check docker system df growth or daemon logs before killing the pull.
If the proxy port changes after reboot, update OrbStack with the new port and restart Docker.

Persistence

These settings persist across Mac reboots:

orb config get network_proxy
sed -n '1,120p' ~/.orbstack/config/docker.json

Before future pulls, the user usually only needs OrbStack and the proxy app running. If the proxy app changes port, rerun:

orb config set network_proxy http://127.0.0.1:<new-port>
orb restart docker

interface:
  display_name: "Fix OrbStack Docker Pull"
  short_description: "Fix OrbStack Docker pull EOFs"
  default_prompt: "Use $fix-orbstack-docker-pull to diagnose my OrbStack Docker pull failure and apply the safest proxy or daemon configuration fix."

#!/usr/bin/env bash

set -u

section() {
  printf '\n== %s ==\n' "$1"
}

run() {
  printf '\n$ %s\n' "$*"
  "$@" 2>&1 || printf '[exit %s]\n' "$?"
}

run_shell() {
  printf '\n$ %s\n' "$*"
  sh -c "$*" 2>&1 || printf '[exit %s]\n' "$?"
}

find_network_services() {
  networksetup -listallnetworkservices 2>/dev/null \
    | sed '1d' \
    | sed 's/^*//'
}

print_service_proxy() {
  service="$1"
  printf '\n-- %s --\n' "$service"
  networksetup -getwebproxy "$service" 2>&1 | sed 's/^/HTTP: /'
  networksetup -getsecurewebproxy "$service" 2>&1 | sed 's/^/HTTPS: /'
}

section "Versions and Context"
run docker version
run_shell "docker info | sed -n '1,120p'"
run orb version
run docker context ls

section "OrbStack Configuration"
run orb config get network_proxy
run_shell "test -f ~/.orbstack/config/docker.json && sed -n '1,160p' ~/.orbstack/config/docker.json || true"
run_shell "test -f ~/.docker/config.json && sed -n '1,160p' ~/.docker/config.json || true"

section "macOS Proxy Settings"
if command -v networksetup >/dev/null 2>&1; then
  services="$(find_network_services)"
  if [ -n "$services" ]; then
    printf '%s\n' "$services" | while IFS= read -r service; do
      [ -n "$service" ] && print_service_proxy "$service"
    done
  else
    print_service_proxy "Wi-Fi"
  fi
else
  printf 'networksetup not found\n'
fi

section "Proxy Processes and Common Ports"
run_shell "ps aux | grep -Ei 'clash|cyberclash|mihomo|sing-box|surge|stash|v2ray|xray|shadow|quantum|loon|proxy' | grep -v grep || true"
run_shell "lsof -nP -iTCP -sTCP:LISTEN | grep -E ':(7890|7897|7899|1080|1087|20171|6152|8080|9090|8888) ' || true"

section "DNS and TUN Clues"
run dscacheutil -q host -a name registry-1.docker.io
run dscacheutil -q host -a name auth.docker.io
run_shell "dig registry-1.docker.io 2>/dev/null | sed -n '1,80p' || true"
run_shell "netstat -rn -f inet | grep -E '198\\.18|default|utun|bridge' || true"
run_shell "ifconfig | grep -E '^[a-z0-9]+:|198\\.18|utun|inet ' || true"

section "Registry Connectivity"
run curl -I --max-time 20 https://auth.docker.io
run curl -I --max-time 20 https://registry-1.docker.io
run curl -I --max-time 20 https://registry-1.docker.io/v2/

section "Explicit Proxy Connectivity"
proxy_url="$(orb config get network_proxy 2>/dev/null || true)"
case "$proxy_url" in
  http://*|https://*)
    run curl -x "$proxy_url" -I --max-time 20 https://registry-1.docker.io/v2/
    ;;
  *)
    printf 'OrbStack network_proxy is not an explicit URL: %s\n' "$proxy_url"
    ;;
esac

section "Docker Pull Smoke Test"
run docker pull hello-world:latest

section "Recent Docker Daemon Logs"
run_shell "orb logs docker | tail -80"

section "Summary Hints"
cat <<'EOF'
- auth.docker.io root 404 and registry root 404 are normal.
- registry-1.docker.io/v2/ should return 401 with a Bearer challenge.
- 198.18.0.x DNS answers usually mean fake-ip/TUN proxy mode.
- If explicit proxy curl works but docker pull EOFs, set OrbStack explicitly:
  orb config set network_proxy http://127.0.0.1:<port>
  orb restart docker
- If large pulls still hang/EOF, preserve existing JSON and add:
  "max-concurrent-downloads": 1
EOF