pulsys-io/pulsys
An open-source, authenticated pull-through cache for Hugging Face. - pulsys-io/pulsys
1 stars · 0 forks · Go
README
Pulsys An authenticated pull-through cache for Hugging Face with a sendfile/io_uring warm path. pulsys.io · Docs · Blog
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 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 Install the chart from this repo. Release images are published to ghcr.io/pulsys-io/pulsys: kubectl create secret generic pulsys-hf --from-literal=token=hf_your_readonly_token
helm install pulsys deploy/charts/pulsys \ --set proxy.publicBaseURL=https://hf.example.com \ --set postgres.host=postgres.db.svc \ --set admin.imports.hfTokenSecret=pulsys-hf \ --set persistence.size=200Gi To build the image yourself instead: docker build -t pulsys:local -f deploy/docker/Dockerfile ., then set image.repository / image.tag accordingly. Pulsys runs as a single proxy instance backed by an external PostgreSQL. Multi-node clustering is on the roadmap.
Chart values: deploy/charts/pulsys/ SSO setup: docs/oidc.md Hardening: docs/security.md
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.