How OpenWeights works
The internals: services, protocol, API reference, and configuration.
This section is for people changing OpenWeights, integrating with it directly, or auditing what it does with their bytes. If you want to upload and download models, start with Using OpenWeights.
Concepts
Architecture
The services, what each owns, and how a request moves between them.
Write path
From hf upload to a pinned xorb on Sia, request by request.
Read path
From hf download through reconstruction and signed URLs back to bytes.
Xet protocol
Chunks, xorbs, shards, hash encoding, and the dual-path routes.
Security model
Why the CAS is the only writer, and what protects each boundary.
Reference
CAS HTTP API
Every route on openweights-cas, with auth, scope, and status codes.
Gateway
Signed-URL verification, range serving, and the disk cache.
hf-proxy
The one-header rewrite that routes huggingface.co uploads to Sia.
Configuration
Every environment variable each service reads, with defaults.
Database
The Postgres schema, the two roles, and the migrations.
Working on OpenWeights
Local development
Build and run each service from source.
Testing
The test suites, the conformance harness, and what CI runs.
Deployment
Compose overlays, Caddy, and the published images.
Repository layout
The git root holds one directory per service plus the supporting harnesses.
| Path | Contents |
|---|---|
cas/ | openweights-cas, a six-crate Rust Cargo workspace, plus migrations/ |
gateway/ | openweights-gateway, a single flat Go package |
console/ | openweights-console, a Vite and React application |
hf-proxy/ | openweights-hf-proxy, a single-file Go reverse proxy |
conformance/ | The Rust Xet-protocol conformance harness |
bench/ | Go module holding the setup wizard and the measurement harnesses |
ops/ | Compose files, overlays, the Caddyfiles, and operator scripts |
tests/hf-roundtrip/ | The end-to-end byte-identical round-trip harness |
docs-site/ | This documentation site |
The Rust workspace splits into openweights-cas (the Axum binary),
openweights-cas-core (every handler), openweights-cas-storage (the Sia write
path and reconciler), openweights-cas-db (sqlx queries and types),
openweights-cas-proto (the only place xet-core-structures is re-exported),
and openweights-cas-register (the one-shot indexer registration CLI).