An authenticated pull-through cache for Hugging Face with a sendfile/io_uring warm path.
Pulsys is an authenticated pull-through cache for the Hugging Face Hub. Point
Hugging Face clients at it with HF_ENDPOINT: the first pull of a model fills a
local disk cache, and every pull after that is served from disk with no upstream
egress.
Warm hits use io_uring on Linux 6.1+ and sendfile on macOS.
On a 48-vCPU c7i.12xlarge it sustains 1.36M req/s at 4 KiB and 90 GB/s
at 16 MiB.
See docs/benchmarks.md.
Quick start
Local full stack (builds from docker/Dockerfile: proxy, Postgres, Keycloak,
admin console):
git clone --recurse-submodules https://github.com/pulsys-io/pulsys.git cd pulsys export PULSYS_HF_TOKEN=hf_your_readonly_token docker compose up --build
Open the admin console at http://localhost:3000 (admin@pulsys.local / admin)
and create an API key at http://localhost:3000/tokens.
Then point any Hugging Face client at the proxy:
export HF_ENDPOINT=http://localhost:8082 export HF_TOKEN=pulsys_... # the API key you just created hf download Qwen/Qwen2.5-0.5B # first run fills the cache; next run is served from disk
huggingface_hub, transformers, datasets, the hf CLI, and hf_transfer
work unchanged.
Deploy
Pulls ghcr.io/pulsys-io/pulsys:latest and
ghcr.io/pulsys-io/pulsys-console:latest. Needs
Kind, Helm, and a Hugging Face read token.
export PULSYS_HF_TOKEN=hf_your_readonly_token kind create cluster --name pulsys kubectl apply --server-side -f \ https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.24/releases/cnpg-1.24.1.yaml kubectl -n cnpg-system rollout status deploy/cnpg-controller-manager --timeout=5m kubectl apply -f deploy/charts/pulsys/examples/cnpg-cluster-kind.yaml kubectl wait --for=condition=Ready cluster/pulsys-pg --timeout=5m kubectl create secret generic pulsys-hf --from-literal=token="$PULSYS_HF_TOKEN" helm upgrade --install pulsys deploy/charts/pulsys \ -f deploy/charts/pulsys/examples/values-kind.yaml kubectl wait --for=condition=available --timeout=5m \ deploy/pulsys deploy/pulsys-console deploy/pulsys-keycloak kubectl port-forward svc/pulsys-console 3000:80 & kubectl port-forward svc/pulsys-keycloak 8081:8080 & kubectl port-forward svc/pulsys 8082:8080 &
Open http://localhost:3000 — admin@pulsys.local / admin.
Proxy: http://localhost:8082.
More chart options: deploy/charts/pulsys/.
Documentation
Rendered docs: pulsys.io/docs. Full index:
docs/. Common entry points:
| Topic | Doc |
|---|---|
| Build, test, code map | DEVELOPMENT.md |
| Benchmarks | docs/benchmarks.md |
| Architecture | docs/architecture.md |
| Security & threat model | docs/security.md |
| Helm chart | deploy/charts/pulsys/ |
| Roadmap | ROADMAP.md |
Contributing
See CONTRIBUTING.md and the Code of Conduct.
Commits are signed off under the DCO, PR
titles follow Conventional Commits, and
go test -race, gofmt -s, and go vet must pass.
License
Licensed under the Apache License 2.0. See NOTICE and THIRD-PARTY-LICENSES.md for attribution and dependency licenses.