The Complete Production SOP: How to Deploy and Run Distribution Registry V2 & Pull-Through Caching in Autonomous AI Agents
Production SOP to deploy Docker Registry V2 pull-through cache with Codex, Claude Code, and Cursor. Bypass Docker Hub limits with deterministic agent workflows.
Technical Overview & Architectural Context
Autonomous coding agents (Codex, Claude Code, Cursor, Windsurf) frequently fail when generating Docker Registry V2 configurations and pull-through mirrors. Without rigorous domain SOPs, agents commonly hallucinate non-existent registry v3 directives, mistakenly attempt to enable push operations on pull-through caches (which the CNCF Distribution spec expressly forbids), misconfigure storage read-only flags during garbage collection, or omit required HTTP TLS and remote URL proxy credentials. Furthermore, agents often alter client-side Docker configurations without verifying TLS SAN certificates or fail to structure client `/etc/docker/daemon.json` files correctly, precipitating catastrophic CI/CD build failures and Docker Hub rate limit blocks (HTTP 429 Too Many Requests). The `registry-v2-distribution-mirror` skill enforces deterministic declarative boundaries: it anchors the agent to valid CNCF Distribution v2 YAML schemas, forces separate storage profiles for cache layers, and mandates offline read-only maintenance locks prior to executing mark-and-sweep garbage collection.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the skill manifest into your agent runtime workspace or global rules path to expose registry-v2 triggers.
Autonomous agent engines discover custom capabilities via workspace-level `.agents/skills` directories or agent rule configurations (`.cursor/rules`, `.claude/skills`). By placing the `registry-v2-distribution-mirror` manifest in the project workspace, agents match triggers like 'setup docker pull through cache' and ingest strict procedural constraints regarding CNCF Distribution V2 specs.
mkdir -p .agents/skills/registry-v2-distribution-mirror && curl -fsSL https://askills.dev/api/skills/registry-v2-distribution-mirror/raw -o .agents/skills/registry-v2-distribution-mirror/SKILL.md---
name: "registry-v2-distribution-mirror"
description: "Deploy private Docker Registry V2 with pull-through caching for Docker Hub rate limits."
metadata:
author: "Distribution"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "setup docker pull through cache"
- "configure distribution registry"
- "run registry garbage collect"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# Distribution Registry V2 & Pull-Through Caching
Deploys CNCF Distribution (Registry V2): configuring pull-through cache mirrors for Docker Hub, S3/Azure storage drivers, htpasswd authentication, TLS termination, and registry garbage collection.
## Execution SOP & Rules
1. Deploy registry container with proxy.remoteurl: https://registry-1.docker.io configuration.
2. Configure daemon.json on client machines: registry-mirrors: ['https://mirror.internal.lan:5000'].
3. Set storage credentials under storage.s3 in config.yml.
4. Run garbage collection: registry garbage-collect /etc/docker/registry/config.yml.Keep the SKILL.md permissions restricted to `fs_write: workspace` and `shell_exec: false`. By enforcing these flags, the agent writes production manifests (`config.yml`, `docker-compose.yml`) into the repository for human audit instead of invoking privileged docker socket commands blindly.
In Cursor and Windsurf, ensure the directory containing `.agents/` is included in the workspace root; otherwise, context indexing might ignore the skill's trigger definitions.
Generate Distribution V2 Manifest and Remote Proxy Configuration
Instruct the agent to generate an immutable, production-ready CNCF Distribution config.yml with proxy caching enabled.
Docker Hub pull-through mirrors must declare the `proxy` block referencing `https://registry-1.docker.io`. To prevent upstream rate limiting when authenticating with a paid Docker Hub account, optional Docker Hub credentials can be passed via environment variables. The skill directs the agent to generate both `config.yml` and a companion `compose.yaml` file.
mkdir -p registry-config && touch registry-config/config.yml docker-compose.registry.ymlversion: 0.1
log:
fields:
service: registry
level: info
storage:
cache:
blobdescriptor: inmemory
filesystem:
rootdirectory: /var/lib/registry
maintenance:
uploadpurging:
enabled: true
age: 168h
interval: 24h
http:
addr: :5000
headers:
X-Content-Type-Options: [nosniff]
health:
storagedriver:
enabled: true
interval: 10s
threshold: 3
proxy:
remoteurl: https://registry-1.docker.io
username: "${REGISTRY_PROXY_USERNAME}"
password: "${REGISTRY_PROXY_PASSWORD}"Never hardcode cleartext upstream Docker Hub tokens into `config.yml`. Use environment variable substitution in the registry binary or pass variables via Docker Compose / Kubernetes Secrets.
Pull-through caches operate as read-only proxies for clients. Direct `docker push` operations to a pull-through cache will fail with `unsupported: push access denied` unless configured as a standalone mirror.
Intent Matching & Trigger Invocation for Client Configuration
Invoke the agent using trigger phrases to generate the client daemon.json and compose runner.
Provide the agent with the exact trigger phrase 'setup docker pull through cache'. The skill directs the LLM to provide the client-side configuration changes needed for the local daemon to query the mirror before falling back to Docker Hub.
docker compose -f docker-compose.registry.yml up -d{
"registry-mirrors": ["http://10.0.0.50:5000"],
"insecure-registries": ["10.0.0.50:5000"],
"log-driver": "json-file",
"log-opts": {
"max-size": "50m",
"max-file": "3"
}
}Use the exact phrase 'setup docker pull through cache' to ensure the runtime maps directly to the frontmatter triggers, bypassing generic LLM web search queries.
Omitting `insecure-registries` when running plain HTTP will cause Docker daemon reload failures or `http: server gave HTTP response to HTTPS client` errors upon `docker pull`.
Verification, Linting & Safe Garbage Collection Gate
Execute dry-run garbage collection and configuration linting before promoting to production.
Garbage collection removes unreferenced layer blobs. However, running active mark-and-sweep while registry writes or layer pulls are occurring can lead to repository corruption. The skill forces the agent to output commands that switch storage to `readonly` mode or run a `--dry-run` inspection first.
docker exec -it registry registry garbage-collect --dry-run /etc/docker/registry/config.yml#!/usr/bin/env bash
set -euo pipefail
echo "Validating Registry Configuration..."
docker run --rm -v $(pwd)/registry-config/config.yml:/etc/docker/registry/config.yml:ro registry:2.8.3 registry -v
echo "Executing dry-run garbage collection..."
docker exec registry registry garbage-collect --dry-run /etc/docker/registry/config.yml
echo "Verification completed. No unreferenced blobs deleted without storage read-only lock."Automate scheduled garbage collection using an offline cron or maintenance container that spins up with a read-only bind-mount of the storage directory.
Never run `registry garbage-collect -m` on a live production instance with concurrent pushes or background pull-through population, as active manifest layers will be purged prematurely.
Real-World Scenario: Configure Docker Hub Pull-Through Mirror with S3 Backend and Client Configuration
“Claude Code, we are hitting Docker Hub rate limits in our CI runner fleet. setup docker pull through cache using Distribution Registry V2 backed by an S3 bucket in us-east-1, and configure our client daemon.json to use the mirror at https://docker-cache.internal:5000.”
Runtime Troubleshooting & Failure Modes
Root Cause: The Docker client attempts TLS handshake by default when querying endpoints listed under registry-mirrors. If the local mirror operates on plain HTTP without TLS certificates, the client aborts the connection.
Add the mirror to the insecure-registries list in /etc/docker/daemon.json:
{
"registry-mirrors": ["http://docker-cache.internal:5000"],
"insecure-registries": ["docker-cache.internal:5000"]
}
sudo systemctl restart dockerRoot Cause: Garbage collector is executed inside a container with mismatched user UID/GID permissions against host-mounted storage, or the storage path is mounted with a read-only host flag during write deletion phase.
Ensure the registry container runs with matching permissions or fix storage ownership:
sudo chown -R 1000:1000 /var/lib/registry
# Run garbage collection specifying the user
docker exec --user 1000:1000 registry registry garbage-collect /etc/docker/registry/config.ymlFrequently Asked Questions (Distribution Registry V2 & Pull-Through Caching SOP)
Q:Can I use Distribution Registry V2 & Pull-Through Caching across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill adheres to the open SKILL.md specification. By mounting the skill into `.agents/skills/registry-v2-distribution-mirror` or referencing it in your runtime agent configuration (`.cursor/rules` or Claude's agent settings), all compatible agents execute the same deterministic SOP without runtime conflicts.
Q:How does Distribution Registry V2 & Pull-Through Caching prevent context window overflow during long agent sessions?
The skill provides minimal, high-density declarative rules focused solely on configuration syntax, storage primitives, and garbage collection flags. By eliminating verbose prose, the agent ingests only critical YAML schemas and CLI commands, saving thousands of context tokens.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a security score of 98/100 (`fs_read: true`, `fs_write: workspace`, `shell_exec: false`). It enforces declarative configuration generation inside the workspace rather than allowing autonomous agents to execute unvetted privileged shell commands or manipulate the host Docker socket directly.
Ready to equip your autonomous agent with Distribution Registry V2 & Pull-Through Caching?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.