Open source · Apache-2.0

Pull a model once. Serve the fleet from local disk.

Pulsys is an authenticated pull-through cache for Hugging Face. Point HF_ENDPOINT at it: the first request fills local disk; every later request is a warm hit. That is CI and GPU time you stop spending on the public internet.

Read the docsView on GitHub
$ export HF_ENDPOINT=http://localhost:8082
$ export HF_TOKEN=pulsys_...
$ hf download Qwen/Qwen2.5-7B-Instruct
Resolving data files...
Download complete
  • Apache-2.0
  • Docker Compose
  • Helm
  • SLSA 3
  • Self-hosted

Repeat downloads are the expensive part.

CI jobs and training nodes often re-pull the same weights on every run. A pull-through cache collapses that into one upstream fill and local-disk warm hits.

Measured warm path

  • 1.36Mreq/s @ 4 KiB (loopback)
  • 90 GB/sthroughput @ 16 MiB
  • c7i.12xlarge48 vCPU · saturate-iouring
  • io_uringLinux warm path
Request rate by payload (EC2 reference run)
EC2 saturation · req/s by payload
Throughput by payload (EC2 reference run)
EC2 saturation · GB/s by payload

Reference run: c7i.12xlarge, 48 vCPU, kernel 6.1.176-221.360.amzn2023.x86_64, variantsaturate-iouring. Generated 2026-07-13T21:16:33Z. Reproduce via thebenchmarks doc.

What changes when you put Pulsys in front

  • No client rewrites

    Set HF_ENDPOINT to Pulsys. huggingface_hub, transformers, datasets, and the hf CLI keep working.

  • One upstream fill

    The first miss streams from Hugging Face onto local disk. Later requests are served from cache.

  • Warm path at the kernel

    Warm hits use io_uring on Linux 6.1+ and sendfile on macOS. Reference EC2 run (1.36M req/s, 90 GB/s) and reproduction steps live in the benchmarks doc.

  • Authenticated by default

    Every request needs a pulsys_* API key from the admin console. Client credentials never reach Hugging Face.

  • Pre-warm before traffic

    Queue a repo in the console. A background job fills the cache so the fleet starts warm.

  • Offline after fill

    Strict-offline mode serves cached artifacts with zero upstream egress.

Where the cost shows up

  • CI fleets

    The same model on every job should not re-cross the public internet. Point HF_ENDPOINT at Pulsys and the second pull is local.

  • Training clusters

    Idle accelerators waiting on egress are the real price of a cold pull. Warm hits stream from local disk.

  • Air-gapped networks

    Pre-warm where there is connectivity, then serve the isolated network with no upstream dependency.

How it fits

First pull: from Hugging Face Hub. Every pull after: from disk.

Deploy with Docker Compose or Helm

export PULSYS_HF_TOKEN=hf_your_readonly_token
docker compose up --build
export HF_ENDPOINT=http://localhost:8082
export HF_TOKEN=pulsys_...
hf download Qwen/Qwen2.5-7B-Instruct
Read the docsStar on GitHub

FAQ

Which clients work?

Any client that speaks the Hugging Face Hub wire protocol. Set HF_ENDPOINT to Pulsys and use a pulsys_* API key as HF_TOKEN.

Where do credentials live?

Pulsys holds a read-only Hugging Face token (PULSYS_HF_TOKEN) for cache misses. Clients use Pulsys API keys from the admin UI. See the security doc.

Can instances share EFS or S3?

No. The warm path assumes local disk. Shared filesystems cap throughput below local disk.

How do I pre-warm the cache?

Pull through the proxy once, or queue an import from the admin console before traffic arrives.