FAQ

How is HubProxy different from free CDN proxies?

HubProxy is fully self-hosted — you control data and bandwidth without relying on unstable third-party CDNs. Customize rate limits, registry allowlists, and upstream SOCKS5 proxies.

Is a reverse proxy required for public deployment?

Strongly recommended. It provides TLS, correct client IP passing, and avoids exposing port 5000. See Recommended Architecture.

What’s the difference between rate-limit and registry whitelists?

[security].whiteList exempts IPs from rate limiting. [access].whiteList controls which Docker images, GitHub repos, and Hugging Face resources can be proxied. They are independent.

How do I format GitHub acceleration URLs?

Prefix the full original URL with your HubProxy host, e.g. https://example.com/https://github.com/owner/repo/releases/download/.... Path-prefix rewrites like /github/owner/... are not supported. See GitHub Acceleration.

GitHub acceleration shows ‘invalid input’?

Common causes: wrong URL format (using /github/ prefix instead of full URL), or incorrect Nginx Host header. See GitHub Acceleration and issue #62.

How does the offline image API work?

Two steps: GET /api/image/download?image=...&mode=prepare for a token, then download with that token. There is no /v2/offline/... path. See Offline Images.

All users share one IP behind Cloudflare?

If HubProxy connects directly to Cloudflare edges, rate limits apply per Cloudflare IP, not per user. Add a private reverse proxy that writes CF-Connecting-IP to forwarding headers.

How do I verify the service is running?

Visit https://example.com/ready — a healthy response includes ready, service, version, and uptime_sec. This path counts toward the IP rate limit; avoid high-frequency polling.

Docker logs consuming too much disk?

docker run defaults to ~20MB logs. Docker Compose preconfigures 200m × 3 rotation; adjust logging.options in compose as needed.

Does HubProxy support resume or multi-part downloads?

GitHub / Hugging Face file downloads: yes. The proxy forwards Range headers and passes through upstream 206 responses — wget -c and multi-threaded Range downloads work (except .sh / .ps1 script rewriting).

Docker pulls: no in-layer Range. Blobs are streamed whole; clients retry failed layers or pull layers in parallel.

Offline tar API: no resume. See Transfer Capabilities.

How do I add a new acceleration domain?

Add a regex to githubExps in src/handlers/github.go. See Development & Build.

Why can’t I pull private images with authType github?

authType labels auth endpoints only — credential injection is not yet implemented. All registry pulls use anonymous auth and client Authorization headers are not forwarded. Private authenticated images cannot be pulled through HubProxy.