Local Podman registry mirror management. Cache container images locally for faster pulls. Supports any registry (ghcr.io, docker.io, private). Use when users need to set up registry mirrors for faster container operations.
/plugin marketplace add atrawog/bazzite-ai-plugins/plugin install atrawog-bazzite-ai-bazzite-ai@atrawog/bazzite-ai-pluginsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
The mirror command manages local registry mirrors using Podman Quadlet containers. Mirrors cache container images locally for faster pulls.
Key Concept: Transparent caching - Podman is auto-configured to use mirrors. Pulls go through the local cache; cache misses fetch from upstream.
| Action | Command | Description |
|---|---|---|
| Install | ujust mirror install <REGISTRY> [PORT] [AUTH] | Install mirror |
| Remove | ujust mirror remove <REGISTRY> [DELETE_CACHE] | Remove mirror |
| List | ujust mirror list | List all mirrors |
| Status | ujust mirror status <REGISTRY> | Show mirror status |
| Enable | ujust mirror enable <REGISTRY> | Enable (start) mirror |
| Disable | ujust mirror disable <REGISTRY> | Disable (stop) mirror |
| Logs | ujust mirror logs <REGISTRY> [LINES] | View logs |
# GitHub Container Registry
ujust mirror install ghcr.io
# Docker Hub
ujust mirror install docker.io
# Quay.io
ujust mirror install quay.io
# NVIDIA NGC
ujust mirror install nvcr.io
# Private registry with auth
ujust mirror install registry.company.com 5000 user:password
# Custom port
ujust mirror install docker.io 5001
Each registry gets a unique port:
| Registry | Default Port |
|---|---|
| ghcr.io | 5000 |
| docker.io | 5001 |
| quay.io | 5002 |
| Custom | Specified |
# Stop without removing
ujust mirror disable ghcr.io
# Start again
ujust mirror enable ghcr.io
ujust mirror logs ghcr.io
ujust mirror logs docker.io 100
# Single mirror
ujust mirror status ghcr.io
# List all
ujust mirror list
Mirrors auto-configure Podman registries.conf. After install:
# Podman transparently uses mirror
podman pull ghcr.io/org/image:tag
# Actually pulls from localhost:5000 (cached)
| Item | Location |
|---|---|
| Cache data | ~/.local/share/containers/mirror/<registry>/ |
| Config | ~/.config/containers/registries.conf.d/ |
| Quadlet | ~/.config/containers/systemd/ |
# Install mirrors for common registries
ujust mirror install ghcr.io
ujust mirror install docker.io
# Verify
ujust mirror list
# Now pulls are cached
podman pull ghcr.io/org/image:tag # First: slow (cache miss)
podman pull ghcr.io/org/image:tag # Second: fast (cache hit)
# For GitHub runners
ujust mirror install ghcr.io
# Runners use cached images
# Significantly faster for repeated pulls
# With authentication
ujust mirror install registry.mycompany.com 5010 myuser:mypassword
# Verify
ujust mirror status registry.mycompany.com
# Remove but keep cache
ujust mirror remove ghcr.io
# Remove with cache cleanup
ujust mirror remove ghcr.io yes
Mirrors are especially useful for:
Large images (AI/ML containers)
Frequent rebuilds
Multiple developers
CI/CD pipelines
Check:
ujust mirror status ghcr.io
ujust mirror logs ghcr.io
Verify Podman config:
cat ~/.config/containers/registries.conf.d/ghcr.io-mirror.conf
Symptom: "Address already in use"
Fix:
# Use different port
ujust mirror remove ghcr.io
ujust mirror install ghcr.io 5100
Symptom: 401 errors in logs
Fix:
# Reinstall with correct credentials
ujust mirror remove registry.company.com
ujust mirror install registry.company.com 5000 correct:password
Check:
du -sh ~/.local/share/containers/mirror/
Fix:
# Remove and reinstall (clears cache)
ujust mirror remove ghcr.io yes
ujust mirror install ghcr.io
GitHub runners automatically use mirrors if configured:
# 1. Install mirror
ujust mirror install ghcr.io
# 2. Install runners
ujust runners install [https://github.com/org/repo](https://github.com/org/repo) 1
# Runners pull through mirror automatically
Related Skills: runners (uses mirrors), pod (image building)
Registry docs: https://docs.docker.com/registry/
Use when the user asks about:
"registry mirror", "cache container images"
"faster pulls", "slow container downloads"
"mirror ghcr", "mirror docker hub"
"CI optimization", "build faster"