Pulsys

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 ([email protected] / 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 — [email protected] / 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.

rothgar/pulsys

README