This is the full developer documentation for Pubky Documentation # > Key-based, self-regulating web that puts users in control. Oct 07 Wednesday 16:00 UTC You’re invited ## Pubky Community Call #4 SDK updates, AI tools, app features, and self-hosting on Umbrel. [Join the call  ](https://meet.google.com/xny-ztvd-zyk)[Read the announcement](https://pubky.app/post/ihaqcthsdbk751sxctk849bdr7yz7a934qen5gmpcbwcur49i97y/0035REMNNEZ1G) # Build for User Sovereignty Open protocol for key-based, censorship-resistant apps [ GitHub ](https://github.com/pubky/pubky-homeserver)[ Human Docs](/overview/) pubky.org for your LLM [](https://claude.ai/new?q=Help%20me%20explore%20Pubky.%20Start%20at%20https%3A%2F%2Fpubky.org%2Fllms.txt%20and%20use%20the%20linked%20index%20or%20full%20documentation%20as%20needed.%0A%0AAsk%20what%20I%E2%80%99d%20like%20to%20know%20or%20do.%20Follow%20my%20interests.%0A%0ACite%20sources%20and%20flag%20anything%20you%20cannot%20verify%20or%20access.%0A%0AIf%20we%20write%20code%2C%20confirm%20my%20language%20or%20framework%20and%20SDK%20version%2C%20then%20check%20the%20corresponding%20SDK%20documentation.)[](https://chat.openai.com/?q=Help%20me%20explore%20Pubky.%20Start%20at%20https%3A%2F%2Fpubky.org%2Fllms.txt%20and%20use%20the%20linked%20index%20or%20full%20documentation%20as%20needed.%0A%0AAsk%20what%20I%E2%80%99d%20like%20to%20know%20or%20do.%20Follow%20my%20interests.%0A%0ACite%20sources%20and%20flag%20anything%20you%20cannot%20verify%20or%20access.%0A%0AIf%20we%20write%20code%2C%20confirm%20my%20language%20or%20framework%20and%20SDK%20version%2C%20then%20check%20the%20corresponding%20SDK%20documentation.)[](https://cursor.com/link/prompt?text=Help%20me%20explore%20Pubky.%20Start%20at%20https%3A%2F%2Fpubky.org%2Fllms.txt%20and%20use%20the%20linked%20index%20or%20full%20documentation%20as%20needed.%0A%0AAsk%20what%20I%E2%80%99d%20like%20to%20know%20or%20do.%20Follow%20my%20interests.%0A%0ACite%20sources%20and%20flag%20anything%20you%20cannot%20verify%20or%20access.%0A%0AIf%20we%20write%20code%2C%20confirm%20my%20language%20or%20framework%20and%20SDK%20version%2C%20then%20check%20the%20corresponding%20SDK%20documentation.)[](https://gemini.google.com/)[](https://x.com/i/grok?text=Help%20me%20explore%20Pubky.%20Start%20at%20https%3A%2F%2Fpubky.org%2Fllms.txt%20and%20use%20the%20linked%20index%20or%20full%20documentation%20as%20needed.%0A%0AAsk%20what%20I%E2%80%99d%20like%20to%20know%20or%20do.%20Follow%20my%20interests.%0A%0ACite%20sources%20and%20flag%20anything%20you%20cannot%20verify%20or%20access.%0A%0AIf%20we%20write%20code%2C%20confirm%20my%20language%20or%20framework%20and%20SDK%20version%2C%20then%20check%20the%20corresponding%20SDK%20documentation.)Prompt  Show starter prompt ``` Help me explore Pubky. Start at https://pubky.org/llms.txt and use the linked index or full documentation as needed. Ask what I’d like to know or do. Follow my interests. Cite sources and flag anything you cannot verify or access. If we write code, confirm my language or framework and SDK version, then check the corresponding SDK documentation. ``` * npm $ npm install @synonymdev/pubky  * RN $ npm install @synonymdev/react-native-pubky  * Rust $ cargo add pubky  AI [**Agent skills** Pubky workflows for your LLM coding agents](https://github.com/pubky/agent-skills) [**Context7** API documentation and examples.](https://context7.com/?q=pubky) [Homeserver](https://context7.com/pubky/pubky-homeserver) [PKARR](https://context7.com/pubky/pkarr) [**DeepWiki** AI explanations of the Pubky codebase.](https://deepwiki.com/pubky/pubky-homeserver) ## [Quick Start](#quick-start) [](/developer-guide/) ### [Build an app](/developer-guide/) [Read and write your first Homeserver record with the Developer Guide.](/developer-guide/) [](/developer-guide/) [](/overview/) ### [Understand Pubky](/overview/) [Learn what Pubky is, how it works, and why it exists.](/overview/) [](/overview/) [](/getting-started/) ### [Try Pubky](/getting-started/) [Create your identity, join pubky.app, and explore your data.](/getting-started/) [](/getting-started/) [](/glossary/) ### [Glossary](/glossary/) [Look up terms used throughout the docs.](/glossary/) [](/glossary/) ## [Development](/#for-developers)  ### Build an app Choose an architecture and connect your app to Pubky. [SDK ](/sdk/)[App architectures ](/app-architectures/)[Authentication ](/authentication/)[App templates](https://pubky.github.io/pubky-app-templates/)  ### Shared social data Build apps that use shared records, tags, and social connections. [pubky-app-specs ](/pubky-app-specs/)[Indexing ](/indexing-and-aggregation/)[Nexus ](/pubky-nexus/)[Social graph](/semantic-social-graph/)  ### Development tools Run a local testnet, inspect data, and find project references. [Docker ](/pubky-docker/)[Explorer ](/pubky-explorer/)[Resources](/resources/) [Contributing](/contributing/) ## [For Users](#for-users)  ###  Pubky [Join pubky.app ](https://pubky.app)[Learn More](/pubky-app/)  ###  Pubky Ring [Website ](https://pubkyring.app/)[Learn More](/pubky-ring/)  ###  Pubky Passport [Open ](https://passport.pubky.app/)[Learn More](/pubky-passport/) ## [Key concepts](#key-concepts) [](/pkdns/) ### [PKDNS](/pkdns/) [Resolve public-key domains through DNS.](/pkdns/) [](/pkdns/) [](/architecture/) ### [System Architecture](/architecture/) [See how identity, discovery, storage, and applications fit together.](/architecture/) [](/architecture/) [](/semantic-social-graph/) ### [Semantic Social Graph](/semantic-social-graph/) [Explore labeled connections between people and content.](/semantic-social-graph/) [](/semantic-social-graph/) [](/credible-exit/) ### [Credible Exit](/credible-exit/) [Keep your identity, data, and connections when leaving a service.](/credible-exit/) [](/credible-exit/) ## [Demos](#demos) Try some proof of concepts built on the Pubky protocol. What will you create? ### App Template Copy this Pubky app template to start your own app. It includes authentication, file storage, event stream subscriptions, and mainnet and local testnet builds. [Demo ](https://pubky.github.io/pubky-app-templates/)[GitHub](https://github.com/pubky/pubky-app-templates) ### Loopky A modern mobile flashcard app with spaced repetition, social discovery, and user-owned data on Pubky. [Website ](https://loopky.app)[GitHub](https://github.com/jvsena42/loopky) ### mypubky A shareable identity card that brings your Pubky identifier, avatar, bio, links, posts, profile tags, and Paykit-powered donation options into one visual page. [Demo ](https://mypubky.com/)[GitHub ](https://github.com/pubky/mypubky)[Blog](https://medium.com/pubky/mypubky-a-portable-link-in-bio-built-on-pubky-identity-c15169ae744a) ### Payky A linktree like page for payments, based on Paykit, where the user can connect using Pubky Ring and add their payment details (crypto, fiat etc.) and share a link to the page with anyone. [Demo ](https://payky.app/)[Blog](https://medium.com/pubky/payky-a-universal-pay-page-built-on-pubky-identity-756d08a64cc4) ### ABC Drop-In Pubky Comment Widget for Blogs Simple embeddable script that lets any website add Pubky-based comments. [Demo ](https://ok300.github.io/abc-prague-hugo/posts/abc-launch/)[GitHub](https://github.com/aintnostressin/abc-team-hackathon-prague) ### Mapky A social layer for OpenStreetMap with place reviews, posts, routes, collections, and geo-captures stored as user-owned data. [Demo ](https://mapky.app/)[GitHub](https://github.com/gillohner/mapky-app) ### Explorer A file explorer that allows you to navigate data stored on your Homeserver. [Demo ](https://explorer.pubky.app/)[GitHub](https://github.com/pubky/pubky-explorer) ### Eventky A social calendar and event management app using existing calendar standards, with event data stored on each user’s homeserver. [Demo ](https://eventky.app/)[GitHub](https://github.com/gillohner/eventky) ### Uploadky File sharing with files stored on your Pubky homeserver. [Demo ](https://uploadky.vercel.app/)[GitHub](https://github.com/PastaGringo/uploadky) ### TC Wiki TimechainWiki is a Bitcoin encyclopedia with reader annotations synced through Nostr or Pubky. [Demo ](https://timechain.wiki/)[GitHub](https://github.com/RadVladdy/timechain-wiki) ### PKDNS A DNS server providing self-sovereign and censorship-resistant domain names based on PKARR. [Demo ](https://pkdns.net/)[GitHub](https://github.com/pubky/pkdns) ### PubkyLab An interactive web-based playground for testing and experimenting with the Pubky SDK. [Demo ](https://jvsena42.github.io/pubky-lab/)[GitHub ](https://github.com/jvsena42/pubky-lab)[Blog](https://medium.com/pubky/pubky-lab-a-simple-playground-for-testing-pubky-sdk-calls-3294a3186607) ### No Registry Self-host PKDNS in under 10 minutes with a simple Pi-hole or Docker setup. [Website ](https://www.noregistry.com/)[Blog](https://medium.com/pubky/no-registry-a-marketing-push-for-pkdns-4e6d6fae58e4) ## [Join our Community](#community) * [Join Pubky.app Try the decentralized social media app. ](https://pubky.app) * [Telegram Join the community chat. ](https://t.me/pubkycore) * [GitHub Source code and repositories. ](https://github.com/pubky) [ ](https://synonym.to)[](https://tether.io) # Indexing & Aggregation Homeservers store records under individual users’ identities. A social feed needs to connect those records: which posts were written by people you follow, which replies belong to a conversation, or which resources carry a particular tag. An application backend can collect public records from multiple [Homeservers](/homeserver/) and make those queries available: * **Aggregation** collects the records the service chooses to include. * **Indexing** organizes those records for queries such as feeds and search. * **An API** exposes the resulting views to clients. These are responsibilities, not a required set of separate services. [Pubky Nexus](/pubky-nexus/) implements them for pubky.app social data. The resulting index is a derived view. It does not replace the original Homeserver records, and an instance only returns data within its indexing coverage and policies. Different services can build different views over the same published data. See [App Architectures](/app-architectures/) to decide whether your application needs a backend. # App Architectures Pubky applications use the [Pubky protocol](/overview/) for identity and data storage. Users publish records to their Homeservers; apps choose how to read them according to the queries they need. Writing a user’s records still goes through their Homeserver, whichever read approach the app uses. Apps can define their own schemas and backends, or reuse [pubky.app](/pubky-app/)’s profiles, posts, tags, and relationships through [pubky-app-specs](/pubky-app-specs/) without recreating its social interface. | Approach | When it helps | What the application needs to handle | | -------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | Client to Homeserver | The app knows which users and paths it needs, such as a personal bookmark tool. | Fetching and presenting those records through the [SDK](/sdk/). | | Custom backend | The app needs search, feeds, or relationships across many users. | Collecting relevant records, maintaining indexes, and serving queries. | | Shared aggregator | Several clients need the same indexed data. | Choosing a service whose coverage and filtering policies suit the app. | ## Choosing a starting point [Section titled “Choosing a starting point”](#choosing-a-starting-point) Direct access is enough for the [Developer Guide](/developer-guide/): the app writes a record and knows where to read it. A feed across many users needs more work. Fetching every user’s records in the browser can become expensive, and the client still needs to discover which records matter. An [indexing service](/indexing-and-aggregation/) can collect those records once and serve queries to many clients. [Pubky Nexus](/pubky-nexus/) supplies this for the shared social data model. If your app uses different data or needs different queries, a custom backend can index just what it needs. These approaches can be combined. An app might read a known file directly from a Homeserver and use an indexer to find related content. It can also keep a local cache for responsive browsing, as the [pubky.app reference architecture](/pubky-app/#reference-architecture) demonstrates. An indexer’s results reflect its coverage and policies, and updates take time to reach its indexes. Decide whether that suits each screen in your app, particularly immediately after a user publishes a change. # System Architecture This page provides a comprehensive overview of the Pubky ecosystem architecture, showing how all components work together to enable decentralized, censorship-resistant applications. *** ## System Architecture [Section titled “System Architecture”](#system-architecture) *** ## Layer Breakdown [Section titled “Layer Breakdown”](#layer-breakdown) ### Identity Layer [Section titled “Identity Layer”](#identity-layer) The foundation of Pubky is cryptographic identity based on **[key pairs](/security-model/#key-custody)**. **Components:** * **[Pubky Ring](/pubky-ring/)**: Mobile app for secure key management * **Key Pairs**: Ed25519 public/private key pairs * **Recovery Files**: Encrypted backups for key recovery **How It Works:** 1. User generates a key pair (public + private key) 2. Public key becomes permanent identity (z-base-32 encoded) 3. Private key stays secure on device, used for signing 4. Recovery file enables backup and cross-device usage **Key Properties:** * ✅ Self-sovereign (no registration with authorities) * ✅ Portable across devices * ✅ Permanent (never changes) * ✅ Cryptographically secure *** ### Discovery Layer [Section titled “Discovery Layer”](#discovery-layer) The discovery layer enables finding Homeservers and resolving identities without central servers. **Components:** * **[PKARR](/pkarr/)**: Public Key Addressable Resource Records * **[Mainline DHT](/mainline-dht/)**: Distributed Hash Table (10M+ nodes) * **[PKDNS](/pkdns/)**: DNS servers for resolving public-key domains **How It Works:** **Key Features:** * Decentralized discovery (no central directory) * Censorship resistant (15+ years proven infrastructure) * Self-published (users control their records) * Updateable (switch Homeservers anytime) *** ### Storage Layer [Section titled “Storage Layer”](#storage-layer) **[Homeservers](/homeserver/)** store user data in a filesystem over a simple HTTP API, similar to WebDAV. **Architecture:** **Key Properties:** * **User Choice**: Pick any Homeserver or run your own * **Data Ownership**: You control your data * **Portability**: Switch Homeservers without losing data * **Storage layout**: Files for user data; PostgreSQL for the Homeserver’s internal metadata Applications manage user files through the [SDK](/sdk/). For direct HTTP integrations, use the [client OpenAPI specification](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-homeserver/openapi-client.yml). *** ### Application Layer [Section titled “Application Layer”](#application-layer) Applications consume data from Homeservers, either directly or through aggregation services. **Architecture Patterns:** #### 1. Simple Client-Homeserver [Section titled “1. Simple Client-Homeserver”](#1-simple-client-homeserver) **Use Case**: Personal apps, simple tools, direct data access #### 2. Global Aggregator [Section titled “2. Global Aggregator”](#2-global-aggregator) **Use Case**: Social feeds, search, discovery (e.g., [Pubky Nexus](/pubky-nexus/)) #### 3. Custom Backend [Section titled “3. Custom Backend”](#3-custom-backend) **Use Case**: Advanced features, recommendations, specialized processing *** ## Data Flow Example: Publishing a Post [Section titled “Data Flow Example: Publishing a Post”](#data-flow-example-publishing-a-post) # Authentication Pubky apps request scoped access to a user’s Homeserver through grant authentication. A key manager such as [Pubky Ring](/pubky-ring/) lets the user approve the request without giving the app their identity key. ## From approval to a session [Section titled “From approval to a session”](#from-approval-to-a-session) An application asks for the permissions its features need, such as reading and writing files in its own storage path. It presents an authorization link or QR code. The user reviews the request in their authenticator, which approves access and delivers an encrypted grant through an [HTTP Relay](/http-relay/). The SDK turns that approval into a session the app can use for authenticated requests. The app’s session is distinct from the identity key. Its permissions limit what it can access on the Homeserver, and grants can be revoked. Reading someone else’s public data does not require their approval; writing data or accessing authenticated storage does. The [Security Model](/security-model/) explains these boundaries. Review requested scopes before approving an app. Root grants carry account-level privileges and should be reserved for trusted account-management tools. ## Signing out [Section titled “Signing out”](#signing-out) Signing out an active grant-backed session through the SDK revokes its grant. Revocation invalidates every session issued from that grant and prevents saved credentials for it from restoring access. Separate grants, including those issued to the same app, are unaffected. Removing saved browser session data only forgets it locally; it does not revoke the grant on the Homeserver. If the session token is no longer valid, SDK sign-out can report success without revoking the grant. ## Implement the flow [Section titled “Implement the flow”](#implement-the-flow) Use the SDK guides to implement this flow: * [JavaScript grant authentication](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-sdk/bindings/js/pkg/README.md#grantauthflow-pubkyauth). * [Rust QR authentication](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-sdk/README.md#pubky-qr-auth-for-third-party-and-keyless-apps). * [Browser session persistence example](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/examples/javascript/5-browser-session-persistence/README.md). For raw endpoints, see the [Homeserver API references](/homeserver/#http-api). For key custody and Homeserver trust, read the [Security Model](/security-model/). # Censorship **Censorship** is the suppression or control of speech, communication, or information by a governing body or authority, often resulting in a lack of free expression and limited user autonomy. Imagine you’ve been using a social platform to share your thoughts and connect with others. One day, you notice that your posts are disappearing or are no longer visible to your friends. Your reach is being reduced, and your voice is being silenced. This is an example of **censorship** at play—when someone else decides what you can and cannot say online, and what others can and cannot see. ## Why Censorship is Inevitable [Section titled “Why Censorship is Inevitable”](#why-censorship-is-inevitable) Censorship is inevitable in today’s web because many popular services, like social platforms, require centralized hosting. These platforms need servers to store data, deliver content, and provide other services. As long as centralized servers are involved, someone—be it the server owner, government authority, or a corporate entity—can decide what content is allowed and what is not. The reality is that many centralized platforms serve millions of users, which makes them natural targets for censorship. Server operators can be pressured to comply with local laws or corporate policies, meaning that user content can be restricted, removed, or filtered at any time. However, this doesn’t mean we should accept censorship without a solution. Instead, we need systems that **assume censorship is likely** and empower users to navigate around it. ## How Pubky Addresses Censorship [Section titled “How Pubky Addresses Censorship”](#how-pubky-addresses-censorship) In **Pubky**, the approach is not to eliminate censorship entirely—because some level of censorship will always exist where there are centralized components—but rather to provide users with a way to **circumvent** it when it happens. * **Flexible Hosting**: Pubky provides a flexible hosting model using trusted servers known as [Homeservers](/homeserver/). While these servers may be subject to censorship, Pubky ensures that users have the ability to migrate away from a censoring server whenever needed. Users keep their identities and connections when they move, and can re-upload their data to another Homeserver, meaning they retain control even in the face of censorship. * **Decentralized Identity**: In Pubky, user identities are not dependent on any single server. By using **self-issued public keys**, users maintain their identity even if they change hosting providers. This prevents identity loss when moving away from a server that engages in censorship. * **Data Portability and Redundancy**: Pubky makes user data portable by storing it in simple Homeserver paths and by supporting local copies through [Pubky Backup](/pubky-backup/). Full Homeserver mirroring and seamless failover are still planned work. ## Important Aspects of Censorship Resistance [Section titled “Important Aspects of Censorship Resistance”](#important-aspects-of-censorship-resistance) * **Data Control**: Users should always have access to and control over their data, even if one hosting provider chooses to censor it. Pubky’s approach empowers users by ensuring they are not dependent on any one server. * **Migration and Interoperability**: The ability to migrate data, identities, and connections between different [Homeservers](/homeserver/) helps users remain resilient against censorship. Interoperable systems mean that even if one provider blocks content, another can provide access. * **Local Copies and Self-Hosting**: Users can keep local copies of their published data with [Pubky Backup](/pubky-backup/), and independent Homeserver operation gives users more control over where their information lives. ## Challenges and Considerations [Section titled “Challenges and Considerations”](#challenges-and-considerations) * **Legal Compliance**: Censorship is often tied to legal requirements that hosting providers must comply with. Even decentralized systems will face challenges related to legal jurisdictions, and Pubky is designed to navigate but not entirely eliminate these legal issues. * **Content Moderation**: Some forms of moderation are necessary—whether it’s to filter out spam or harmful content. Pubky facilitates **user-controlled moderation**, where individuals or groups decide what they want to see, rather than a centralized authority imposing a one-size-fits-all policy. * **Redundancy Limitations**: [Pubky Backup](/pubky-backup/) improves user-controlled data availability, but it is local backup rather than automatic server failover. Practical migration still depends on available [Homeservers](/homeserver/) and tooling to re-upload data. Censorship on the web is inevitable, but that doesn’t mean users have to be powerless. With Pubky, you have the ability to choose your hosting, migrate your data, and maintain your identity—all key tools for resisting censorship. Pubky’s design assumes censorship will happen and provides the mechanisms needed to overcome it. This empowers users with true control, ensuring that no single entity can unilaterally suppress their voice. The future of the web lies in resilient, user-first systems that put individuals back in control of their online presence. # Comparisons Pubky combines public-key identity, signed service discovery through [PKARR](https://github.com/pubky/pkarr), and mutable files on a user-chosen [Homeserver](https://github.com/pubky/pubky-homeserver). This is useful when building a web app whose users should keep their identity and data independently of the app’s operator. For example, a document can keep the same public-key-based address as its contents change or its owner changes hosting providers. Apps use familiar HTTP storage operations, while discovering the user’s chosen server without requiring ownership of a conventional domain name. That combination is Pubky’s main advantage. Several alternatives also separate apps from storage, support portable identity, or let users edit data. ## Personal storage and identity [Section titled “Personal storage and identity”](#personal-storage-and-identity) ### Solid [Section titled “Solid”](#solid) [Solid](https://solidproject.org/TR/protocol) lets applications access user-controlled storage, commonly called Pods, through HTTP. It supports both linked data and ordinary files, with permissions determining which applications can access them. Identity uses a WebID URL, which can be hosted separately from the data. Pubky is particularly relevant when you want the identity and its discovery mechanism to remain independent of conventional domain ownership. Solid is worth evaluating when its linked-data conventions and Web standards fit your application. ### remoteStorage [Section titled “remoteStorage”](#remotestorage) [remoteStorage](https://remotestorage.io/protocol.html) is a close comparison: user-selected storage, HTTP files, and application access authorized through OAuth. It discovers storage using WebFinger and a domain-based user address. Pubky adds a key-based identity and PKARR discovery to a similarly familiar storage model. For applications that need local changes synchronized automatically, consider that [remoteStorage.js already provides offline synchronization](https://remotestorage.io/rs.js/docs/why.html); choosing Pubky does not provide that application behavior automatically. ### Peergos [Section titled “Peergos”](#peergos) [Peergos](https://book.peergos.org/security/capabilities.html) provides an encrypted filesystem with controlled sharing. Its [identity infrastructure](https://book.peergos.org/security/pki.html) maps usernames to public keys and storage providers through a mirrored directory. It also supports [provider migration](https://book.peergos.org/features/migration.html) while preserving identity and links. Pubky’s public-key addresses avoid allocating names in a global username registry. Peergos deserves particular attention for private file collaboration; ordinary public Pubky records have a different confidentiality and trust model. ## Shared social data [Section titled “Shared social data”](#shared-social-data) ### Nostr [Section titled “Nostr”](#nostr) [Nostr](https://github.com/nostr-protocol/nips/blob/master/01.md) distributes signed events through relays. Clients can verify an event independently of the relay that delivered it. [Published relay lists](https://github.com/nostr-protocol/nips/blob/master/65.md) help clients find where users read and publish. Pubky offers a direct model for reading and updating the current file at a stable path. Nostr expresses updates through replacement events and [deletion requests](https://github.com/nostr-protocol/nips/blob/master/09.md). Pubky’s approach can suit mutable documents; Nostr’s signatures suit independently verifiable event distribution. Neither can erase copies other people have already retained. ### AT Protocol [Section titled “AT Protocol”](#at-protocol) [AT Protocol](https://atproto.com/specs/repository), used by Bluesky, stores records in signed repositories, with schemas and separately stored [blobs](https://atproto.com/specs/blob). Its [identity system](https://atproto.com/guides/identity) supports `did:plc` and `did:web`, and [account migration](https://atproto.com/guides/account-migration) is an implemented workflow. Pubky offers public-key discovery without a PLC identity directory or domain-based DID, and file storage without requiring AT Protocol’s repository format. AT Protocol’s signed repositories provide verification that ordinary public Pubky files do not. Both approaches still need shared data conventions for applications to interoperate. ## Peer-to-peer application platforms [Section titled “Peer-to-peer application platforms”](#peer-to-peer-application-platforms) ### Freenet [Section titled “Freenet”](#freenet) [Freenet](https://freenet.org/build/manual/components/contracts/) replicates mutable application state, with WebAssembly contracts validating updates. Applications define their own identity and authorization rules. This is the project formerly called Locutus, distinct from the older Freenet now called Hyphanet. Pubky supplies a common user identity and hosted HTTP storage model. It can fit a web application that needs users to publish files without implementing replicated contract state. Freenet is relevant when replicated state and its validation rules are central to the application. ### Holepunch / Pear [Section titled “Holepunch / Pear”](#holepunch--pear) [Pear’s stack](https://docs.pears.com/p2p/explanation/how-the-stack-fits-together/) combines peer discovery, verifiable logs, file storage, multiwriter data, and an application runtime. Hypercore is one component of this broader stack. Pubky fits conventional browser applications backed by user-selected servers. Pear is relevant when applications need to exchange and replicate data directly between peers. Compare the whole application and hosting model, rather than treating Hypercore alone as its equivalent to Pubky. ## What to check before choosing [Section titled “What to check before choosing”](#what-to-check-before-choosing) Pubky’s [Security Model](/security-model/) includes trust in the Homeserver for public file integrity and availability. Signed discovery does not automatically sign stored files. [Changing providers](/credible-exit/) also requires preserving and moving data; updating discovery alone is not migration. Use the [Developer Guide](/developer-guide/) to assess how the workflow fits your application. # Contributing AI-Assisted Contributions We welcome contributions made with the help of AI tools, but you are fully responsible for what you submit. You must understand, review, and be able to explain every change in your PR. Unreviewed AI-generated submissions — bulk changes, hallucinated references, or PRs the author cannot explain — will be closed without review. ## Code and bug reports [Section titled “Code and bug reports”](#code-and-bug-reports) Search existing issues before opening a report; include reproduction steps and the affected software version. ## Security [Section titled “Security”](#security) If you believe you have found a vulnerability, follow the [Pubky Security Policy](https://github.com/pubky/.github/blob/main/SECURITY.md) to report it privately instead of opening a public issue. ## Community [Section titled “Community”](#community) Join [Telegram](https://t.me/pubkycore) to ask questions, help other users, and share what you build. # Credible Exit **Credible Exit** is the ability to leave a platform or service without losing access to your data, identity, or connections, ensuring full user control and portability. This [substack post](https://subconscious.substack.com/p/credible-exit) by Gordon Brander is a good introduction to the topic. Imagine you’ve built a social profile on a platform. Over time, you start noticing that some of your posts are being restricted or your content is no longer being promoted. You don’t want to lose everything you’ve built—your posts, connections, or even your online identity. This is where **Credible Exit** comes into play. It ensures that you can leave a platform without losing what’s yours, giving you true control over your online presence. It is also important for the credible exit to be feasible, as in a measure of cost, meaning the cost of exit should be within the order of magnitude of making an exit economically efficient. ## Why Credible Exit is Important [Section titled “Why Credible Exit is Important”](#why-credible-exit-is-important) Today, most platforms hold your data hostage. They make it difficult to leave, and if you do leave, you often lose all your posts, connections, and your ability to stay visible. This is the result of centralized control—a few big platforms deciding what can be shared and who gets to see it. They can censor you or limit your access without warning. Here are some of the best examples of Credible Exit in practice: * **Domain Name System (DNS)**: DNS is a classic example of a system that allows for a credible exit. If you no longer want your domain hosted with one provider, you can transfer it to another without losing control over your domain name. * **Email Protocols (IMAP/SMTP)**: Email is another example. Users can change email providers while keeping the same email address, ensuring they don’t lose their communication history or contacts. * **Bitcoin Wallets**: Bitcoin wallets offer credible exit by allowing users to export private keys and import them into another wallet provider, retaining full control over their funds and transactions. **Credible Exit** is a fundamental principle that ensures users are never locked in. It means having the freedom to move your data, identity, and content to a new service without losing anything. It gives you leverage, making sure that platforms compete for your trust rather than taking it for granted. ## How Pubky Makes Credible Exit Possible [Section titled “How Pubky Makes Credible Exit Possible”](#how-pubky-makes-credible-exit-possible) In **Pubky**, Credible Exit is not just an idea—it’s built into the architecture. Pubky combines decentralized routing and identity with flexible, user-controlled hosting to make sure you’re always in charge. * **Trusted Servers with a Safety Net**: When you join Pubky, you can use a trusted server to host your data. These servers are there to provide convenience, but you’re never stuck. If the server changes its policies or you simply want to move, Pubky allows you to seamlessly migrate your data to another server without any loss of content or followers. * **Decentralized Identity**: With Pubky, your identity is not tied to any one server. You use self-issued public keys that are recognized across the network. This means you can change where your data is hosted without losing your identity or connections. * **Data Portability**: [Pubky Backup](/pubky-backup/) is a desktop tool that stores local snapshots of a user’s published Homeserver data. Re-uploading those local files to a new Homeserver is still a manual workflow today, while seamless restore and Homeserver mirroring are planned features. > *NOTE*: During Pubky’s initial bootstrapping phase, credible exit may not be fully practical until more Homeserver providers and migration tools mature. [Synonym](https://synonym.to/) is building tools to make it easy for businesses and users to self-host, and Pubky Backup reduces one important exit cost by keeping a local data copy. ## Important Aspects of Credible Exit [Section titled “Important Aspects of Credible Exit”](#important-aspects-of-credible-exit) * **Protocols**: The foundation of credible exit, enabling communication and data transfer between systems. * **Data Importance**: Differentiating between basic data (content created by users) and generated data (interactions, likes, comments), which may require different approaches for exit. * **Dimensions of Credible Exit**: Including the ability to export data, sync data across platforms, use data in useful formats, and store data in local files. ## Challenges and Considerations [Section titled “Challenges and Considerations”](#challenges-and-considerations) * **Static Exports**: While GDPR regulations allow for data exports, the static nature of these exports can limit their utility for ongoing use. * **Data Formats**: The importance of using common, useful formats for data to ensure it can be utilized elsewhere. * **Interoperability**: The potential for multiple apps to share data through permissionless APIs, enhancing broad interoperability. ## Summary [Section titled “Summary”](#summary) Credible Exit is about freedom and control. It ensures that you’re never at the mercy of a single platform or server. With Pubky, you get the convenience of using trusted servers while always having an exit strategy—one that guarantees you keep everything you’ve built online. This is the foundation of a more open, user-first web, where platforms must earn your trust rather than exploit it. # Developer Guide This guide walks you through building a first Pubky app against a local development stack. You will start a local Homeserver with Pubky Docker, create a Vite app, install the Pubky SDK, and connect your app to the local testnet. By the end, you will have created a demo identity, signed up and signed in on the local Homeserver, written a JSON file to Pubky storage, and read it back in the browser. After that, you will also get to know the templates you can use to bootstrap your own Pubky app. To follow along, you will need [Docker](https://docs.docker.com/get-started/get-docker/) and [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/). ### Step 1: Set Up Pubky Docker [Section titled “Step 1: Set Up Pubky Docker”](#step-1-set-up-pubky-docker) Prefer a native setup? If you do not want to use Docker, see the [native Pubky testnet setup](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-testnet/README.md). In order to build our App we’ll need to setup a local homeserver and testnet - we’ll use [Pubky Docker](/pubky-docker/) to spin up a local development environment. Note: [Pubky Docker](/pubky-docker/) can run a full [pubky.app](/pubky-app/)-compatible social stack too, but we will keep this setup minimal. ```bash git clone https://github.com/pubky/pubky-docker.git && cd pubky-docker && cp .env-sample .env ``` Make sure your Docker engine is running. On Linux, [start the daemon](https://docs.docker.com/engine/daemon/start/); with Docker Desktop, open the app. For [Colima](https://colima.run/docs/getting-started/), run: ```bash colima start ``` Run the homeserver and testnet via Docker compose: ```bash docker compose up homeserver -d ``` Open (PKARR relay) and (Homeserver admin) in your browser to verify they respond. You now have a local Pubky testnet ready for app development. An isolated DHT is running, the HTTP relay is local, and the Homeserver publishes its PKARR identity to the local DHT. This means local clients can discover your Homeserver the same way they would on the public network, with local testnet services. The Docker stack publishes ports and uses development credentials; run it only on an isolated development machine or network, with disposable data and identities. Your testnet Homeserver’s pubky is always `8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo`. Testnet state is ephemeral When the Docker containers are restarted the files stored on the Homeserver and user PKARR records in the local DHT are reset. The testnet Homeserver does however have a stable, predefined pubky. With `.env` set to the default `NETWORK=testnet`, these ports are exposed: | Port | Service | Purpose | | ------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `15411` | [PKARR](/pkarr/) relay | Used by the Pubky SDK to publish and resolve testnet PKARR records over HTTP, instead of using the [Mainline DHT](/mainline-dht/). | | `15412` | [HTTP relay](/http-relay/) | Runs the local relay used by Pubky authentication flows. | | `6286` | Homeserver ICANN HTTP | Clear-text HTTP endpoint used for browser and localhost fallback. | | `6287` | Homeserver [PubkyTLS](/glossary/#pubkytls) | Direct Pubky TLS endpoint for SDK and native clients. | | `6288` | Homeserver admin HTTP | Local admin endpoint exposed by Pubky Docker. | CLI examples For manual user and Homeserver operations while developing locally, you can use [JavaScript CLI examples](https://github.com/pubky/pubky-homeserver/tree/v0.14.0/examples/javascript). For source builds, see [Optional: Build from source](https://github.com/pubky/pubky-docker/blob/main/Readme.md). ### Step 2: Initialize Project with the SDK [Section titled “Step 2: Initialize Project with the SDK”](#step-2-initialize-project-with-the-sdk) What follows is a step-by-step guide to building your first Pubky app. If you prefer to start from a ready-made project, jump to the [basic Pubky app template](#39-basic-pubky-app-template). Reference docs For full API details see the reference documentation for [JavaScript](https://pubky.github.io/pubky-homeserver/js-sdk-typedoc/) and [Rust](https://docs.rs/pubky). With the Homeserver running, clone this empty Vite template and install the [Pubky SDK](/sdk/): ```bash npx tiged pubky/pubky-app-templates/vite-starter pubky-hello-world cd pubky-hello-world npm install && npm install @synonymdev/pubky ``` NPM package: [@synonymdev/pubky](https://www.npmjs.com/package/@synonymdev/pubky) **Other tools and platforms** If you are using another language, package manager, or framework, install the SDK like this. Dedicated guides for these will follow. **Yarn:** ```bash yarn add @synonymdev/pubky ``` **Rust ([docs](https://docs.rs/pubky)):** ```bash cargo add pubky ``` **React Native:** ```bash npm install @synonymdev/react-native-pubky cd ios && pod install # iOS only ``` **iOS/Android Native**: See [SDK Documentation](/sdk/) for UniFFI bindings via `pubky-core-ffi`. ### Step 3: Build Your First App [Section titled “Step 3: Build Your First App”](#step-3-build-your-first-app) Open `src/main.ts` and replace the `document.querySelector('#app')!.textContent = 'Vite Starter'` line with the snippets below. #### 3.1 Import the SDK and enable info logs [Section titled “3.1 Import the SDK and enable info logs”](#31-import-the-sdk-and-enable-info-logs) ```js import { Keypair, Pubky, PublicKey, setLogLevel } from "@synonymdev/pubky"; try { setLogLevel("info"); } catch (error) { console.warn( "Pubky log level must be set only once, before creating the client.", error, ); } ``` This loads the Pubky SDK and sends info logs to the browser console. To see the logs in your browser console, make sure you have the right log level filtering configured in your browser as well. #### 3.2 Connect to the local testnet [Section titled “3.2 Connect to the local testnet”](#32-connect-to-the-local-testnet) ```js const pubky = Pubky.testnet(); ``` This tells the SDK to use the local testnet services started by Pubky Docker instead of the production Pubky network. #### 3.3 Create a new user identity [Section titled “3.3 Create a new user identity”](#33-create-a-new-user-identity) ```js const keypair = Keypair.random(); const signer = pubky.signer(keypair); console.log("Your pubky:", signer.publicKey.z32()); ``` This creates a demo identity for the hello-world app and logs its pubky to the browser console. #### 3.4 Sign up on the local Homeserver [Section titled “3.4 Sign up on the local Homeserver”](#34-sign-up-on-the-local-homeserver) ```js const homeserver = PublicKey.from( "pubky8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo", ); await signer.signup(homeserver, null); ``` This creates an account on the local Homeserver and publishes the user’s Homeserver mapping (PKARR). Because [local signup is set to `open`](https://github.com/pubky/pubky-docker/blob/75b1121f3e90b9b44d9416ca4f5ba87a4984e800/homeserver.config.toml#L5), we pass `null` instead of a signup token. Homeserver signup This guide performs Homeserver signup inside the app because it is the shortest path to a working local example. In a real-world flow, however, Homeserver signup is not the responsibility of a Pubky app. Assume users already have an account on a Homeserver. If not, direct them to a separate signup flow, such as [the onboarding on pubky.app](https://pubky.app/onboarding/human), instead of implementing it in the app. The template in Step 3.9 follows this pattern. Run `npm run dev` and open the printed URL in your browser. Look at the logs in your browser console. You should see that the signup request succeeded and that you successfully published your Homeserver configuration (= PKARR). 404 during signup During first signup, the browser console may show a `404` for a request to `http://localhost:15411/`. That can be normal: the SDK checks whether the new user’s PKARR record exists before publishing it. If signup continues, you can ignore that `404`. #### 3.5 Sign in [Section titled “3.5 Sign in”](#35-sign-in) ```js const session = await signer.signin("myapp.example"); ``` This creates a Homeserver session for the demo user. #### 3.6 Write to Homeserver storage [Section titled “3.6 Write to Homeserver storage”](#36-write-to-homeserver-storage) ```js const path = "/pub/hello-world/data.json"; await session.storage.putJson(path, { message: "Hello Pubkyverse!" }); ``` This writes a simple JSON file onto the signed-in user’s Homeserver public storage. Store independent records separately Store each independently edited record in its own file. For example, a posts collection can use `/pub/myapp/posts/001.json` and `/pub/myapp/posts/002.json`. A write replaces the data at one path, so this layout lets your app: * **Send smaller updates:** Upload the changed record without rewriting unchanged data. * **Load records as needed:** Page through the directory listing and fetch only the files needed for the current view. * **Reduce potential write conflicts:** Editing the same file from different processes or apps needs coordination. That said, keep fields together when you read and update them as a unit. Splitting them adds unnecessary requests. #### 3.7 Read the JSON back [Section titled “3.7 Read the JSON back”](#37-read-the-json-back) ```js const data = await session.storage.getJson(path); document.querySelector("#app")!.textContent = JSON.stringify( data, null, 2, ); ``` This fetches the same JSON file from Homeserver storage and renders it in the template’s `#app` element, proving that signup, signin, write, and read all worked. Run `npm run dev` again and open the page. You should now see the data displayed there. #### 3.8 Inspect Homeserver data [Section titled “3.8 Inspect Homeserver data”](#38-inspect-homeserver-data) Open the [testnet Pubky Explorer](https://explorer.pubky.app/testnet/), enter the pubky logged in Step 3.3, and browse to `/pub/hello-world/data.json`. The hosted app connects to `localhost`; allow local-network access if prompted. Alternatively, clone [Pubky Explorer](https://github.com/pubky/pubky-explorer) and run it locally. First app complete Nice. Your first Pubky app works. #### 3.9 Basic Pubky app template [Section titled “3.9 Basic Pubky app template”](#39-basic-pubky-app-template) As a next step, try [this template](https://pubky.github.io/pubky-app-templates/) as a fuller starting point for a fresh Pubky app. It includes a working browser app with local testnet configuration, identity creation, Homeserver signup and signin, and a Pubky auth flow. Treat it as a set of building blocks: copy the pieces your app needs, adapt the auth and storage flows, and replace the sample UI with your own experience. ```bash npx tiged pubky/pubky-app-templates/basic-pubky-app my-pubky-app cd my-pubky-app npm install ``` Set a stable app ID in `src/config.ts`; it determines the storage path. ```bash VITE_PUBKY_TESTNET=true npm run dev ``` ##### Homeserver auth [Section titled “Homeserver auth”](#homeserver-auth) The basic app offers two login paths. The right-side **New identity** panel is a development shortcut: it creates a keypair inside the app, signs up with the Homeserver, and signs in. The left-side **Sign in with Pubky Ring** panel shows the recommended authentication flow: the app initiates sign-in, while responsibility for key management and Homeserver signup remains with components outside the app. For local development, you can use the [Pubky Ring Simulator](https://simulator.pubkyring.app/) as a browser-based stand-in for Pubky Ring. The simulator is preconfigured to connect to your local testnet on `localhost`. Because the hosted version accesses services running on your device, your browser may ask whether `simulator.pubkyring.app` can access apps and services on your device or devices on your local network. Choose **Allow** to continue. If you prefer not to grant this permission, clone the simulator and follow its [development instructions](https://github.com/pubky/pubky-ring-simulator#development) to run it locally. 1. In `my-pubky-app`, use the left-side **Sign in with Pubky Ring** panel and click **Copy link**. 2. In the simulator, select **Shortcut** mode and paste the link into **Auth link**. 3. The simulator creates an identity, signs it up on your local Homeserver, then approves the request automatically. 4. Switch back to `my-pubky-app`. It polls the pending auth flow and signs in automatically once the simulator approves. 5. To test sign-in with different identities, use the Pubky Ring Simulator in **Regular** mode. It simulates Pubky Ring’s identity management, letting you create and select an identity before authorizing a request. That flow is the security best practice: it keeps the user’s key material out of the application being tested. The Pubky app template receives a session after authorization, but the identity and Homeserver setup remain with the signer. ### Step 4: Add Social Features [Section titled “Step 4: Add Social Features”](#step-4-add-social-features) Guide coming soon For now, this section collects references. A dedicated guide will follow. **Learn from working examples:** * [mypubky.com](https://mypubky.com/) ([source](https://github.com/pubky/mypubky)) * [eventky.app](https://eventky.app/) ([source](https://github.com/gillohner/eventky)) * [mapky.app](https://mapky.app/) ([source](https://github.com/gillohner/mapky-app)) **Social App (pubky-app-specs):** * [pubky-app-specs](https://github.com/pubky/pubky-app-specs) - Data models for social features and interoperability with [pubky.app](/pubky-app/) * [npm: pubky-app-specs](https://www.npmjs.com/package/pubky-app-specs) / [crates.io: pubky-app-specs](https://crates.io/crates/pubky-app-specs) **Use Pubky Nexus for Social Features:** If building a social app, leverage [Pubky Nexus](/pubky-nexus/) for: * Real-time feeds and timelines * Search and discovery * User recommendations * Notifications ```javascript const response = await fetch( "https://nexus.pubky.app/v0/stream/posts?limit=10", ); const posts = await response.json(); ``` 📊 [Nexus API Docs](https://nexus.pubky.app/swagger-ui/) **Add Payments (WIP):** [Paykit](/paykit/) protocol (work in progress) will enable: * Payment discovery via Pubky public keys * Public or private payment details for Bitcoin onchain, Lightning, and other rails * Encrypted receipt access for payers * Subscriptions and payment request workflows **Add Encryption (WIP):** [Pubky Noise](/pubky-noise/) (work in progress) provides: * Encrypted peer-to-peer channels * Private messaging * Secure data sharing ### Step 5: Production Setup [Section titled “Step 5: Production Setup”](#step-5-production-setup) To connect your app to the production Pubky network, replace the client from Step 3.2: ```diff const pubky = Pubky.testnet(); const pubky = new Pubky(); ``` `new Pubky()` stops using the local endpoints. The app instead resolves [PKARR](/pkarr/) records from the [Mainline DHT](/mainline-dht/), connects to the Homeserver resolved from each user’s PKARR record, and uses a public [HTTP relay](/http-relay/) for authentication. Steps 3.3–3.5 use development-only identity and Homeserver shortcuts. For production, use [Pubky Ring](/pubky-ring/); the [basic Pubky app template](#39-basic-pubky-app-template) already implements that flow. **Optional: Configure custom relays** Browsers cannot query the UDP-based Mainline DHT directly, so the SDK uses HTTPS gateways called **PKARR relays**. See the [current default relay list](https://github.com/pubky/pkarr/blob/main/pkarr/src/lib.rs). To use custom PKARR relays: ```javascript const client = new Client({ pkarr: { relays: ["https://pkarr.pubky.org"], }, }); const pubky = Pubky.withClient(client); ``` PKARR relays are separate from the [HTTP relay](/http-relay/) that transfers encrypted Pubky Ring authentication messages. To use a custom HTTP relay with the SDK: ```javascript import { AuthFlowKind } from "@synonymdev/pubky"; const relay = "https://httprelay.example.com/inbox/"; const flow = await pubky.startGrantAuthFlow( "/pub/myapp/:rw", AuthFlowKind.signin(), { clientId: "myapp.example", relay, }, ); ``` The basic template maps [`VITE_PUBKY_HTTP_RELAY`](https://github.com/pubky/pubky-app-templates/blob/main/basic-pubky-app/src/config.ts) to the same SDK option. #### Test the Setup [Section titled “Test the Setup”](#test-the-setup) 1. Start the production-configured app and authenticate through Pubky Ring with your production identity. 2. Use the app to create some sample data. 3. Enter your pubky in [Pubky Explorer](https://explorer.pubky.app) and verify the files created by the app. ### Next Steps [Section titled “Next Steps”](#next-steps) * **Explore SDK examples:** See the [Pubky Homeserver examples](https://github.com/pubky/pubky-homeserver/tree/v0.14.0/examples) for runnable workflows. * **Find SDK references:** See the [Pubky SDK guide](/sdk/) for supported platforms, API references, and examples. * **Choose an app architecture:** Compare [client-only, aggregator, and custom-backend designs](/app-architectures/). * **Security model:** Review the [security considerations for app developers](/security-model/). Need help? Ask on pubky.app or [Telegram](https://t.me/pubkycore). # First Steps Developer Guide This guide helps you try Pubky **as a user**; if you want to build on Pubky, start with the [Developer Guide](/developer-guide/). Welcome to Pubky! You’ll create your identity, sign in to pubky.app, and inspect and back up the data you publish. ## Step 1: Download Pubky Ring [Section titled “Step 1: Download Pubky Ring”](#step-1-download-pubky-ring) **[Pubky Ring](/pubky-ring/)** is your key manager for the Pubky ecosystem. It stores your identity and lets you authorize Pubky apps without creating a platform-owned account. * **iOS**: Download from the [App Store](https://apps.apple.com/us/app/pubky-ring/id6739356756) * **Android**: Download from [Google Play](https://play.google.com/store/apps/details?id=to.pubky.ring) [Official Website](https://pubkyring.app/) · [Official Repository](https://github.com/pubky/pubky-ring) ## Step 2: Create Your Pubky Identity And Profile [Section titled “Step 2: Create Your Pubky Identity And Profile”](#step-2-create-your-pubky-identity-and-profile) 1. Visit **[pubky.app](https://pubky.app)**. 2. Click “Join now”. 3. Enter your invite code if you have one. If not, depending on where you are located, you may be able to use SMS verification and/or Bitcoin payment verification. These checks help Homeserver operators prevent signup spam. They are *not* meant to invade your privacy or charge you for using the Homeserver. Other signup methods are in development. 4. Scan the QR code with your smartphone and open the link with Pubky Ring. The QR code contains your invite code. 5. Authorize pubky.app in Pubky Ring to write to `/pub/pubky.app` on your Homeserver. Homeservers only allow an app to write to the paths you approve. As of today, everything under `/pub/` is public by default, so read access does not require authorization. 6. Create your Pubky profile. 7. **Save your recovery phrase securely** - this is your master backup. 8. Your public key (pubky) is now your permanent identity! Your pubky looks like this: ```text z4e8s17cou9qmuwen8p1556jzhf1wktmzo6ijsfnri9c4hnrdfty ``` ## Step 3: Try pubky.app [Section titled “Step 3: Try pubky.app”](#step-3-try-pubkyapp) Once your profile is created, use **[pubky.app](https://pubky.app)** as a decentralized social media app built on Pubky. 1. Start posting, following, tagging, and exploring. 2. Reopen pubky.app later and sign in with the same Pubky Ring identity. What makes it different: * You define on which Homeserver your own data is stored. You are in control. * Your feed is shaped by your choices, not by a platform’s engagement algorithm. * Pubky is designed for [censorship resistance](/censorship-resistance/) and [credible exit](/credible-exit/). ## Explore Other Pubky Apps [Section titled “Explore Other Pubky Apps”](#explore-other-pubky-apps) Your Pubky Ring identity can be used across different Pubky apps. When you authorize another app, it can publish data on your Homeserver, instead of making you create a separate account for every application. As you sign in to these apps, notice how Pubky Ring asks you to approve access to specific paths on your Homeserver. * **[mypubky](https://mypubky.com/)**: A shareable bio page for your profile, links, posts, and payment options. * **[Payky](https://payky.app/)**: A payment profile for sharing your payment details, from crypto to fiat, in one link. * **[Mapky](https://mapky.app/)**: A social map where your location-based data stays user-owned. * **[Eventky](https://eventky.app/)**: A social calendar and event management app with event data stored on each user’s Homeserver. ## Step 4: Explore Your Data [Section titled “Step 4: Explore Your Data”](#step-4-explore-your-data) Use **[Pubky Explorer](/pubky-explorer/)** ([explorer.pubky.app](https://explorer.pubky.app)) to browse your data. 1. Enter your pubky or navigate to a path. 2. Browse your files and directories. 3. See exactly what data you have published. 4. Share direct links to your public data. Example paths: * `pubky://your-key/pub/pubky.app/profile.json` - Your profile * `pubky://your-key/pub/pubky.app/posts/` - Your posts directory ## Step 5: Back Up Your Published Data [Section titled “Step 5: Back Up Your Published Data”](#step-5-back-up-your-published-data) Install **[Pubky Backup](/pubky-backup/)** to keep local copies of your data and preserve your data sovereignty. Use [Pubky Backup README](https://github.com/pubky/pubky-backup/blob/main/README.md) and [release builds](https://github.com/pubky/pubky-backup/releases) for download and install instructions. Pubky Backup does not replace your recovery phrase. The recovery phrase protects your identity key; Pubky Backup protects a local copy of your published data. ## Next Steps [Section titled “Next Steps”](#next-steps) * **Join the community**: [Telegram](https://t.me/pubkycore) * **Learn more**: Read the [Overview](/overview/) * **Understand the tech**: Check out [System Architecture](/architecture/) * **Explore concepts**: Learn about the [Semantic Social Graph](/semantic-social-graph/) ## Common First Questions [Section titled “Common First Questions”](#common-first-questions) **Do I need Pubky Ring to use Pubky?** Pubky Ring is the recommended way to manage your identity and authorize apps. It keeps your key material separate from individual apps. **Can I use Pubky without running my own Homeserver?** Yes. Users can choose a public Homeserver provider. Running your own is optional. **Where is my data stored?** Your public app data is stored on a Homeserver, which is linked to your pubky through [PKARR](/pkarr/). You can change your Homeserver in Pubky Ring, and [Pubky Explorer](https://explorer.pubky.app) lets you inspect what is currently stored there. # Glossary Quick reference for terms used throughout the Pubky ecosystem. *** ## A [Section titled “A”](#a) **Aggregator** A service that collects and organizes data from multiple [Homeservers](/homeserver/) to enable search, feeds, and discovery features. See [Aggregator](/indexing-and-aggregation/). **Authentication** The process of proving ownership of a public key through cryptographic signatures, enabling secure access to Homeservers without passwords. See [details](/authentication/). ## C [Section titled “C”](#c) **Grant** A cryptographically signed authorization that gives a specific application scoped read and/or write access to a user’s data. It expires and is bound to the application’s proof-of-possession key. **Censorship Resistance** The property of being difficult or impossible to block, censor, or control by any single authority. Pubky achieves this through decentralized [Mainline DHT](/mainline-dht/) and distributed [Homeservers](/homeserver/). **[Credible Exit](/credible-exit/)** The ability to leave a service provider (Homeserver, app, etc.) without losing your data, identity, or social connections. A core principle of Pubky’s architecture. ## D [Section titled “D”](#d) **[Distributed Hash Table (DHT)](/mainline-dht/)** A decentralized key-value storage system distributed across many nodes. Pubky uses [Mainline DHT](/mainline-dht/) for storing [PKARR](/pkarr/) records. **[Domain Name System (DNS)](/pkdns/)** Traditional system for translating domain names to IP addresses. [PKDNS](/pkdns/) extends this to support public-key domains. **[DNS over HTTPS (DoH)](/pkdns/#dns-over-https-doh)** Protocol for encrypting DNS queries using HTTPS, preventing surveillance and tampering. ## G [Section titled “G”](#g) **Guarded Data** See [Private Storage](/glossary/#private-storage). The [Security Model](/security-model/#guarded-data) uses “guarded” to distinguish access-controlled data from encrypted data. ## H [Section titled “H”](#h) **[Homeserver](/homeserver/)** A web server that stores user data in a filesystem over a simple HTTP API. Internally, PostgreSQL tracks metadata such as users, quotas, sessions, and events. Users can run their own or choose any provider. Data is stored per public key and accessed via HTTP/HTTPS. **[Homegate](/homegate/)** A signup verification service for Homeservers, providing SMS and Lightning Network payment verification to prevent spam while preserving privacy. **[Homeserver CLI](https://github.com/pubky/pubky-homeserver/tree/v0.14.0/homeservercli)** Command-line tool for interacting with Pubky Homeservers, providing user operations, admin functions, and testing utilities. ## I [Section titled “I”](#i) **Indexer** See **Aggregator**. A service that crawls and indexes data from Homeservers to provide search and discovery features. ## K [Section titled “K”](#k) **[Key Pair](/security-model/#key-custody)** A pair of cryptographic keys (public and private) used for identity, authentication, and encryption. In Pubky, your public key IS your identity. ## M [Section titled “M”](#m) **[Mainline DHT](/mainline-dht/)** The Distributed Hash Table used by BitTorrent, with 10+ million nodes globally. Pubky uses it to store [PKARR](/pkarr/) records, providing censorship-resistant discovery. ## N [Section titled “N”](#n) **[Nexus](/pubky-nexus/)** (Pubky Nexus) Production-grade indexing and aggregation service for [pubky.app](/pubky-app/). Provides high-performance social graph API, search, and real-time notifications. **[Noise](/pubky-noise/)** (Pubky Noise) Noise Protocol implementation for encrypted peer-to-peer communication in the Pubky ecosystem (work in progress). ## P [Section titled “P”](#p) **[Paykit](/paykit/)** Payment protocol built on Pubky for payment discovery and coordination across multiple payment methods, including Bitcoin on-chain and Lightning (work in progress). **[PKARR](/pkarr/)** (Public Key Addressable Resource Records) Self-issued, signed DNS-like records published to the Mainline DHT. Each record is tied to a public key and contains information like Homeserver locations. **[PKDNS](/pkdns/)** DNS server that resolves public-key domains by fetching PKARR records from the Mainline DHT, bridging traditional DNS with decentralized identity. **[Private Storage](/private-storage/)** Storage under `/priv/` on a [Homeserver](/homeserver/), readable only with an authenticated session for the data owner’s identity and capabilities covering the requested path. It provides access control, not encryption; apps that need confidentiality from the operator encrypt the data themselves. **Proof of Possession (PoP)** A cryptographic check that an application controls the private key bound to a grant. The application presents a signed PoP proof when exchanging the grant for a bearer token, so the grant cannot be used on its own. See [Authentication](/authentication/). **Public Key** The public half of a cryptographic key pair. In Pubky, this serves as your permanent, self-sovereign identity (often called a “pubky”). **Pubky** 1. The decentralized web protocol and ecosystem, formally known as the [Pubky protocol](/overview/) 2. A user’s public-key identity (e.g., “my pubky is z4e8s…”) **Pubky app** Any application built on the [Pubky protocol](/overview/). A Pubky app uses the Pubky [SDK](/sdk/) and [Homeservers](/homeserver/) for authentication and data storage. See [App Architectures](/app-architectures/). **[pubky.app](/pubky-app/)** The reference implementation of a Pubky app — a decentralized social media application built by Synonym, live at [pubky.app](https://pubky.app). It demonstrates how to build social applications on the Pubky protocol using [Nexus](/pubky-nexus/) for indexing and the [pubky-app-specs](/pubky-app-specs/) data model. **[Pubky Backup](/pubky-backup/)** Desktop app for keeping local copies of published Homeserver data. Current app details are in the [Pubky Backup README](https://github.com/pubky/pubky-backup/blob/main/README.md). **[Pubky Protocol](/overview/)** The protocol encompassing the Homeserver, SDK, PKARR and specifications for building decentralized applications on Pubky. **PubkyTLS** Pubky’s TLS transport for Homeserver connections addressed by public key. It uses TLS with Raw Public Keys (RFC 7250), so the server public key is verified directly instead of through an X.509 certificate authority chain. **[Pubky Docker](/pubky-docker/)** Docker Compose orchestration for running the complete Pubky Social stack locally with one command. **[Pubky Explorer](/pubky-explorer/)** Web-based file browser for exploring public data on Pubky Homeservers. Available at [explorer.pubky.app](https://explorer.pubky.app). **[Pubky Ring](/pubky-ring/)** Mobile key manager app (iOS/Android) for securely managing pubkys, authorizing applications, and handling sessions. **[pubky-app-specs](/pubky-app-specs/)** Formal data model specifications for [pubky.app](/pubky-app/), defining structures for users, posts, tags, and other social features. Any Pubky app that follows these specs can interoperate with pubky.app and its ecosystem. ## R [Section titled “R”](#r) **Recovery File** Encrypted backup of a user’s private key and identity information, protected by a passphrase. Used for key recovery and migration between devices. ## S [Section titled “S”](#s) **[SDK](/sdk/)** (Software Development Kit) Client libraries for building Pubky applications, available in Rust, JavaScript/WASM, and native mobile (iOS/Android). **Self-Sovereign Identity** Identity that is fully controlled by the individual, not dependent on any centralized authority or service provider. Pubky implements this via cryptographic key pairs. **[Semantic Social Graph](/semantic-social-graph/)** A social network where relationships are tagged with meaningful metadata, enabling personalized content filtering, trust-based discovery, and user-controlled feeds. **Session** A time-limited authentication state that allows a client to access a Homeserver without repeatedly signing requests with the private key. ## T [Section titled “T”](#t) **Tag** User-defined label attached to posts, files, or other users to add semantic meaning and enable filtering/discovery in the [Semantic Social Graph](/semantic-social-graph/). ## W [Section titled “W”](#w) **Web of Trust** Traditional model where trust propagates through social connections. Pubky extends this with the [Semantic Social Graph](/semantic-social-graph/), adding semantic context to trust relationships. # Homegate **[Homegate](https://github.com/pubky/homegate)** is a backend service that manages and controls signups for [Pubky Homeservers](/homeserver/). Pubky’s social app uses it during onboarding; the enabled verification methods depend on the operator’s configuration. It is an optional service for operators who want an onboarding gate before admitting users to their Homeserver. It controls signup, while [Pubky authentication](/authentication/) controls an app’s authorized access to an existing user’s data. See the [Homegate README](https://github.com/pubky/homegate/blob/master/README.md) for configuration and verification providers, and the [API specification](https://github.com/pubky/homegate/blob/master/openapi.yaml) for endpoint details. # Homeserver [A Homeserver](https://github.com/pubky/pubky-homeserver) stores and serves data for Pubky users. Users self-host their Homeserver or choose a provider. [PKARR](/pkarr/) lets applications discover the Homeserver from the user’s public key. ## Its role in an app [Section titled “Its role in an app”](#its-role-in-an-app) Think of a Homeserver as storage an application can use on the user’s behalf. A user authorizes the app, and the app writes files within the permissions it receives. Other apps can read public files and interpret them when they understand the data format. The Homeserver serves those files even when the user’s device is offline, provided the service remains available. It does not decide what a social feed should show or how a search result should rank. An application or [indexer](/indexing-and-aggregation/) handles those views. The Pubky protocol separates identity from hosting, enabling [Credible Exit](/credible-exit/), but moving files and updating discovery still require working tools and available copies. Homeservers provide publicly readable `/pub/` storage and access-controlled (not encrypted) `/priv/` storage. See [Private Storage](/private-storage/) for an overview and guides. Access control still trusts the operator; see the [Security Model](/security-model/). Homeservers provide [event streams](#http-api) that let apps and indexers follow changes to stored files. Homeservers also support [storage locking](/sdk/#storage-locking) to help applications coordinate concurrent updates to the same file. ## Running a Homeserver [Section titled “Running a Homeserver”](#running-a-homeserver) For installing, configuring, and running a Homeserver, follow the [Install Guide](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/docs/INSTALL.md). To make it publicly reachable see the [Deployment Guide](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/docs/DEPLOY.md). For local development and testing with a fixed-port testnet, follow the [Pubky Testnet README](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-testnet/README.md). For a full walkthrough of setting up a local stack and building your first app, see the [Developer Guide](/developer-guide/). ## HTTP API [Section titled “HTTP API”](#http-api) For routes, parameters, and response schemas, use the specifications: * **[Client OpenAPI](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-homeserver/openapi-client.yml)**: Authentication, file storage, event streams, and signup-token validation. * **[Admin OpenAPI](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-homeserver/openapi-admin.yml)**: Server administration, signup tokens, user quotas, and WebDAV. Admin access is privileged. Keep the admin interface private and protected, and provide admin credentials only to trusted operators. Ordinary applications should use the client API through the SDK. For app development, use the [SDK](/sdk/), which handles authentication, Homeserver discovery, and transport. # HTTP Relay [HTTP relay](https://github.com/pubky/http-relay) service for forwarding encrypted grants during Pubky [authentication](/authentication/) flows. In the Pubky Auth flow, a third-party app needs to receive a grant from the user’s authenticator ([Pubky Ring](/pubky-ring/)). The relay solves this by providing a temporary rendezvous point where encrypted grants can be deposited and retrieved. The relay handles message delivery; the clients handle grant encryption. It does not store your app’s files or replace a [Homeserver](/homeserver/). The [authentication overview](/authentication/) shows where it fits in the grant exchange. Use the [Pubky SDK](/sdk/) for app authentication integration. For the relay’s API, configuration, and operation, see the [HTTP Relay README](https://github.com/pubky/http-relay/blob/main/README.md); its [interactive demo](https://pubky.github.io/http-relay/) illustrates message delivery. # Mainline DHT Pubky uses BitTorrent’s Mainline distributed hash table through [PKARR](/pkarr/) to discover where a public key’s services are hosted. Application data lives on [Homeservers](/homeserver/); the DHT holds the discovery records. Discovery records require periodic republishing to remain available. The underlying storage protocol is specified in [BEP 44](https://www.bittorrent.org/beps/bep_0044.html). For the Rust implementation, usage, and operational limitations, see the [Mainline README](https://github.com/pubky/mainline/blob/main/README.md). ## Cloud network reachability [Section titled “Cloud network reachability”](#cloud-network-reachability) Direct DHT access has shown low reachability on some AWS and GCP deployments: lookups can miss records and publication can reach too few peers, even when joining the network succeeds. The [reported failures](https://github.com/pubky/mainline/issues/56) and [reachability investigation](https://github.com/pubky/mainline/issues/104) have not established a single cause. PKARR relays can provide a path through another network, provided the relay itself has working DHT connectivity. Relay clients can also encounter [timeouts during uncached lookups](https://github.com/pubky/pkarr/issues/240). See the [PKARR backend configuration guide](https://github.com/pubky/pkarr/blob/main/docs/integration.md#backend-configuration) for choosing direct DHT access, relays, or both. # Overview ## What is Pubky? [Section titled “What is Pubky?”](#what-is-pubky) Pubky is an open protocol for applications built around public-key identities and user-chosen hosting. A public key identifies the user; [PKARR](/pkarr/) lets applications discover the user’s [Homeserver](/homeserver/). The protocol provides identity, discovery, and storage. Applications decide how to use that storage and access it through the [SDK](/sdk/). [pubky.app](/pubky-app/) is a social application built on it, with shared data models and an indexer for feeds and search.  ## Why Pubky exists [Section titled “Why Pubky exists”](#why-pubky-exists) Pubky’s goal is a web where people control their identities, choose where their data lives, and decide how to discover and filter information. On a service that owns both your account and its database, changing applications often means starting again. Pubky separates those responsibilities: * **Your identity can outlast a provider.** Applications identify you by your public key, and discover where your data is hosted. Changing hosts does not require a new identifier. Making that move practical also requires your key, usable copies of your data, and migration tooling; see [Credible Exit](/credible-exit/). * **Less dependence on a single service.** User-chosen hosting and decentralized discovery support [Censorship Resistance](/censorship-resistance/). * **Different apps can work with the same data.** A post or profile can be read by another app that understands its format. The [shared social specifications](/pubky-app-specs/) make this possible for pubky.app’s data, while other apps can define formats suited to their own purpose. * **The view of the data can change independently.** Clients and indexers can offer different feeds, search results, or filters. Relationships and tags supply context for those views through the [Semantic Social Graph](/semantic-social-graph/). For a developer, this means building on familiar web applications and HTTP storage while letting users choose their identity and hosting. An app can access a user’s files directly or use an indexer when it needs to search across many users. The [architecture overview](/architecture/) explains how those pieces fit together. These choices do not eliminate trust in software or hosting providers. The [Security Model](/security-model/) explains key custody, public data, and what a Homeserver operator can do. ## The broader vision [Section titled “The broader vision”](#the-broader-vision) The **Atomic Economy** extends these ideas into a broader vision of economic and social coordination. Start with [The Atomic Economy: Reclaiming Society from the Inside Out](https://medium.com/pubky/the-atomic-economy-reclaiming-society-from-the-inside-out-574504dfe326), then explore the original [essays and talks](/resources/#philosophical-foundations). These describe motivations and possibilities; [Architecture](/architecture/) explains the implemented components and their boundaries. ## Quick Start [Section titled “Quick Start”](#quick-start) * **Try Pubky:** [First Steps](/getting-started/) introduces the user journey. * **Build an app:** the [Developer Guide](/developer-guide/) walks through writing and reading your first Pubky data. * **Run a Homeserver:** follow the [Install Guide](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/docs/INSTALL.md) and [Deployment Guide](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/docs/DEPLOY.md). * **Find a project or tool:** use the [Resources](/resources/) directory. # Paykit > ⚠️ **NOTE**: [Paykit](https://github.com/pubky/paykit-rs) is currently under active development and is **NOT production-ready**. The protocol and implementation are subject to significant changes. Integration work in Bitkit serves as a testbed for protocol development. ## Overview [Section titled “Overview”](#overview) [Paykit](https://github.com/pubky/paykit-rs) is a payment protocol built on Pubky for payment discovery and coordination across multiple payment methods, including Bitcoin on-chain and Lightning. Apps can start from a Pubky public key, discover public payment details, privately share payment details over encrypted channels, and let payers retrieve encrypted receipts. ## Core Concept [Section titled “Core Concept”](#core-concept) Paykit uses a payee’s Pubky public key as the stable starting point for payment discovery. Instead of asking for an address or invoice out of band, an app can look up the published payment details on a [Homeserver](/homeserver/) under `/pub/paykit/v0/{payment_endpoint_identifier}`. This enables applications where users can pay directly to profiles while still letting the integrating wallet or payment processor decide which payment rail to use. ## How Paykit Works [Section titled “How Paykit Works”](#how-paykit-works) Paykit uses Pubky Homeservers for payment data and [Pubky Noise](/pubky-noise/) for private Paykit messages. ### Public Payment Details [Section titled “Public Payment Details”](#public-payment-details) Payees publish payment details to their Homeserver. Anyone who knows the payee’s Pubky public key can discover those public details. ### Private Payment Coordination [Section titled “Private Payment Coordination”](#private-payment-coordination) When a payment should not rely on public payment details, a payee can share a private payment list with a specific counterparty over an encrypted channel. Private payment details are exchanged as Private Payment Envelopes. ### Encrypted Receipts [Section titled “Encrypted Receipts”](#encrypted-receipts) Paykit receipts are encrypted before storage. The payee stores the encrypted receipt on their Homeserver and sends the payer the access details needed to retrieve and decrypt it. ## Payment Methods [Section titled “Payment Methods”](#payment-methods) Paykit helps apps discover the payment details a payee publishes, but actual payment method support depends on the integrating wallet or payment application. The initial examples focus on Bitcoin on-chain and Lightning, while the endpoint identifier format is designed to support other payment methods over time. See the [Paykit Payment Endpoint Identifier Specification](https://github.com/pubky/paykit-rs/blob/master/specs/payment-endpoint-identifier.md). ## What Paykit Does Not Do [Section titled “What Paykit Does Not Do”](#what-paykit-does-not-do) Paykit does not move funds, custody keys, choose a payment rail, or implement wallet logic. Payment method selection, payment execution and key management remain the responsibility of the integrating wallet, payment processor, or application. ## Current Status [Section titled “Current Status”](#current-status) The current implementation includes public payment lists, private payment envelopes, encrypted links, and encrypted receipt access. [Bitkit](https://bitkit.to/) integrations on iOS and Android are used as protocol testbeds before stabilization. ## Potential Use Cases [Section titled “Potential Use Cases”](#potential-use-cases) ### Direct Profile Payments [Section titled “Direct Profile Payments”](#direct-profile-payments) Pay directly to profiles using Pubky identity without asking for an address or invoice out of band. ### Creator Monetization [Section titled “Creator Monetization”](#creator-monetization) Use public or private payment details for tips, paid content, or creator support. ### Commerce [Section titled “Commerce”](#commerce) Applications could use Paykit discovery around store checkouts, service bookings, or marketplace payments while keeping actual payment execution in the wallet or payment processor. ## Related Research [Section titled “Related Research”](#related-research) **Atomicity Protocol** - Peer-to-peer mutual credit system research exploring trust-based payment routing using Pubky’s [Semantic Social Graph](/semantic-social-graph/). Designed as settlement infrastructure for credit issuance and transfer across economic scales from peer-to-peer to institutional banking. Currently in research phase. ## References [Section titled “References”](#references) * **Repository and protocol overview**: [github.com/pubky/paykit-rs](https://github.com/pubky/paykit-rs) * **Library usage and API details**: [paykit-lib README](https://github.com/pubky/paykit-rs/blob/master/paykit-lib/README.md) * **Paykit Payment Endpoint Identifier Specification**: [payment-endpoint-identifier.md](https://github.com/pubky/paykit-rs/blob/master/specs/payment-endpoint-identifier.md) # PKARR [PKARR](https://github.com/pubky/pkarr) (Public-Key Addressable Resource Records) associates a public key with signed discovery records. In Pubky, these records connect a user’s identity to their Homeserver, so the identity can stay the same when the hosting location changes. ## Finding someone without fixing their location [Section titled “Finding someone without fixing their location”](#finding-someone-without-fixing-their-location) A public key is a stable identifier, but it does not tell an app which server to contact. PKARR supplies that missing step: the identity owner signs a small set of records describing where services can be reached. Those records are distributed through the [Mainline DHT](/mainline-dht/), a censorship-resistant, decentralized network. For Pubky, this means an app can start with a user’s public key, discover their Homeserver, and then fetch a file. Posts and profiles stay on the Homeserver; they are not stored in the DHT. The records use DNS’s familiar record format, but publishing an identity’s PKARR records does not require registering a conventional domain name. When hosting changes, new records can point to the new location while the public key remains the same. The signature lets clients verify who authorized a discovery record; it does not authenticate the contents of files served by that host. ## What applications need to account for [Section titled “What applications need to account for”](#what-applications-need-to-account-for) Records need to be republished to remain available, and caches can delay changes. PKARR relays let browsers reach discovery services and can also help native services with [limited DHT reachability](/mainline-dht/#cloud-network-reachability). These are separate from the [HTTP Relay](/http-relay/) used during app authorization. The [PKARR churn study](https://github.com/pubky/pkarr-churn/blob/main/results-node_decay.md) investigates how nodes leaving the DHT affect record availability, and how replication and republishing can balance availability against network load. Its survival estimates and proposed republishing schedules describe experimental conditions, not guaranteed retention or SDK defaults. DNS record TTLs guide caching; they do not set how long DHT nodes retain a record. Pubky app developers normally use the [Pubky SDK](/sdk/) to handle discovery. [PKDNS](/pkdns/) provides a bridge for software that uses conventional DNS. ## Go deeper [Section titled “Go deeper”](#go-deeper) The PKARR repository maintains the detailed explanations and integration instructions: * [Introduction](https://github.com/pubky/pkarr/blob/main/docs/introduction.md): motivation, concepts, and trade-offs. * [Quickstart](https://github.com/pubky/pkarr/blob/main/docs/quickstart.md): publishing and resolving records. * [Integration Guide](https://github.com/pubky/pkarr/blob/main/docs/integration.md): application configuration, browser support, caching, and republishing. * [Specifications](https://github.com/pubky/pkarr/tree/main/design): packet format, relays, endpoint discovery, and TLS. # PKDNS **[PKDNS](https://github.com/pubky/pkdns)** is a DNS server that enables self-sovereign and censorship-resistant domain names by resolving [PKARR](/pkarr/) (Public Key Addressable Resource Records) hosted on the [Mainline DHT](/mainline-dht/). It bridges the gap between traditional DNS infrastructure and public key-based domains, allowing clients configured to use it to access the decentralized web using standard DNS protocols. ## Overview [Section titled “Overview”](#overview) PKDNS makes public-key domains accessible to everyone by acting as a DNS resolver that understands both traditional ICANN domains and PKARR-based public-key domains. When you query a public-key domain (52-character z-base-32 encoded public key), PKDNS fetches the signed DNS records from the Mainline DHT, verifies the signature, and returns them to your browser or application—just like traditional DNS. ### Key Innovation [Section titled “Key Innovation”](#key-innovation) Instead of relying on ICANN registrars and centralized name servers, PKDNS enables: * **Self-sovereign domains**: Your Ed25519 public key IS your domain * **Censorship resistance**: Records are stored on the decentralized Mainline DHT * **No registration fees**: Publish records directly to the DHT * **Cryptographic verification**: PKARR records are signed and verifiable * **ICANN fallback**: Still resolves traditional domains seamlessly ## How It Works [Section titled “How It Works”](#how-it-works) ### Resolution Flow [Section titled “Resolution Flow”](#resolution-flow) 1. **User queries domain**: Browser or app requests `7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy` 2. **PKDNS recognizes format**: Recognizes a z-base-32 encoded public key in the domain name 3. **DHT lookup**: Queries the Mainline DHT for PKARR records associated with that public key 4. **Signature verification**: Validates that records were signed by the private key holder 5. **Cache and return**: Caches the verified records and returns DNS response to client 6. **ICANN fallback**: For traditional domains like `example.com`, forwards to the configured DNS resolver (default: 8.8.8.8) ### Public-Key Domain Format [Section titled “Public-Key Domain Format”](#public-key-domain-format) Public-key domains use z-base-32 encoded Ed25519 public keys: * **Length**: 52 characters (z-base-32 encoding) * **Example**: `7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy` * **Subdomains**: Support standard subdomain syntax (e.g., `blog.7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy`) ### Supported Record Types [Section titled “Supported Record Types”](#supported-record-types) PKDNS currently supports the most common DNS record types: * **A**: IPv4 addresses * **AAAA**: IPv6 addresses * **TXT**: Text records * **CNAME**: Canonical name records * **MX**: Mail exchange records For other record types, use bind9 or similar full-featured DNS servers. ## Features [Section titled “Features”](#features) ### DNS-over-HTTPS (DoH) [Section titled “DNS-over-HTTPS (DoH)”](#dns-over-https-doh) PKDNS supports DNS-over-HTTPS, enabling encrypted DNS queries from browsers: * Configure browser to use a PKDNS DoH endpoint * DNS queries to the selected DoH endpoint are encrypted over HTTPS * Hides those DNS queries from network observers; the resolver still sees them * Public DoH endpoints available in [servers.txt](https://github.com/pubky/pkdns/blob/master/servers.txt) Applications using ordinary DNS trust their chosen PKDNS resolver to return the records it verifies. ### Caching [Section titled “Caching”](#caching) Multi-layer caching for optimal performance: * **Response cache**: Caches responses for traditional DNS queries * **PKARR cache**: Stores verified PKARR records from DHT * **Configurable TTL**: Uses record TTLs within configured minimum and maximum bounds ### Rate Limiting [Section titled “Rate Limiting”](#rate-limiting) Built-in protection against abuse: * Per-IP rate limiting to prevent DoS attacks * Configurable thresholds and timeouts * Protects both the server and the DHT network ### Dynamic DNS (DynDNS) [Section titled “Dynamic DNS (DynDNS)”](#dynamic-dns-dyndns) Support for dynamic IP updates: * CLI tool for publishing updated A/AAAA records * Automated IP detection from multiple providers * Schedule periodic republishing to keep records available on the DHT * Perfect for Homeservers and dynamic IP addresses ### Hybrid Resolution [Section titled “Hybrid Resolution”](#hybrid-resolution) Seamlessly resolves both public-key domains and traditional domains: * Public-key domains → DHT lookup * ICANN domains → Configured DNS resolver * Configurable fallback DNS server * Configure your browser or system to use a PKDNS resolver ## Getting Started [Section titled “Getting Started”](#getting-started) ### Using Public Hosted Servers [Section titled “Using Public Hosted Servers”](#using-public-hosted-servers) The easiest way to try PKDNS: 1. **Choose a public server**: Check [servers.txt](https://github.com/pubky/pkdns/blob/master/servers.txt) for available DNS-over-HTTPS endpoints 2. **Configure your browser**: * Firefox: Settings → Network Settings → Enable DNS over HTTPS → Custom → Enter DoH URL * Chrome: Settings → Privacy and security → Security → Use secure DNS → Custom → Enter DoH URL * Edge: Settings → Privacy, search, and services → Security → Use secure DNS → Choose provider 3. **Test it works**: Visit For self-hosting, configuration, verification, and troubleshooting, see the [PKDNS README](https://github.com/pubky/pkdns/blob/master/README.md). ## Publishing Your Own Public-Key Domain [Section titled “Publishing Your Own Public-Key Domain”](#publishing-your-own-public-key-domain) Publishing a public-key domain involves generating a key pair, creating DNS records, and publishing them to the Mainline DHT. Records must be republished periodically to remain available. **⚠️ Security**: Store your private key securely. Anyone with the private key can publish records for your domain. See the [PKDNS README](https://github.com/pubky/pkdns/blob/master/README.md) and its linked publishing guide for the CLI workflow and dynamic IP updates. ## Use Cases [Section titled “Use Cases”](#use-cases) ### Self-Sovereign Web Publishing [Section titled “Self-Sovereign Web Publishing”](#self-sovereign-web-publishing) Publish websites without: * Domain registrars (no annual fees) * DNS hosting services (no third-party control) * Renewal requirements (keys don’t expire) * Registrar control over your domain (records are published on the DHT) ### Decentralized Applications [Section titled “Decentralized Applications”](#decentralized-applications) Enable dApps to use public-key addresses: * No smart contract required for DNS * Cryptographic verification built-in * Works with existing web infrastructure ### Development & Testing [Section titled “Development & Testing”](#development--testing) Instant domain names for development: * Generate test domains in seconds * No registration or setup fees * Update records without a registrar * Perfect for CI/CD pipelines ### Privacy-Focused Browsing [Section titled “Privacy-Focused Browsing”](#privacy-focused-browsing) Access censorship-resistant content: * Signatures prevent unauthorized changes to records; availability is not guaranteed * No central authority to pressure * Works through standard DNS protocols * Compatible with existing privacy tools ### Personal Identity [Section titled “Personal Identity”](#personal-identity) Use your public key as your digital identity: * Single domain across all services * Provable ownership via signatures * No platform lock-in * Portable across applications ## Limitations & Considerations [Section titled “Limitations & Considerations”](#limitations--considerations) ### Port 53 Requirement [Section titled “Port 53 Requirement”](#port-53-requirement) Running a DNS server on port 53 may require additional permissions or conflict with another DNS service. See the [PKDNS README](https://github.com/pubky/pkdns/blob/master/README.md) for setup and troubleshooting. ### DHT Ephemeral Storage [Section titled “DHT Ephemeral Storage”](#dht-ephemeral-storage) Records expire after a few hours and must be republished: * **Active domains**: Need periodic republishing (\~hourly) * **Automated solutions**: Schedule publishing with the DynDNS tooling * **Trade-off**: Prevents DHT pollution but requires maintenance ### Record Size Limit [Section titled “Record Size Limit”](#record-size-limit) PKARR packets must be ≤1000 bytes: * Limits number of records per domain * Use CNAME indirection for complex setups * Consider multiple public keys if needed ### Limited Record Type Support [Section titled “Limited Record Type Support”](#limited-record-type-support) Currently supports only: A, AAAA, TXT, CNAME, MX * Use bind9 for advanced record types (SRV, CAA, etc.) * May expand in future versions ### Browser Trailing Slash [Section titled “Browser Trailing Slash”](#browser-trailing-slash) Browsers may search instead of resolve domains: * Always append `./` to public-key domains in URL bar * Example: `http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy./` * Not needed for bookmarks or links ## Resources [Section titled “Resources”](#resources) * **Repository**: * **Releases**: * **Docker Image**: * **Public Servers**: [servers.txt](https://github.com/pubky/pkdns/blob/master/servers.txt) * **Zone Explorer**: * **Telegram Chat**: ### Documentation [Section titled “Documentation”](#documentation) * [DNS-over-HTTPS Setup](https://github.com/pubky/pkdns/blob/master/docs/dns-over-https.md) * [Dynamic DNS Configuration](https://github.com/pubky/pkdns/blob/master/docs/dyn-dns.md) * [Logging Configuration](https://github.com/pubky/pkdns/blob/master/docs/logging.md) * [Publishing Guide](https://medium.com/pubky/how-to-host-a-public-key-domain-website-v0-6-0-ubuntu-24-04-57e6f2cb6f77) ### Blog Posts [Section titled “Blog Posts”](#blog-posts) * [Mainline DHT Censorship Explained](https://medium.com/pubky/mainline-dht-censorship-explained-b62763db39cb) * [Public Key Domains Censorship Resistance Explained](https://medium.com/pubky/public-key-domains-censorship-resistance-explained-33d0333e6123) ### Related Tools [Section titled “Related Tools”](#related-tools) * **[pkarr](https://github.com/pubky/pkarr)**: Core PKARR library and specification * **[pkdns-digger](https://github.com/pubky/pkdns-digger)**: Web-based DNS record lookup tool for PKARR/PKDNS * **[pkdns-vanity](https://github.com/jphastings/pkdns-vanity)**: Generate vanity public-key domains # Private Storage Apps can use `/priv/` on a [Homeserver](/homeserver/) for non-public, user-specific data, such as preferences or drafts. This keeps app state attached to the user’s Pubky identity without publishing it for everyone to read. Private storage controls who can access the data; it does not encrypt it. The Homeserver can still read the contents unless the app encrypts them. ## Public and Private Storage [Section titled “Public and Private Storage”](#public-and-private-storage) Files under `/pub/` are publicly readable. Access to `/priv/` requires an authenticated session for the data owner’s identity, with capabilities covering the requested operation and path. This allows the owner and apps they authorize to access their private app data. `/priv/` alone does not provide sharing with other Pubky identities. Existing `/pub/` data remains public. Choosing `/priv/` for private storage does not retract previously published copies. ## Privacy and Trust [Section titled “Privacy and Trust”](#privacy-and-trust) Homeserver operators and privileged administrators can read unencrypted `/priv/` content. Apps that need confidentiality from the Homeserver must encrypt their data and manage the encryption keys themselves. See the [Security Model](/security-model/) for the trust placed in Homeservers. ## Documentation [Section titled “Documentation”](#documentation) * [Private Storage guide](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/docs/PRIVATE_STORAGE.md) — Behavior, access rules, and security considerations. * [SDK storage guide](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-sdk/README.md#storage-api-session--public) — Working with storage through the SDK. * [Client OpenAPI specification](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-homeserver/openapi-client.yml) — HTTP API contracts. # pubky.app [pubky.app](https://pubky.app) is a social application and reference implementation built on the [Pubky protocol](/overview/). People publish posts, follow one another, and discover content through feeds and tags. Developers can study how it combines user-controlled storage with an indexed social graph and a responsive web interface. ## Tags and perspectives [Section titled “Tags and perspectives”](#tags-and-perspectives) Tags are free-text labels people apply to profiles and posts, including those written by someone else. Each annotation records who applied the label and what it describes. A post might be tagged `tutorial` by one reader and `privacy` by another; those labels add context beyond a single like count. Perspectives are saved views of a feed, combining filters and presentation settings. They let readers return to a particular view of the social data. Tags and follow relationships provide the building blocks for the broader [semantic social graph](/semantic-social-graph/). Bookmarks are [public social records](https://github.com/pubky/pubky-app-specs/blob/main/SPEC.md#pubkyappbookmark). Treat bookmarked links as public data. ## Reference architecture [Section titled “Reference architecture”](#reference-architecture) The application separates publishing, indexing, and presentation: 1. **The frontend keeps data locally.** Its browser database holds records and feed data so the interface can show cached content and respond to user actions promptly. 2. **Users publish to Homeservers.** The [SDK](/sdk/) writes social records using the user’s authorization. The records follow [pubky-app-specs](/pubky-app-specs/) so other compatible apps can understand them. 3. **Nexus follows changes.** [Homeserver event feeds](/homeserver/#http-api) let [Nexus](/pubky-nexus/) discover updates, fetch public records, and index content and relationships across users. 4. **The frontend refreshes from Nexus.** Indexed results update the local cache, which the interface reads to present feeds, profiles, and search results. Local changes and indexed views do not become visible everywhere at once: the Homeserver write and subsequent Nexus indexing must complete. The [local-first design](https://github.com/pubky/pubky-app/blob/dev/docs/local-first.md) explains the read, write, and refresh behavior in detail. ## Building on the same data [Section titled “Building on the same data”](#building-on-the-same-data) Another app can reuse the social data without adopting pubky.app’s interface. It can read known records directly from Homeservers, query Nexus for indexed views, and contribute compatible records with the user’s authorization. For example, a topic reader could use existing profiles and follow relationships while presenting a different feed. [pubky-app-specs](/pubky-app-specs/) defines the shared data model that makes this interoperability possible. Its [Universal Tags](/pubky-app-specs/#universal-tags) let people label resources beyond pubky.app posts and profiles, such as an article tagged `tutorial`, so apps can discover both resources and the people who tagged them. Choose the pieces your app needs; the [app architecture guide](/app-architectures/) covers the alternatives. For development and integration, see: * [App repository](https://github.com/pubky/pubky-app): source code and development setup. * [Developer documentation](https://github.com/pubky/pubky-app/blob/dev/docs/README.md): architecture, data flow, local storage, PWA behavior, and configuration. # pubky-app-specs [pubky-app-specs](https://github.com/pubky/pubky-app-specs) defines shared data models for the Pubky ‘social’ app ecosystem, with [pubky.app](/pubky-app/) as the reference implementation. ## Overview [Section titled “Overview”](#overview) `pubky-app-specs` defines the canonical data schemas for social application data stored on Pubky [homeservers](/homeserver/). It provides validation rules, serialization logic, and type definitions used by both *Pubky apps* and the [Pubky Nexus](/pubky-nexus/) indexer to ensure interoperability with [pubky.app](/pubky-app/). Note that this is *only* required for Pubky ‘social’ apps: Pubky apps that read or write pubky.app social data, including profiles, posts and collections, follows, mutes, tags, bookmarks, and feeds. Pubky apps that do not rely on that social data should ignore `pubky-app-specs` and rely solely on their own application-specific schemas. ## Reusing social data [Section titled “Reusing social data”](#reusing-social-data) A third-party app can read compatible records directly from Homeservers through the [Pubky SDK](/sdk/), or query Nexus for indexed views across users. For example, a reading app could display a user’s profile and the articles shared by people they follow. The profile and follow relationships do not need to be recreated in a separate account system. To contribute compatible data, an app publishes records to the user’s Homeserver with the user’s authorization. Shared schemas let other clients interpret those records; each client can choose its own presentation and features. Using the schemas does not mean every client or indexer supports every record type or includes every user. ## Universal Tags [Section titled “Universal Tags”](#universal-tags) A Universal Tag expresses a named relation from a user to a resource. For example, Alice tags an article `tutorial`: | Part | Meaning | Example | | -------- | ------------------------- | ---------------------- | | Subject | Who applied the tag | Alice’s Pubky identity | | Relation | The tag’s label | `tutorial` | | Object | The resource being tagged | The article’s URI | The tag is stored on Alice’s Homeserver, separately from the article. It adds context without changing the resource and can describe resources beyond pubky.app posts and profiles. Another app could reuse the annotation to organize reading material. Labels express their authors’ assessments; apps choose whose annotations to include. Tags support discovery in both directions: * **Find resources through people:** show the articles Alice tagged `tutorial`. * **Find people through resources:** show who tagged an article `tutorial`, including people previously unknown to the app who use another app or Homeserver. These connections form part of the [semantic social graph](/semantic-social-graph/). Apps publish tag records to the user’s Homeserver with their authorization. They can read known annotations directly or query Nexus for indexed resources and taggers. See the [tag model](https://github.com/pubky/pubky-app-specs/blob/main/SPEC.md#pubkyapptag) for record formats and validation, and the [Nexus API reference](https://nexus.pubky.app/swagger-ui/) for supported queries. Nexus discovery is limited to the [users and Homeservers its instance indexes](https://github.com/pubky/pubky-nexus/blob/main/docs/decentralization.md): someone can be new to your app while already known to its indexer. ## Specifications and libraries [Section titled “Specifications and libraries”](#specifications-and-libraries) * [Data model specification](https://github.com/pubky/pubky-app-specs/blob/main/SPEC.md): schemas, paths, and validation rules. * [Library README](https://github.com/pubky/pubky-app-specs): Rust usage and links to the API reference. * [JavaScript and TypeScript guide](https://github.com/pubky/pubky-app-specs/blob/main/pkg/README.md): npm package usage. # Pubky Backup **[Pubky Backup](https://github.com/pubky/pubky-backup)** is the desktop backup app for maintaining a local copy of published Homeserver data. It helps preserve access to your files if your hosting provider becomes unavailable or you decide to leave. ## What a backup protects [Section titled “What a backup protects”](#what-a-backup-protects) * **Identity key backup:** lets you recover control of your identity. Manage this separately through [Pubky Ring](/pubky-ring/). * **Synchronized data copy:** keeps a local copy of your published Homeserver data. * **Snapshot:** preserves a point-in-time copy, rather than only following the current published state. Keeping both your keys and your data makes [credible exit](/credible-exit/) more practical. Pubky Backup does not provide automatic failover or restoration to another Homeserver; a local copy is one part of preparing to move, not a complete migration workflow. See the [Pubky Backup README](https://github.com/pubky/pubky-backup/blob/main/README.md) for downloads and setup. The [core library documentation](https://github.com/pubky/pubky-backup/blob/main/src-tauri/pubky-backup-core/README.md) describes synchronization and snapshots. # Pubky Docker **[Pubky Docker](https://github.com/pubky/pubky-docker)** runs a full local Pubky environment, including Pubky Homeserver, Homegate, and the Pubky ‘social’ components Pubky Nexus and pubky.app. Use it to develop an app against a disposable local testnet, or to test changes across the social application’s components. The [Developer Guide](/developer-guide/) uses it to provide a Homeserver for your first app. You do not need to run the full stack for every SDK integration. Warning Pubky Docker is intended for local development, testing, and experimentation—not production hosting. ## Testnet Architecture [Section titled “Testnet Architecture”](#testnet-architecture) The stack includes a local DHT and PKARR relay for discovery, an HTTP relay for authentication, and Homegate for signup. A simple SDK app needs the Homeserver and local protocol services; the social stack also provides Nexus and pubky.app. The following simplified diagram shows the default local testnet topology: For authorization during local development, the [Ring Simulator](https://simulator.pubkyring.app/) can act as the authenticator. The [authentication overview](/authentication/) explains that flow. For setup, configuration, and running specific component revisions, see the [Pubky Docker README](https://github.com/pubky/pubky-docker/blob/main/Readme.md). Check running component versions with [`./list-component-versions.sh`](https://github.com/pubky/pubky-docker/blob/main/list-component-versions.sh). # Pubky Explorer **Pubky Explorer** is a web-based file browser for exploring public data stored on [Pubky Homeservers](/homeserver/). It is useful for inspecting the files behind an app’s view of that data. **Live Application**: Enter a public key or a Pubky URI to browse its public directories and inspect individual files. For app developers, this helps answer concrete questions: was a record written, is it at the expected path, and what does its JSON contain? Explorer shows stored files, while [Nexus](/pubky-nexus/) builds indexed views across users. A file can exist on a Homeserver before it appears in an app’s indexed view. Explorer is therefore useful when separating a storage problem from an indexing or display problem. Use the [testnet Explorer](https://explorer.pubky.app/testnet/) to inspect data created on the local testnet. See the [Pubky Explorer README](https://github.com/pubky/pubky-explorer/blob/main/README.md) for the usage demonstration, testnet connection, and development setup. # Pubky Nexus [Pubky Nexus](https://github.com/pubky/pubky-nexus) indexes public social data from [Homeservers](/homeserver/) using the [pubky-app-specs](/pubky-app-specs/) data model and serves it through an API for [pubky.app](/pubky-app/) and compatible clients. It is an application service, not a requirement for every Pubky app. ## When Nexus is useful [Section titled “When Nexus is useful”](#when-nexus-is-useful) Use Nexus when your app needs views across social records, such as feeds, search results, replies, or tags and follow relationships. It lets the client request an indexed result instead of locating and combining each record itself. The [semantic social graph](/semantic-social-graph/) explains how these relationships support contextual views. Applications publish changes to users’ Homeservers. Nexus watches Homeserver event feeds, fetches relevant public records, and updates its indexes. Clients then query those indexes. The [pubky.app reference architecture](/pubky-app/#reference-architecture) shows how this works alongside a browser’s local cache. Nexus does not write a user’s posts on their behalf, and its index does not replace Homeserver storage. A missing API result can mean that the instance has not indexed the record; it does not by itself mean the original record is absent. Instance coverage and indexing delay matter when building a client. ## Using or running Nexus [Section titled “Using or running Nexus”](#using-or-running-nexus) For implementation and operation, see: * [Nexus README](https://github.com/pubky/pubky-nexus): architecture, setup, configuration, migrations, and testing. * [Swagger UI](https://nexus.pubky.app/swagger-ui/) and [OpenAPI specification (JSON)](https://nexus.pubky.app/api-docs/v0/openapi.json): endpoints and response schemas for the public instance. * [Indexing coverage and Homeserver configuration](https://github.com/pubky/pubky-nexus/blob/main/docs/decentralization.md): how an instance selects Homeservers and users to index. ## Exploring the graph with Nexus Scout [Section titled “Exploring the graph with Nexus Scout”](#exploring-the-graph-with-nexus-scout) [Nexus Scout](https://nexus-scout.pubky.app/) lets AI agents and developers run read-only Cypher queries over the Pubky social graph and receive JSON results. The public instance uses a periodically refreshed replica, so results can lag behind the Nexus API. See the [agent guide](https://nexus-scout.pubky.app/llms.txt) for schema discovery, query examples, and limits. # Pubky Noise [Pubky Noise](https://github.com/pubky/pubky-noise) is a library under development for encrypted communication through [Homeservers](/homeserver/). It lets applications exchange encrypted messages through hosted storage without requiring both participants to be online together. It is relevant to developers building private communication between Pubky identities, including the [Paykit](/paykit/) work. It is a building block for applications, rather than a standalone messaging app. See the [Pubky Noise README](https://github.com/pubky/pubky-noise/blob/master/README.md) for its transport and session model, and the [Rust API reference](https://docs.rs/pubky-noise/latest/pubky_noise/) for the library interface. # Pubky Passport > Create and recover a Pubky identity with Google and sign in to Pubky apps from your browser. Pubky Passport is a browser-based signer for Pubky. It lets you create an identity and approve sign-in requests from Pubky apps without installing a mobile app. It plays a similar role to [Pubky Ring](/pubky-ring/), which manages identities on your phone. [Open Pubky Passport](https://passport.pubky.app/) and choose **Continue with Google**. Passport creates your Pubky identity or restores the one backed up for that Google account. When an app asks to sign in, you review its requested permissions before approving access. ## Identity and recovery [Section titled “Identity and recovery”](#identity-and-recovery) Passport creates and uses your secret key in the browser, with an encrypted backup in your Google Drive. Recovering that backup requires both Google access and the Passport service; neither can recover it alone. You can download a password-protected recovery file or move your identity to Pubky Ring. Do this before detaching Google: detachment deletes the Drive backups and leaves your identity in the browser, making independent recovery essential if you lose that browser’s data. See the [Passport README](https://github.com/pubky/pubky-passport/blob/main/README.md) for details. Developers adding Passport sign-in should follow the [integration guide](https://github.com/pubky/pubky-passport/blob/main/docs/integration.md). # Pubky Ring Pubky Ring is the key manager and identity application for the Pubky ecosystem. It holds your identity keys and lets you approve access requests from apps. An app requests permission to use your identity and access particular data on your [Homeserver](/homeserver/). You review that request in Ring, which issues a grant for the approved access. This lets an app work with your data without receiving your identity’s private key. See [authentication](/authentication/) for how the app, Ring, and Homeserver fit together. Visit the [Pubky Ring website](https://pubkyring.app/) for installs. ## Protecting your identity [Section titled “Protecting your identity”](#protecting-your-identity) Keep a separate backup of your identity key using Ring’s backup options. Identity recovery and [backing up published data](/pubky-backup/) serve different purposes: recovering a key does not recover data lost by a Homeserver. ## For app developers [Section titled “For app developers”](#for-app-developers) Use the [Pubky SDK](/sdk/) to request app authorization. The [Ring Simulator](https://simulator.pubkyring.app/) is an experimental browser authenticator for local testnet development; the [Developer Guide](/developer-guide/) shows it alongside a working app. For Ring’s development setup and implementation, see the [Pubky Ring README](https://github.com/pubky/pubky-ring/blob/main/README.md). # Resources A curated directory of websites, applications, repositories, packages, and community channels across the Pubky ecosystem. *** ## Websites [Section titled “Websites”](#websites) * [pubky.org](https://pubky.org/) — Official Pubky documentation * [pubky.tech](https://pubky.tech/) — Awesome list: Ecosystem directory * [synonym.to](https://synonym.to/) — Synonym (company behind Pubky) * [pkdns.net](https://pkdns.net/) — PKDNS public resolver * [stats.pubky.app](https://stats.pubky.app/) — Pubky metrics dashboard ## AI Resources [Section titled “AI Resources”](#ai-resources) * Pubky documentation for LLMs: [overview](https://pubky.org/llms.txt), [page index](https://pubky.org/llms-small.txt), and [full documentation](https://pubky.org/llms-full.txt) * [Pubky agent skills](https://github.com/pubky/agent-skills) — Maintained skills for AI coding tools working with Pubky * [Nexus Scout](https://nexus-scout.pubky.app/) — Read-only query gateway for AI agents exploring the Pubky social graph ([agent guide](https://nexus-scout.pubky.app/llms.txt), [source](https://github.com/pubky/nexus-scout)) * Context7 resources to keep LLMs up to date: [pubky.org `llms.txt`](https://context7.com/llmstxt/pubky_llms_txt), [Pubky Homeserver repo](https://context7.com/pubky/pubky-homeserver), [Pubky Nexus repo](https://context7.com/pubky/pubky-nexus), [PKARR repo](https://context7.com/pubky/pkarr), [PKDNS repo](https://context7.com/pubky/pkdns), [pubky-app-specs repo](https://context7.com/pubky/pubky-app-specs), [Pubky Docker repo](https://context7.com/pubky/pubky-docker), and [Mainline repo](https://context7.com/pubky/mainline) * DeepWiki (AI-generated codebase wikis with LLM chat): [pubky-homeserver](https://deepwiki.com/pubky/pubky-homeserver) and [pubky-nexus](https://deepwiki.com/pubky/pubky-nexus) ## Live Applications [Section titled “Live Applications”](#live-applications) * [pubky.app](https://pubky.app/) — Decentralized social media app ([source](https://github.com/pubky/pubky-app)) * [mypubky.com](https://mypubky.com/) — Shareable bio page for your profile, links, posts, and payment options ([source](https://github.com/pubky/mypubky)) * [pubkyring.app](https://pubkyring.app/) — Pubky Ring key manager ([source](https://github.com/pubky/pubky-ring)) * [passport.pubky.app](https://passport.pubky.app/) — Pubky Passport browser signer with Google sign-in and encrypted recovery backups ([source](https://github.com/pubky/pubky-passport)) * [payky.app](https://payky.app/) — Payment profile for sharing payment details in one link * [mapky.app](https://mapky.app/) — Social map with user-owned location-based data * [explorer.pubky.app](https://explorer.pubky.app/) — Pubky data explorer ([local testnet instance](https://explorer.pubky.app/testnet/), [source](https://github.com/pubky/pubky-explorer)) * [simulator.pubkyring.app](https://simulator.pubkyring.app/) — Browser tool for signing in to Pubky apps on a local testnet ([source](https://github.com/pubky/pubky-ring-simulator)) * [pubky.observer](https://pubky.observer/) — Pubky data explorer * [playground.pubky.org](https://playground.pubky.org/) — Interactive demo: same user-owned data powering multiple apps with different layouts ## Core Repositories [Section titled “Core Repositories”](#core-repositories) All under [github.com/pubky](https://github.com/pubky): * [pubky-homeserver](https://github.com/pubky/pubky-homeserver) — Pubky Homeserver and protocol implementation * [homeserver-dashboard](https://github.com/pubky/homeserver-dashboard) — Admin dashboard for Pubky homeservers * [pubky-backup](https://github.com/pubky/pubky-backup) — Desktop app for local backups of published Homeserver data * [pubky-nexus](https://github.com/pubky/pubky-nexus) — Aggregator and indexer for pubky.app * [pubky-app-templates](https://github.com/pubky/pubky-app-templates) — Starter templates for building Pubky apps ([demos](https://pubky.github.io/pubky-app-templates/)) * [pubky-core-ffi](https://github.com/pubky/pubky-core-ffi) — Pubky Mobile SDK * [pkdns](https://github.com/pubky/pkdns) — DNS server resolving pkarr self-sovereign domains * [pkdns-resolver-extension](https://github.com/pubky/pkdns-resolver-extension) — Browser extension for PKDNS resolution * [homegate](https://github.com/pubky/homegate) — Gateway service * [pubky-docker](https://github.com/pubky/pubky-docker) — Local Pubky stack for development and experimentation on testnet * [umbrel-app-store](https://github.com/pubky/umbrel-app-store) — Install your own Pubky Homeserver on your Umbrel node * [pubky-cli](https://github.com/pubky/pubky-cli) — Command-line companion for interacting with Pubky homeservers * [atomicity](https://github.com/pubky/atomicity) — Proposal for a P2P credit system ## Community Projects [Section titled “Community Projects”](#community-projects) * [Uploadky](https://uploadky.vercel.app/) — File sharing with files stored on your Pubky homeserver ([source](https://github.com/PastaGringo/uploadky)) * [TimechainWiki](https://timechain.wiki/) — Bitcoin encyclopedia with reader annotations synced through Nostr or Pubky ([source](https://github.com/RadVladdy/timechain-wiki)) * [Loopky](https://github.com/jvsena42/loopky) — Flashcards with spaced repetition and decks stored on Pubky ([Android releases](https://github.com/jvsena42/loopky/releases/latest)) * [Chessky](https://chessky-ten.vercel.app/) — Multiplayer chess across homeservers, with no indexer or other backend ([source](https://github.com/gcomte/chessky)) * [Ghostly](https://ghostly.tools/) — Encrypted chat and file sharing built on PKARR ([source](https://github.com/MiguelMedeiros/ghostly)) * [Pubky Pulse](https://pubkypulse.com/) — Experimental app observability with SDKs and MCP access for AI agents ([source](https://github.com/Jasonvdb/pubky-pulse)) * [eventky.app](https://eventky.app/) — Event management on Pubky ([source](https://github.com/gillohner/eventky/)) * [tagky](https://github.com/PastaGringo/tagky) — Automated tagging using LLM * [Pubky Watcher Canvas](https://eventky.app/watcher-canvas/) — Multiplayer pixel canvas demonstrating Pubky event streams ([source](https://github.com/gillohner/pubky-watcher-canvas)) * [pubky-mint](https://github.com/ok300/pubky-mint) — RSS-like way to browse your follows’ Pubky activity * [vanity-pubky](https://github.com/coreyphillips/vanity-pubky) — Vanity key generator * [pubky-messenger](https://github.com/coreyphillips/pubky-messenger) — Rust library for private messaging over Pubky * [pkdns-vanity](https://github.com/jphastings/pkdns-vanity) — PKDNS vanity key generator ## Package Registries [Section titled “Package Registries”](#package-registries) * Pubky SDK — [Rust crate](https://crates.io/crates/pubky) and [JavaScript/TypeScript npm package](https://www.npmjs.com/package/@synonymdev/pubky) * [pkarr](https://crates.io/crates/pkarr) — Public Key Addressable Resource Records ([npm](https://www.npmjs.com/package/@synonymdev/pkarr), [source](https://github.com/pubky/pkarr)) * [pubky-app-specs](https://crates.io/crates/pubky-app-specs) - Shared data models and validation for Pubky apps ([npm](https://www.npmjs.com/package/pubky-app-specs), [source](https://github.com/pubky/pubky-app-specs)) * [mainline](https://crates.io/crates/mainline) — BitTorrent Mainline DHT implementation ([source](https://github.com/pubky/mainline)) * [@synonymdev/react-native-pubky](https://www.npmjs.com/package/@synonymdev/react-native-pubky) — React Native SDK ([source](https://github.com/pubky/react-native-pubky)) ## Community Channels [Section titled “Community Channels”](#community-channels) * [Pubky on pubky.app](https://pubky.app/profile/ihaqcthsdbk751sxctk849bdr7yz7a934qen5gmpcbwcur49i97y) — Official Pubky profile * [Telegram: pubkycore](https://t.me/pubkycore) — Community chat * [Discord](https://discord.gg/DxTBJXvJxn) — Developer community * [X/Twitter: @getpubky](https://x.com/getpubky) — Official updates * [YouTube](https://www.youtube.com/channel/UCyNruUjynpzvQXNTxbJBLmg) — Tutorials, demos, roundtables, presentations * [Medium: pubky](https://medium.com/pubky) — Blog posts and articles ## Videos & Talks [Section titled “Videos & Talks”](#videos--talks) * [Introducing Pubky Collections](https://www.youtube.com/watch?v=RLcYgW8rg-Y) (08/10/2026) — Save, organize, and share Pubky posts * [Payky: One Link, Every Way to Pay You](https://www.youtube.com/watch?v=qrYJCxmD8e8) (06/16/2026) — Create and share a payment profile using Pubky Ring * [MyPubky: Your Link-in-Bio, Without the Lock-In](https://www.youtube.com/watch?v=PUXGgTyrY20) (06/09/2026) — Build a portable profile with links and payment options * [Why the Internet Is Broken by Design and How Pubky Changes the Model](https://www.youtube.com/watch?v=3cUTp9jKMX8) (03/03/2026) — Introduction to key-based identity and portable data * [Pubky Introduction — BTC Prague 2025](https://www.youtube.com/watch?v=hPxLz4VQpKk) (08/01/2025) — Introduction to Pubky * [The Atomic Economy](https://www.youtube.com/watch?v=X3ogGRuv7qY) (08/29/2025) — The Atomic Economy talk * [Pubky Community Call #3](https://www.youtube.com/watch?v=1eMYq-WJiNg) (02/17/2026) — Community call * [PKDNS Explainer](https://youtu.be/GJHMlyKUoWY) (10/26/2024) — How PKDNS works * [Pubky Explorer Explainer](https://youtu.be/qESmEhDNl4E) (10/27/2024) — Using the Pubky Explorer * [Nuh @ Thank God for Nostr podcast](https://fountain.fm/episode/HXQpcOdQU9Tnxa9BQO2v) (11/19/2024) — Podcast interview ## Philosophical Foundations [Section titled “Philosophical Foundations”](#philosophical-foundations) Essays, talks, and resources exploring the vision, principles, and philosophy behind Pubky and the Atomic Economy. ### Essays & Manifestos [Section titled “Essays & Manifestos”](#essays--manifestos) * [The Age of Social Intelligence](https://pubky.app/post/gujx6qd8ksydh1makdphd3bxu351d9b8waqka8hfg6q7hnqkxexo/0034WADK62XRG) (03/29/2026) — Why social intelligence is the missing layer as AI scales, and the Semantic Social Graph as open cognitive infrastructure * [Nostr vs Pubky: The Basics](https://pubky.app/post/gujx6qd8ksydh1makdphd3bxu351d9b8waqka8hfg6q7hnqkxexo/0034M0VM2ETV0) — John Carvalho compares the protocols’ approaches to identity, discovery, and data ownership * [How to Fix Spam, Bots, and AI Slop on the World Wide Web](https://howtofixtheweb.com) (03/16/2026) — The Semantic Social Graph as the real algorithm to replace centralized feed curation * [Opening Pubky](https://medium.com/pubky/opening-pubky-4bdca7dc4c77) (01/30/2026) — The public launch, portable identity, and building apps around user-owned data * [Building Blocks for the Atomic Economy](https://medium.com/pubky/building-blocks-for-the-atomic-economy-aeeba8ccde8e) (10/17/2025) — How each technical primitive maps to a philosophical principle of sovereignty * [The Atomic Economy: Reclaiming Society from the Inside Out](https://medium.com/pubky/the-atomic-economy-reclaiming-society-from-the-inside-out-574504dfe326) (04/24/2025) — Extending Bitcoin’s revolution into identity, trust, and coordination * [Corporate vs. Community-Led Open Source Development](https://medium.com/pubky/corporate-vs-community-led-open-source-development-491a03da58e6) (11/07/2024) — Cathedral vs. Bazaar: why effective freedom tools require intentional design * [Pubky: The Next Web](https://medium.com/pubky/pubky-the-next-web-3287b35408f1) (11/05/2024) — The founding manifesto: diagnosing the web’s failures and proposing “You Are the Algorithm” * [Introducing Pubky: Rebooting the Web with User Sovereignty at the Core](https://medium.com/@synonym_to/pubky-launch-260f36ba8fe3) (10/25/2024) — Synonym’s official launch statement on digital autonomy and open-source sovereignty * [Welcome to the Atomic Economy](https://bitcoinerrorlog.substack.com/p/welcome-to-the-atomic-economy) (12/04/2021) — Early articulation of the Atomic Economy vision: webs of trust replacing centralized gatekeepers ### Bitcoin & Trust Philosophy [Section titled “Bitcoin & Trust Philosophy”](#bitcoin--trust-philosophy) * [You Cannot Store “Lifetime”](https://pubky.app/post/gujx6qd8ksydh1makdphd3bxu351d9b8waqka8hfg6q7hnqkxexo/0035JX1KFXSRG) — Subjective value, reputation, and the limits of money as a store of value * [How to Think About Data on Bitcoin](https://bitcoinerrorlog.medium.com/how-to-think-about-data-on-bitcoin-a5a80442ef68) (05/01/2025) — Blockspace as a free market, and why social data doesn’t belong on-chain * [Fiat Will Never Die, Long Live Bitcoin](https://bitcoinerrorlog.substack.com/p/fiat-will-never-die-long-live-bitcoin) (02/10/2021) — Units of trust vs. units of work: a nuanced framework for money and credit * [Who secures Bitcoin?](https://medium.com/bitcoinerrorlog/who-secures-bitcoin-95b19bbcda3c) (10/26/2019) — Individual nodes as the ultimate guarantors of consensus, not miners or developers ### Talks & Interviews [Section titled “Talks & Interviews”](#talks--interviews) * [The Next Web — Bitcoin Audible Chat 124](https://bitcoin-audible.castos.com/episodes/chat-124-the-next-web-with-john-carvalho) (01/15/2025) — Deep dive into Pubky’s philosophy, credible exit, and pragmatic decentralization * [Defending Bitcoin — HackerNoon](https://hackernoon.com/defending-bitcoin-with-john-carvalho-17f549b5e059) (01/21/2019) — Origin story: defending decentralization at the protocol level, the thread that leads to Pubky * [AMA — Stacker News](https://stacker.news/items/17771) (04/03/2022) — Extended Q\&A revealing first-principles thinking: “Primitives are all that matter” ### Third-Party Analysis [Section titled “Third-Party Analysis”](#third-party-analysis) * [What is Pubky? — Bitfinex Blog](https://blog.bitfinex.com/education/what-is-pubky/) (08/01/2025) — Accessible overview of Pubky’s philosophical and technical foundations * [Synonym Launches Architecture For A Self-Sovereign Economy — Bitcoin Magazine](https://bitcoinmagazine.com/business/synonym-launches-architecture-for-self-sovereign-economy-around-bitcoin) (11/16/2021) — Synonym’s founding announcement: replacing the legacy economy with self-sovereign alternatives # Pubky SDK The Pubky SDK handles Homeserver discovery, authentication, and storage access for applications. Start with the guide for your platform; each implementation maintains its own API and integration instructions. | Platform | Guide | API reference | | ----------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | JavaScript / TypeScript | [SDK README](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-sdk/bindings/js/pkg/README.md) | [TypeDoc](https://pubky.github.io/pubky-homeserver/js-sdk-typedoc/) | | Rust | [SDK README](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-sdk/README.md) | [Rust API](https://docs.rs/pubky/latest/pubky/) | | React Native | [React Native SDK](https://github.com/pubky/react-native-pubky) | See the package documentation | | Swift / Kotlin | [Pubky Core Mobile SDK](https://github.com/pubky/pubky-core-ffi) | See the bindings documentation | ## How It Works [Section titled “How It Works”](#how-it-works) The main SDK types follow the steps an application takes: | Type | Role in an application | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Pubky` | The client used to discover Homeservers and start authenticated or public operations. | | `PubkySigner` | Holds an identity key for operations that require it, such as creating a development account. Third-party apps normally request access through an external authenticator. | | `PubkySession` | Represents authenticated access to a user’s Homeserver, with the permissions granted to the app. | | `SessionStorage` | Reads and writes files within that session’s permissions. | | `PublicStorage` | Reads public data without signing in. | For example, an app can use a session to save a user’s own data and public storage to read another user’s published profile. [Authentication](/authentication/) explains how an app obtains access without taking custody of the identity key. Refer to your platform’s documentation for its supported types and behavior. ## Homeserver connections [Section titled “Homeserver connections”](#homeserver-connections) Native Rust clients prefer [PubkyTLS](/glossary/#pubkytls), which verifies the Homeserver’s public key directly. If PKARR advertises an ICANN HTTPS endpoint, the SDK can use it when the direct endpoint is absent or fails its TCP reachability check. Browser clients reach public Homeservers through the ICANN HTTPS endpoint. ICANN connections use standard HTTPS certificate validation, so their trust depends on the conventional domain and certificate authorities. The native fallback concerns TCP reachability: a later TLS or request failure does not trigger it. See the SDK’s [transport selection and tests](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-sdk/src/client/http_targets/native.rs) for the exact behavior. Native clients behind HTTPS proxies also have [reported discovery and routing limitations](https://github.com/pubky/pubky-homeserver/issues/657). For public connection setup, follow the [Homeserver Deployment Guide](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/docs/DEPLOY.md). ## Storage Locking [Section titled “Storage Locking”](#storage-locking) Storage locks help applications coordinate updates to the same file on Homeservers that support WebDAV storage locks. Applications opt in through the Rust SDK’s `SessionStorage` helpers; ordinary storage operations do not acquire locks automatically. The JavaScript bindings do not expose these helpers. The application manages the lock lifecycle and retries; the SDK handles requests and lock tokens. The Homeserver keeps a lock alive during a write made with it. See the [Rust storage-lock example](https://docs.rs/pubky/latest/pubky/struct.StorageLock.html#example) and [lock API](https://docs.rs/pubky/latest/pubky/struct.SessionStorage.html#method.lock) for usage and renewal behavior, and the Locking section of the [client OpenAPI specification](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-homeserver/openapi-client.yml) for protocol guarantees and limitations. ## Build and explore [Section titled “Build and explore”](#build-and-explore) Follow the [Developer Guide](/developer-guide/) for a self-contained walkthrough that writes and reads data on a local testnet. The [examples directory](https://github.com/pubky/pubky-homeserver/tree/v0.14.0/examples) covers further workflows, including authorization, persistence, and event streams. Use the API references above for method signatures, return values, and errors. For integrations that need raw HTTP, see the [Homeserver API references](/homeserver/#http-api). For client resource limits, see the SDK’s [error-body limits](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-sdk/README.md#error-body-limits) and [event-stream limits](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/pubky-sdk/README.md#event-stream-limits). # Security Model Pubky separates identity from hosting, but applications still depend on key custody, Homeserver behavior, and network availability. [Credible exit](/credible-exit/) reduces dependence on a provider; it does not remove these trust boundaries. ## Key custody [Section titled “Key custody”](#key-custody) Anyone holding an identity’s private key can act as that identity. Losing every copy makes the identity unrecoverable. Changing Homeservers or revoking app sessions does not make a compromised identity key safe again. Use an authenticator you trust and request only the app permissions you need. See [Authentication](/authentication/) for the integration guides. ## Homeserver trust [Section titled “Homeserver trust”](#homeserver-trust) Data under `/pub/` is public. Access to `/priv/` requires a session for the storage owner’s identity and permissions covering the requested access. This is access control, not encryption: Homeserver administrators can still read and write tenant data. See [Private Storage](/private-storage/) for an overview and the [Private Storage guide](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/docs/PRIVATE_STORAGE.md) for access rules. Applications can encrypt content before uploading it and manage decryption keys themselves. The Homeserver then stores ciphertext, while access patterns and data sizes remain visible. `/priv/` adds access control; it does not provide encryption or key management. A signed discovery record does not prove that stored application content is authentic. Applications must account for an operator altering, withholding, or deleting data, and observing access patterns. Keeping independent copies helps preserve data if a provider becomes unavailable; it does not by itself detect tampering. ## Discovery and availability [Section titled “Discovery and availability”](#discovery-and-availability) PKARR records can expire, lookups can fail, and caches can delay a hosting change. A new discovery record does not recover missing files or guarantee immediate reachability. See the [PKARR trade-offs](https://github.com/pubky/pkarr/blob/main/docs/introduction.md#the-trade-offs). ## Transport Security [Section titled “Transport Security”](#transport-security) Transport encryption protects a connection, not data from the Homeserver handling it. The [SDK connection overview](/sdk/#homeserver-connections) explains platform differences and fallback to conventional HTTPS. The [Homeserver Deployment Guide](https://github.com/pubky/pubky-homeserver/blob/v0.14.0/docs/DEPLOY.md) covers the supported connection and deployment options; the [PKARR TLS specification](https://github.com/pubky/pkarr/blob/main/design/tls.md) describes public-key verification. # Semantic Social Graph A semantic social graph goes beyond simple follow/friend connections. Every link between users and content is stored as a labeled edge, so the graph preserves not just *that* two things are connected but *how*. ### How It Works in Pubky [Section titled “How It Works in Pubky”](#how-it-works-in-pubky) Pubky users produce labeled edges through ordinary activity: following a peer, tagging a post, bookmarking a link, publishing a reply or repost, organizing posts into a collection. Labels on tags add explicit context, while the edge type preserves what action connected two nodes. Nexus indexes this data and lets clients query it along social and semantic dimensions. Posts can be retrieved by follow network, by tag, by content kind, or sorted by time. Web-of-trust views traverse follows up to three hops deep, and tag-based views narrow results further. For example, showing only authors tagged `rust-dev` by the observer or by peers in their follow network. These building blocks let clients construct contextual views without a universal feed algorithm. One view might show a `rust-dev` domain feed from trusted connections, another a chronological stream from direct follows.  ### Beyond Social: A Substrate for Intelligence [Section titled “Beyond Social: A Substrate for Intelligence”](#beyond-social-a-substrate-for-intelligence) A semantic social graph isn’t only useful for people. Because it accumulates contextual meaning from ordinary activity, it becomes a rich layer that AI can operate over. It can surface connections between peers and topics, identify recurring community structures, or recommend content paths that no single user would have mapped out. For a deeper exploration of this idea, see [Social Intelligence Is Not Artificial](https://pubky.app/post/gujx6qd8ksydh1makdphd3bxu351d9b8waqka8hfg6q7hnqkxexo/0035MMN9XV790) (blog post).