Pubky Core - Frequently Asked Questions
Overview & Philosophy
Section titled “Overview & Philosophy”Q1. What is Pubky, and why was it developed?
Section titled “Q1. What is Pubky, and why was it developed?”Pubky is a new kind of web built on public-key domains instead of usernames or rented accounts. Your public key becomes your self-sovereign domain. Pubky uses PKDNS, which runs on the Mainline DHT.
Pubky introduces a semantic social graph driven by tags and trust, not ads and opaque feeds.
It was created to counter:
- Poisoned algorithms
- Censorship
- Walled gardens and data harvesting
Q2. Why is Pubky critical for a free-market society?
Section titled “Q2. Why is Pubky critical for a free-market society?”Because it removes gatekeepers by design. Identities are user-owned; hosting/indexing are interchangeable.
Q3. What’s the relationship between Pubky and Slashtags?
Section titled “Q3. What’s the relationship between Pubky and Slashtags?”Slashtags was a previous Synonym project using Hypercore instead of PKDNS and Homeservers. It shared similar goals.
Q4. Is Pubky open source?
Section titled “Q4. Is Pubky open source?”Yes. Under the MIT license. View on GitHub
Q5. What is Pubky Core?
Section titled “Q5. What is Pubky Core?”Pubky Core is the foundational infrastructure for Pubky - an open protocol combining censorship-resistant public-key DNS (PKARR) with conventional web technologies. It includes the protocol specification, a production-ready Homeserver implementation, and SDKs in multiple languages (Rust, JavaScript, iOS, Android). See the Pubky Core Overview for details.
Q6. How do I start building on Pubky?
Section titled “Q6. How do I start building on Pubky?”Install the Pubky SDK for your platform (Rust: cargo add pubky, JavaScript: npm install @synonymdev/pubky), follow the official documentation, and explore the examples in the repository. The SDK provides client libraries for authentication, data storage, and Homeserver interaction.
Architecture & Resolution (PKARR, PKDNS, DHT)
Section titled “Architecture & Resolution (PKARR, PKDNS, DHT)”Q7. What is PKARR?
Section titled “Q7. What is PKARR?”“Public Key Addressable Resource Records” your signed DNS-like records published on the DHT.
Q8. What is PKDNS?
Section titled “Q8. What is PKDNS?”PKDNS is a DNS server that resolves public-key domains by fetching PKARR records from the Mainline DHT. It enables self-sovereign, censorship-resistant domain names while still supporting traditional ICANN domains. Anyone can run a PKDNS server or use public instances to access the decentralized web. See PKDNS for setup guides and publishing instructions.
Q9. How does Pubky compare to DNS?
Section titled “Q9. How does Pubky compare to DNS?”Pubky replaces ICANN with your public key. You publish and resolve records yourself.
Q10. What format does PKDNS use?
Section titled “Q10. What format does PKDNS use?”DNS-style RR, signed under your key, shared via the Mainline DHT.
Q11. Does it support CNAME/SRV/HTTPS indirection?
Section titled “Q11. Does it support CNAME/SRV/HTTPS indirection?”Yes, with caveats, avoid deep/brittle recursion.
Q12. Are DHTs part of the clearnet?
Section titled “Q12. Are DHTs part of the clearnet?”Yes, via UDP. Web browsers require bridges due to lack of raw UDP support.
Q13. How can browsers interact with the DHT?
Section titled “Q13. How can browsers interact with the DHT?”Via HTTP bridges, resolvers like PKDNS, or native helpers.
Q14. Do others need PKDNS to connect to Pubky sites?
Section titled “Q14. Do others need PKDNS to connect to Pubky sites?”No special setup in the Pubky App. Other apps can use public PKDNS instances or self-hosted PKDNS resolvers. Many public DNS-over-HTTPS endpoints are available—see the PKDNS documentation for a list of hosted servers.
Homeservers & Hosting
Section titled “Homeservers & Hosting”Q15. What are Homeservers?
Section titled “Q15. What are Homeservers?”Regular web servers that host your content. Anyone can run one.
Q16. Can I run one at home?
Section titled “Q16. Can I run one at home?”Yes. You’ll need port forwarding or tunneling if behind NAT.
Q17. How can I explore data on a Homeserver?
Section titled “Q17. How can I explore data on a Homeserver?”Use Pubky Explorer (explorer.pubky.app), a web-based file browser for public Pubky data. Enter any public key or path (e.g., pubky://your-key/pub/pubky.app/profile.json) to browse files and directories stored on Homeservers. Features include keyboard navigation, file preview, directory traversal, and shareable URLs.
Q18. How can I run the complete Pubky stack locally for development?
Section titled “Q18. How can I run the complete Pubky stack locally for development?”Use Pubky Docker, a Docker Compose orchestration that runs the entire Pubky Social stack with one command. It includes PKARR relay, Homeserver (with PostgreSQL), Pubky Nexus (with Neo4j and Redis), and the Pubky App frontend—all preconfigured and ready to use. Clone the repository, configure .env for testnet or mainnet, and run docker compose up -d. Perfect for testing integrations, developing custom frontends, or learning how all components interact. See Pubky Docker for setup instructions.
Q19. When should I use Pubky Docker vs SDK libraries?
Section titled “Q19. When should I use Pubky Docker vs SDK libraries?”Use the SDK libraries (@synonymdev/pubky for JavaScript, pubky for Rust) when building applications that interact with Pubky. Only use Pubky Docker if you need to run the full stack locally to experiment with Pubky Nexus, test custom social frontends, debug cross-component issues, or learn the complete architecture. For most app development, the SDK libraries connected to public infrastructure are simpler and faster.
Q20. How is redundancy handled?
Section titled “Q20. How is redundancy handled?”Use mirrors in PKARR. Clients pick healthy ones.
Q21. Does it support load balancing?
Section titled “Q21. Does it support load balancing?”Yes, for reads. Writes go to a single primary.
Q22. Can Homeservers sign my data?
Section titled “Q22. Can Homeservers sign my data?”No. Signing is done by the client.
Q23. How to self-host a Homeserver?
Section titled “Q23. How to self-host a Homeserver?”Deploy the package/container, configure HTTPS, publish in PKARR.
Q24. What are the storage limits?
Section titled “Q24. What are the storage limits?”Synonym’s public Homeserver currently has: 1GB per user, 10MB per file. These are temporary limits during beta. Self-hosted Homeservers can configure their own limits.
Q25. Can Pubky integrate with Tor?
Section titled “Q25. Can Pubky integrate with Tor?”Yes, via .onion endpoints, but it’s not yet tested officially.
Identity, Keys & Security
Section titled “Identity, Keys & Security”Q26. How are keys managed?
Section titled “Q26. How are keys managed?”With Pubky Ring, the identity manager app for Pubky. Pubky Ring is a native mobile app (iOS/Android) that securely manages your pubkys (public keys), handles device sessions, publishes identity via PKARR, and authorizes apps—all without accounts or passwords.
Q27. Does Pubky support key rotation?
Section titled “Q27. Does Pubky support key rotation?”Not yet standardized, possible manually via PKARR fallback logic.
Q28. What if my key is lost or hacked?
Section titled “Q28. What if my key is lost or hacked?”Migrate to a new key, update PKARR, and alert your graph.
Q29. Can I use the same seed as Nostr?
Section titled “Q29. Can I use the same seed as Nostr?”Yes, but most users prefer separate secrets due to risk.
Q30. How does identity trust work?
Section titled “Q30. How does identity trust work?”No global authority, trust is built through social graph, tags, and interaction.
Publishing, Privacy & Moderation
Section titled “Publishing, Privacy & Moderation”Q31. How do I publish content?
Section titled “Q31. How do I publish content?”Host it on a Homeserver and link it in your PKARR.
Q32. Is Pubky suitable for private sharing?
Section titled “Q32. Is Pubky suitable for private sharing?”Not yet. All current use assumes public content.
Q33. Where does moderation happen?
Section titled “Q33. Where does moderation happen?”At the Homeserver and indexer level (e.g., Pubky Nexus).
Q34. What is Pubky Nexus?
Section titled “Q34. What is Pubky Nexus?”Pubky Nexus is the production indexing and aggregation service that powers Pubky App. It transforms data from multiple Homeservers into a high-performance social graph API with sub-millisecond response times, enabling features like feeds, search, recommendations, and real-time notifications. Explore the live API.
Q35. Can I run my own Nexus instance?
Section titled “Q35. Can I run my own Nexus instance?”Yes! Nexus is open source and can be self-hosted. This allows organizations to run custom instances with their own content filtering policies, moderation rules, and Homeserver selections. See the Pubky Nexus documentation for deployment details.
Q36. How does Pubky resist spam?
Section titled “Q36. How does Pubky resist spam?”Via CAPTCHAs, rate-limits, invites, and graph distance rules.
Q37. How does Paykit fit in?
Section titled “Q37. How does Paykit fit in?”Paykit is a payment protocol (work in progress) built on Pubky that aims to enable payment discovery and coordination across multiple methods (Bitcoin, Lightning, etc.). See Client Features for the full feature list.
⚠️ Note: Paykit is NOT production-ready and the protocol is subject to significant changes.
Q38. Is Paykit ready for use?
Section titled “Q38. Is Paykit ready for use?”No. Paykit is currently a work in progress under active development. The protocol specification, security model, and implementation are all subject to breaking changes. Do not use it for production applications.
Q39. What payment methods will Paykit support?
Section titled “Q39. What payment methods will Paykit support?”The initial focus is on Bitcoin on-chain and Lightning Network. The protocol is designed to be extensible to other methods (Liquid, Fedimint, ecash, etc.), but these are not yet implemented or specified.
Q40. Where is Paykit being tested?
Section titled “Q40. Where is Paykit being tested?”Paykit is being integrated into Bitkit (iOS and Android) to validate the protocol design and identify issues before stabilization. These integrations serve as testbeds, not production features.
Q41. When will Paykit be production-ready?
Section titled “Q41. When will Paykit be production-ready?”There is no set timeline. Significant work remains on protocol stabilization, security auditing, cross-platform testing, and interoperability validation before Paykit can be recommended for production use.
Q42. Can Pubky do everything Nostr can?
Section titled “Q42. Can Pubky do everything Nostr can?”Yes, and more. Pubky includes DHT-based discovery and semantic tagging.
Interoperability, Ecosystem & Onboarding
Section titled “Interoperability, Ecosystem & Onboarding”Q43. Pubky vs IPFS
Section titled “Q43. Pubky vs IPFS”Pubky is identity-first and mutable; IPFS is content-first and immutable.
Q44. Pubky vs Nostr
Section titled “Q44. Pubky vs Nostr”Pubky uses Homeservers and PKARR for hosting; Nostr uses relays. Pubky has semantic discovery.
Q45. Pubky vs Bluesky
Section titled “Q45. Pubky vs Bluesky”Pubky is key-native and decentralized. Bluesky relies on DID directories and centralized servers.
Q46. Pubky vs Farcaster
Section titled “Q46. Pubky vs Farcaster”Pubky = key-owned + off-chain. Farcaster = chain-anchored + relay-dependent.
Q47. Will Pubky integrate with other protocols?
Section titled “Q47. Will Pubky integrate with other protocols?”Bridges are possible, but not currently in development.
Q48. Are there mobile apps?
Section titled “Q48. Are there mobile apps?”Yes!
- Pubky Ring: Native mobile app (iOS/Android) - Your keychain for the Pubky ecosystem. Manages identities, authorizes apps, and handles sessions. Self-custodial with no accounts required.
- Pubky.app: Progressive Web App (PWA) - Social publishing application
- More apps welcome from the community!
Q49. What is Pubky Ring?
Section titled “Q49. What is Pubky Ring?”Pubky Ring is the key manager app for the Pubky ecosystem. It’s a native mobile app (iOS/Android) that securely manages your pubkys (public keys), authorizes applications, manages sessions, and handles key derivation—all self-custodially with no accounts, passwords, or tracking. Think of it as your keychain for decentralized identity.
Q50. How do users join Pubky App?
Section titled “Q50. How do users join Pubky App?”Homeservers can implement signup verification to prevent spam while preserving privacy. Homegate is an open-source service that provides two verification methods: SMS codes (rate-limited per phone number) and Lightning Network payments. Homeserver operators can use Homegate, implement custom verification, or allow open signups. See Homegate for deployment and integration details.
Q51. Indexer vs Homeserver?
Section titled “Q51. Indexer vs Homeserver?”- Homeserver = stores user data
- Indexer = enables search/feeds across Homeservers
Q52. How do I ensure my app is compatible with Pubky App?
Section titled “Q52. How do I ensure my app is compatible with Pubky App?”Follow the pubky-app-specs data model specification. This defines the structure and validation rules for users, posts, tags, bookmarks, follows, and feeds. The spec is available as an npm package (JavaScript/TypeScript) and Rust crates. Note: Currently v0.4.0 in rapid development; v1 will mark the first stable, long-term support version.
Q53. What’s the status of Pubky App development?
Section titled “Q53. What’s the status of Pubky App development?”The Pubky App client (pubky.app) is live and under active development at github.com/pubky/pubky-app. Developers building compatible clients should use pubky-app-specs (or the Rust crate) as the authoritative specification.
Q54. Can I contribute to Pubky App?
Section titled “Q54. Can I contribute to Pubky App?”Yes! The pubky-app repository is under active development and welcomes contributions. If you want to build a compatible social client, use the pubky-app-specs specification as your foundation.
Operations, Resilience & Scale
Section titled “Operations, Resilience & Scale”Q55. How do I migrate providers?
Section titled “Q55. How do I migrate providers?”Add mirror → update PKARR → let caches sync → retire old host.
Q56. What if Synonym disappears?
Section titled “Q56. What if Synonym disappears?”Nothing breaks. Your key, data, and graph are yours.
Q57. What if my ISP censors my Homeserver?
Section titled “Q57. What if my ISP censors my Homeserver?”Switch hosts, use Tor/VPN, republish PKARR.
Q58. How often does PKARR update?
Section titled “Q58. How often does PKARR update?”Periodically, every few hours is typical. See republishing research for details.
Q59. What if I spam the DHT?
Section titled “Q59. What if I spam the DHT?”You’ll be rate-limited. Publish sensibly.
Q60. Does DHT scale globally?
Section titled “Q60. Does DHT scale globally?”Yes. Mainline DHT already does, Pubky’s usage is lightweight.
Q61. Why do some say Nostr needs a DHT?
Section titled “Q61. Why do some say Nostr needs a DHT?”Because relay-only networks don’t scale easily without coordination.
Q62. What about private data in Pubky?
Section titled “Q62. What about private data in Pubky?”Short-term: Pubky Noise-based encrypted channels for private peer-to-peer communication.
Long-term: Cryptree-style systems and further R&D.
Q63. What is Pubky Noise?
Section titled “Q63. What is Pubky Noise?”Pubky Noise is a Noise Protocol implementation that provides encrypted communication channels for the Pubky ecosystem. It uses the IK handshake pattern for mutual authentication and forward secrecy. Currently used by Paykit for private payment negotiation, it can also support other applications requiring secure peer-to-peer communication. Work in progress - not production-ready yet.
Q64. How does Pubky Noise differ from the Noise Protocol?
Section titled “Q64. How does Pubky Noise differ from the Noise Protocol?”Pubky Noise is a specific implementation of the Noise Protocol Framework adapted for the Pubky ecosystem. It integrates with Pubky’s Ed25519 identity system, derives X25519 encryption keys automatically, and publishes endpoints to Homeserver directories for peer discovery. It provides platform-specific bindings (iOS, Android, Web, CLI) and handles session management.