pubky

name	pubky
description	Use when building or debugging an application on Pubky with the web/server SDKs: signing users up to a homeserver, authenticating with keypairs and the pubkyauth flow (capabilities, relays, recovery files, signup tokens, sessions), reading/writing data over pubky:// URLs (put/get/list/delete with pagination), constructing and validating spec-compliant social objects (users, posts, tags, bookmarks, follows, feeds, files) with pubky-app-specs and its Timestamp/Blake3-Hash IDs and canonical /pub/pubky.app paths, or querying the Nexus social-graph REST API. Covers the JavaScript/WASM client (@synonymdev/pubky) and the Rust client (the pubky crate), pubky:// addressing, pkarr identity resolution, error handling, and local pubky-testnet development. NOT for native iOS/Android or React Native apps (use pubky-mobile) and NOT for running or self-hosting homeserver/Nexus/DNS infrastructure (use pubky-infra).
metadata	{"author":"pubky","version":"0.1.0"}

Pubky — build web & server apps

You are helping build a real application on the Pubky protocol with the web/server SDKs. Read this overview, then open the one reference file for the task at hand. Do not load every reference up front.

Ground rules (always apply)

• Use only documented functionality. Do not mock, simulate, or invent Pubky features. Every API used must exist in the references below or in their linked upstream sources.
• Respect Shipped vs Planned. Public /pub storage, capability-scoped sessions, PKARR discovery, app-specs, resumable auth flows, and event streams are shipped. Private storage roots (/priv), homeserver mirroring, backup restore, and cloud/two-way backup are NOT — never present them as available. See references/shipped-vs-planned.md.
• Public-key string formats matter. publicKey.toString() → pubky<z32> for display; publicKey.z32() → raw z-base-32 for hostnames, DNS names, headers, params, DB keys.
• Auth is SDK-driven. Use the pubkyauth flow; never ask users to paste keys or mnemonics. AuthTokens are valid for a ~3-minute window. See references/auth.md.
• Pre-1.0 churn is real. app-specs is v0.x and Nexus is /v0 — treat APIs as unstable and prefer linking upstream over hardcoding shapes.

Architecture in one screen

• Client SDK — @synonymdev/pubky (JS/WASM) or the pubky Rust crate. Auth + data ops. Prefer one shared client per app/process.
• Homeserver — the user's backend. App-facing API is file storage only: HTTP PUT/GET/DELETE against pubky://<pk>/pub/.... ~10 MB default per-request limit; expect 429.
• pkarr — public-key DNS over the Mainline DHT; resolves pubky:// to homeservers (consumed transparently via the SDK). Records are ephemeral; republished periodically.
• pubky-app-specs — validated data models + ID/path generation (the on-wire contract).
• Nexus — aggregator/indexer; a hosted read REST API (still /v0). Apps write to the homeserver and read social-graph data from Nexus.

URL forms: pubky<pk>/pub/<path> (SDK address) · pubky://<pk>/pub/<path> (deeplink) · /pub/<path> (signed-in session). Only /pub is protocol-required; the first segment under it is an app-chosen scope (e.g. /pub/pubky.app/*).

Where to look

Task	Read
Identity, pubky:// addressing, pkarr, homeserver model (shared spine)	references/concepts.md
The pubkyauth flow, capabilities, relays, recovery files, signup tokens, sessions	references/auth.md
Create/validate users, posts, tags, bookmarks, follows, feeds, files; IDs & paths	references/app-specs.md
JavaScript / WASM client — install, init, CRUD, pagination	references/sdk-js.md
Rust client (pubky crate) — usage, idioms	references/sdk-rust.md
Querying aggregated social data (the Nexus read API)	references/nexus-api.md
Local development with pubky-testnet; scripting with the CLI	references/testing-and-testnet.md
Worked reference apps and patterns (pubky.app, explorer, workshop)	references/reference-apps.md
Advanced: E2E messaging (pubky-noise), payments (paykit)	references/advanced-messaging-payments.md
What's shipped vs planned (guardrails)	references/shipped-vs-planned.md

Building a native mobile app (iOS/Android/React Native)? Use the pubky-mobile skill. Running or self-hosting a homeserver, Nexus, or DNS? Use the pubky-infra skill.