Wisp.place Documentation
Decentralized static site hosting on the AT Protocol.
Wisp.place enables you to host static websites directly in your AT Protocol repository. Your Personal Data Server (PDS) holds the cryptographically signed manifest and files as the authoritative source of truth, while hosting services index and serve them with CDN-like performance.
Quick Start
Section titled “Quick Start”Using the Web Interface
Section titled “Using the Web Interface”Visit https://wisp.place and sign in with your AT Protocol account to deploy sites through the browser.
Using the CLI
Section titled “Using the CLI”# Download the CLI binary for your platformcurl -L https://sites.wisp.place/nekomimi.pet/wisp-cli-binaries/wisp-cli-x86_64-linux -o wisp-clichmod +x wisp-cli
# Deploy your site./wisp-cli your-handle.bsky.social --path ./my-site --site my-siteYour site will be available at:
https://sites.wisp.place/{your-did}/{site-name}Key Features
Section titled “Key Features”Decentralized Storage
Section titled “Decentralized Storage”- Sites stored as
place.wisp.fsrecords in your AT Protocol repo - Cryptographically verifiable ownership
- Your PDS is the source of truth
- Portable across hosting providers
Custom Domains
Section titled “Custom Domains”- Point your own domain to your Wisp site
- DNS verification ensures secure ownership
- Automatic SSL/TLS certificates
URL Redirects & Rewrites
Section titled “URL Redirects & Rewrites”- Netlify-style
_redirectsfile support - Single-page app (SPA) routing
- API proxying and conditional routing
- Custom 404 pages
Efficient Deployment
Section titled “Efficient Deployment”- Incremental updates: Only upload changed files
- Smart compression: Automatic gzip for text files
- Large site support: Automatic splitting into subfs records for sites with 250+ files to get around 150KB record size limit
- Blob reuse: Content-addressed storage prevents duplicate uploads
How It Works
Section titled “How It Works”The deployment process starts when you upload your files. Each file is compressed with gzip, base64-encoded, and uploaded as a blob to your PDS. A place.wisp.fs record then stores the complete site structure with references to these blobs, creating a verifiable manifest of your site.
The firehose service continuously watches the AT Protocol firehose for new and updated sites. When a site is created or updated, it downloads the manifest and blobs from the PDS, writes them to S3 (or disk), and publishes a cache invalidation event via Redis. The hosting service is a read-only CDN that serves files from a three-tier cache (memory, disk, S3). When a file isn’t in cache, the hosting service fetches it on-demand from the PDS and promotes it through the tiers.
Custom domains work through DNS verification, allowing your site to be served from your own domain while maintaining the cryptographic guarantees of the AT Protocol.
Architecture Overview
Section titled “Architecture Overview” ┌──────────────┐ ┌──────────────┐ │ wisp-cli │ │ wisp.place │ │ (Rust Binary)│ │ Website │ │ │ │ (React UI) │ └──────────────┘ └──────────────┘ │ │ ▼ ▼┌─────────────────────────────────────────────────────────┐│ AT Protocol PDS ││ (Authoritative Source - Cryptographically Signed) ││ ││ ┌──────────────────────────────────────────────┐ ││ │ place.wisp.fs record │ ││ │ - Site manifest (directory tree) │ ││ │ - Blob references (CID-based) │ ││ │ - Metadata (file count, timestamps) │ ││ └──────────────────────────────────────────────┘ ││ ││ ┌──────────────────────────────────────────────┐ ││ │ Blobs (gzipped + base64 encoded) │ ││ │ - index.html, styles.css, assets/* │ ││ └──────────────────────────────────────────────┘ │└─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ AT Protocol Firehose │ │ (Jetstream WebSocket Stream) │ └─────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────┐│ Firehose Service (Write Path) ││ ││ - Watches firehose for place.wisp.fs changes ││ - Downloads blobs from PDS ││ - Writes cached files to S3 / disk ││ - Publishes cache invalidation via Redis │└─────────────────────────────────────────────────────────┘ │ │ │ (S3 / Disk) │ (Redis pub/sub) ▼ ▼┌─────────────────────────────────────────────────────────┐│ Hosting Service (Read Path) ││ ││ ┌──────────────────────────────────────────────┐ ││ │ Tiered Storage │ ││ │ ┌──────┐ ┌──────┐ ┌──────────────┐ │ ││ │ │ Hot │ → │ Warm │ → │ Cold │ │ ││ │ │(Mem) │ │(Disk)│ │(S3/Disk) │ │ ││ │ └──────┘ └──────┘ └──────────────┘ │ ││ │ On miss: fetch from PDS and promote up │ ││ └──────────────────────────────────────────────┘ ││ ││ ┌──────────────────────────────────────────────┐ ││ │ Routing & Serving │ ││ │ - Custom domains (example.com) │ ││ │ - Subdomains (alice.wisp.place) │ ││ │ - Direct URLs (sites.wisp.place/did/site) │ ││ └──────────────────────────────────────────────┘ │└─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────┐ │ Browser │ └─────────────┘For a detailed breakdown of the services and storage system, see the Architecture Guide.
Tech Stack
Section titled “Tech Stack”- Backend: Bun + Elysia + PostgreSQL
- Frontend: React 19 + Tailwind 4 + Radix UI
- Hosting Service: Node.js + Hono
- Firehose Service: Bun
- CLI: Rust + Jacquard (AT Protocol library)
- Protocol: AT Protocol OAuth + custom lexicons
- Storage: S3-compatible (Cloudflare R2, MinIO, etc.) + Redis for cache invalidation
Limits
Section titled “Limits”- Max file size: 100MB per file (PDS limit)
- Max files: 1000 files per site
- Max total size: 300MB per site (compressed)
Files are automatically compressed with gzip before upload, so actual limits may be higher depending on your content compressibility.
Getting Started
Section titled “Getting Started”- CLI Documentation - Deploy sites from the command line
- Architecture Guide - How hosting, firehose, and tiered storage work
- Self-Hosting Guide - Deploy your own instance
- Lexicons - AT Protocol record schemas and data structures
- Website: https://wisp.place
- Repository: https://tangled.org/@nekomimi.pet/wisp.place-monorepo
- AT Protocol: https://atproto.com
- Jacquard Library: https://tangled.org/@nonbinary.computer/jacquard
License
Section titled “License”MIT License - See the repository for details.