pulsys

KO | EN

gitlite — search

#nextjs #cpp #database #tailwindcss #github #mysql #markdown #golang #devops #awesome

(★ 9)

An open-source, authenticated pull-through cache for Hugging Face.

File Explorer

ZIP Download

- - bug_report.yml
  - config.yml
  - feature_request.yml
- - codeql.yml
  - dco.yml
  - dependency-review.yml
  - helm.yml
  - labels.yml
  - lint.yml
  - linux.yml
  - pages.yml
  - realhf.yml
  - release-please.yml
  - release.yml
  - scorecard.yml
  - security.yml
  - triage.yml
- CODEOWNERS
- dependabot.yml
- labeler.yml
- labels.yml
- pull_request_template.md
- .env.example
- .gitignore
- next-env.d.ts
- next.config.ts
- package-lock.json
- package.json
- playwright.config.ts
- README.md
- tsconfig.json
- - main.go
- - main.go
- - main.go
- - main.go
- - main.go
  - pprof.go
- - main.go
  - tenant_oidc.go
  - user.go
- - ct.yaml
  - lintconf.yaml
  - yamllint-rendered.yaml
- - Dockerfile
  - Dockerfile.goreleaser
- - pulsys-realm-prod.json
- - pulsys-realm.json
  - README.md
- - pulsys.conf
  - pulsys_proxy_headers.inc
- - init.sh
  - pulsys.sh
- Dockerfile
- architecture.md
- benchmarks.md
- internals.md
- oidc.md
- README.md
- security.md
- - cdk.json
  - package-lock.json
  - package.json
  - README.md
  - tsconfig.json
- - bench-ami.pkr.hcl
  - stock-ami.pkr.hcl
- - server.go
- - actor.go
  - csrf.go
  - csrf_test.go
  - middleware.go
  - middleware_test.go
  - pat_crypto_test.go
  - proxygate.go
  - proxygate_test.go
  - rbac.go
  - rbac_test.go
  - store.go
  - token.go
- - doc.go
  - local.go
  - local_test.go
  - store.go
- - backend.go
  - backend_test.go
  - bench_test.go
  - bodyhandle.go
  - checkpoint_test.go
  - inflight.go
  - inflight_ctx_test.go
  - key.go
  - key_test.go
  - key_xet_test.go
  - keyhex_cache.go
  - lru.go
  - lru_test.go
  - policy.go
  - store.go
  - store_purge_test.go
  - store_quota_test.go
  - store_test.go
  - stress_test.go
  - tier.go
  - zeroalloc_test.go
- - classify.go
  - classify_test.go
  - example_test.go
- - config.go
- - bridge.go
  - export_iouring_parser_linux_test.go
  - export_iouring_test.go
  - export_parser_test.go
  - floor_test.go
  - fuzz_parser_test.go
  - header_buf.go
  - iouring_linux.go
  - iouring_linux_test.go
  - iouring_other.go
  - iouring_parser_linux.go
  - iouring_reactor_linux.go
  - iouring_ring_linux.go
  - iouring_shutdown_linux_test.go
  - iouring_smuggling_corpus_linux_test.go
  - iouring_sndtimeo_linux_test.go
  - listener.go
  - parser_bench_test.go
  - parser_differential_test.go
  - parser_smuggling_corpus_test.go
  - parser_validator_oracle_test.go
  - sendfile_darwin.go
  - sendfile_darwin_test.go
  - sendfile_other.go
  - sendfile_unix.go
  - sendfile_unix_test.go
  - sendfile_with_header_other.go
  - server.go
  - server_test.go
  - slow_client_test.go
  - unsafe_alias.go
  - write_deadline.go
- - db.go
  - db_test.go
  - migrate.go
  - river_migrate.go
- - client.go
  - client_bench_test.go
  - client_test.go
- - hostallow.go
  - hostallow_test.go
- - args.go
  - errors.go
  - loopback.go
  - loopback_test.go
  - river_setup.go
  - river_worker.go
  - river_worker_test.go
  - worker.go
  - worker_pg_test.go
  - worker_test.go
- - humanize.go
  - humanize_test.go
- - hf_download_test.go
  - stub_test.go
- - logx.go
  - redact_test.go
  - sanitize_test.go
- - metrics.go
  - metrics_test.go
- - auth_enforcement_test.go
  - contention_test.go
  - forward_auth_test.go
  - handler.go
  - offline_test.go
  - parallel_range_test.go
  - proxy_test.go
  - redirect_range_pin_test.go
  - registry_handler.go
  - registry_handler_test.go
  - registry_range_fuzz_test.go
  - upload_handler.go
  - upload_handler_test.go
  - util.go
  - util_test.go
  - xet_e2e_test.go
  - xetlink_test.go
- - doc.go
  - real_hub_test.go
- - audit.go
  - doc.go
  - invariants_test.go
  - store.go
  - store_test.go
  - types.go
- - rewrite.go
  - rewrite_test.go
- - telemetry.go
- - container.go
  - doc.go
  - testpg.go
- - doc.go
  - harness.go
  - harness_test.go
  - leak_test.go
- - upstream.go
  - upstream_ssrf_test.go
- - pre-commit
- - ssm-common.sh
- attach-hf-data-volume.sh
- bench_compare.sh
- bench_db_up.sh
- bench_e2e.sh
- bench_footprint.sh
- bench_matrix.sh
- bench_saturate.sh
- bench_startup.sh
- bench_warm_parallel.sh
- bench_warm_saturate.sh
- bench_write_meta.sh
- build-stock-ami.sh
- build-tuned-ami.sh
- dingospeed-config.yaml
- e2e_models.json
- hf_download_bench.sh
- mount-hf-data-volume.sh
- profile_baseline.sh
- profile_summary.sh
- render_bench_matrix.go
- render_bench_matrix_extras.go
- render_bench_svg.go
- render_charts.sh
- render_hero_cast.sh
- render_saturate_charts.go
- run-aws-benchmarks.sh
- run_e2e_models.sh
- security-tests-entrypoint.sh
- security-tests-linux.sh
- smoke-pulsys.sh
- ssm-bench.sh
- ssm-hf-download.sh
- ssm-profile.sh
- ssm-shell.sh
- ssm-sweep.sh
- ssm-sync-scripts.sh
- ssm-tail-bench.sh
- ssm-teardown.sh
- sweep_tunings.sh
- update_claims.sh
- - apple-touch-icon.png
  - CNAME
  - favicon-1024.png
  - favicon-16.png
  - favicon-180.png
  - favicon-32.png
  - favicon-48.png
  - favicon-512.png
  - favicon.svg
  - github-avatar.png
  - llms.txt
  - logo.svg
  - og.png
  - robots.txt
- - render-brand.mjs
  - sync-benchmarks.mjs
  - sync-docs.mjs
  - sync-results.mjs
- - content.config.ts
  - env.d.ts
  - site.config.ts
- .gitignore
- astro.config.mjs
- package-lock.json
- package.json
- playwright.config.ts
- README.md
- tsconfig.json
.dockerignore
.gitignore
.gitmodules
.golangci.yml
.goreleaser.yaml
.release-please-manifest.json
.trivyignore
CHANGELOG.md
CODE_OF_CONDUCT.md
compose.yaml
CONTRIBUTING.md
DEVELOPMENT.md
docker-compose.security-tests.yml
Dockerfile.security-tests
go.mod
go.sum
LICENSE
llms.txt
NOTICE
osv-scanner.toml
README.md
release-please-config.json
ROADMAP.md
SECURITY.md
THIRD-PARTY-LICENSES.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

An authenticated pull-through cache for Hugging Face with a sendfile/io_uring
warm path.

[pulsys.io](https://pulsys.io) · [Docs](https://pulsys.io/docs) · [Blog](https://pulsys.io/blog)

[![CI](https://github.com/pulsys-io/pulsys/actions/workflows/linux.yml/badge.svg)](https://github.com/pulsys-io/pulsys/actions/workflows/linux.yml)
[![Go Reference](https://pkg.go.dev/badge/github.com/pulsys-io/pulsys.svg)](https://pkg.go.dev/github.com/pulsys-io/pulsys)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/pulsys-io/pulsys/badge)](https://securityscorecards.dev/viewer/?uri=github.com/pulsys-io/pulsys)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13603/badge)](https://www.bestpractices.dev/projects/13603)
[![SLSA 3](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev/spec/v1.0/levels)
[![Release](https://img.shields.io/github/v/release/pulsys-io/pulsys?sort=semver)](https://github.com/pulsys-io/pulsys/releases)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://raw.githubusercontent.com/pulsys-io/pulsys/main/LICENSE)

</div>

---

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`](docs/benchmarks.md).

## Quick start

Local full stack (builds from `docker/Dockerfile`: proxy, Postgres, Keycloak,
admin console):

```bash
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](http://localhost:3000/tokens).
Then point any Hugging Face client at the proxy:

```bash
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](https://kind.sigs.k8s.io/), Helm, and a Hugging Face read token.

```bash
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/`](deploy/charts/pulsys/).

## Documentation

Rendered docs: [pulsys.io/docs](https://pulsys.io/docs). Full index:
[`docs/`](docs/README.md). Common entry points:

| Topic | Doc |
|---|---|
| Build, test, code map | [`DEVELOPMENT.md`](DEVELOPMENT.md) |
| Benchmarks | [`docs/benchmarks.md`](docs/benchmarks.md) |
| Architecture | [`docs/architecture.md`](docs/architecture.md) |
| Security & threat model | [`docs/security.md`](docs/security.md) |
| Helm chart | [`deploy/charts/pulsys/`](deploy/charts/pulsys/) |
| Roadmap | [`ROADMAP.md`](ROADMAP.md) |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).
Commits are signed off under the [DCO](https://developercertificate.org/), PR
titles follow [Conventional Commits](https://www.conventionalcommits.org/), and
`go test -race`, `gofmt -s`, and `go vet` must pass.

## License

Licensed under the [Apache License 2.0](LICENSE). See [NOTICE](NOTICE) and
[THIRD-PARTY-LICENSES.md](THIRD-PARTY-LICENSES.md) for attribution and
dependency licenses.

pulsys

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README