Skip to content

Getting Started

Welcome to Pubky! This guide will help you get started whether you’re a user looking to try decentralized social media or a developer building on the Pubky protocol.

For Users: Experience Decentralized Social Media

Section titled “For Users: Experience Decentralized Social Media”

Step 1: Download Pubky Ring

Section titled “Step 1: Download Pubky Ring”

Pubky Ring is your key manager for the Pubky ecosystem. It securely stores your identity and authorizes apps.

  • iOS: Download from the App Store
  • Android: Download from Google Play

🔗 Official Repository

Step 2: Create Your First Pubky (Identity)

Section titled “Step 2: Create Your First Pubky (Identity)”
  1. Open Pubky Ring
  2. Follow the onboarding flow to generate your key pair
  3. Save your recovery phrase securely - this is your master backup
  4. Your public key (pubky) is now your permanent identity!

Important: Your pubky looks like: z4e8s17cou9qmuwen8p1556jzhf1wktmzo6ijsfnri9c4hnrdfty

Step 3: Try Pubky App

Section titled “Step 3: Try Pubky App”

Visit pubky.app - a decentralized social media platform built on Pubky.

  1. Click “Sign In” or “Create Account”
  2. Authorize Pubky App through Pubky Ring
  3. Create your profile
  4. Start posting, following, and exploring!

What makes it different:

  • You own your data (stored on Homeservers)
  • No algorithm controls your feed
  • You can switch to different apps without losing your content
  • True censorship resistance

Step 4: Explore Your Data

Section titled “Step 4: Explore Your Data”

Use Pubky Explorer (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’ve 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

Next Steps for Users

Section titled “Next Steps for Users”

For Developers: Build on Pubky

Section titled “For Developers: Build on Pubky”

Step 1: Install the SDK

Section titled “Step 1: Install the SDK”

Choose your platform and install the Pubky SDK:

Rust:

Terminal window
cargo add pubky

JavaScript/TypeScript (Web & Node.js):

Terminal window
npm install @synonymdev/pubky
# or
yarn add @synonymdev/pubky

React Native:

Terminal window
npm install @synonymdev/react-native-pubky
cd ios && pod install  # iOS only

iOS/Android Native: See SDK Documentation for UniFFI bindings via pubky-core-ffi.

📚 Resources:

Step 2: Run Local Development Stack

Section titled “Step 2: Run Local Development Stack”

Pubky Docker provides a one-command local setup of the full Pubky Social stack (PKARR relay, Homeserver, Nexus, and the App frontend).

See the Pubky Docker documentation for setup instructions, port mappings, and configuration options.

Alternative: Run just a Homeserver:

Terminal window
git clone https://github.com/pubky/pubky-core
cd pubky-core/pubky-homeserver
cargo run

Step 3: Build Your First App

Section titled “Step 3: Build Your First App”

Quick Example (JavaScript):

import { Pubky, Keypair } from "@synonymdev/pubky";


// Create client and signer
const pubky = new Pubky();
const signer = pubky.signer(Keypair.random());


// Sign up (pass signup token for gated homeservers, null for open/testnet)
const session = await signer.signup(homeserverPk, null);
console.log("Your pubky:", signer.publicKey.z32());


// Store data
await session.storage.putJson("/pub/myapp/profile", {
  name: "Alice",
  bio: "Building on Pubky!",
  avatar: "https://example.com/avatar.jpg",
});


// Retrieve data
const profile = await session.storage.getJson("/pub/myapp/profile");
console.log("Profile:", profile);


// List directory
const files = await session.storage.list("/pub/myapp/");
console.log("Files:", files);


// Sign out
await session.signout();

Key concepts:

  • Data is stored per public key on Homeservers
  • Path structure: /pub/app-name/path for public data
  • All operations use standard HTTP/HTTPS
  • Authentication via cryptographic signatures

📖 Full SDK guide: SDK Documentation

Step 4: Explore Example Apps

Section titled “Step 4: Explore Example Apps”

Learn from working examples:

Social App (Pubky App Specs):

CLI Tool:

Simple Examples:

Step 5: Integrate Advanced Features

Section titled “Step 5: Integrate Advanced Features”

Use Pubky Nexus for Social Features:

If building a social app, leverage Pubky Nexus for:

  • Real-time feeds and timelines
  • Search and discovery
  • User recommendations
  • Notifications
// Query Nexus API
const response = await fetch('https://nexus.pubky.app/v0/feeds/global');
const posts = await response.json();

📊 Nexus API Docs

Add Payments (WIP):

Paykit protocol (work in progress) will enable:

  • Payment discovery via public keys
  • Bitcoin/Lightning integration
  • Subscriptions and monetization

Add Encryption (WIP):

Pubky Noise (work in progress) provides:

  • Encrypted peer-to-peer channels
  • Private messaging
  • Secure data sharing

Step 6: Deploy to Production

Section titled “Step 6: Deploy to Production”

Deploy a Homeserver:

  1. Set up a server (VPS, cloud, or self-hosted)
  2. Configure HTTPS (required)
  3. Deploy Homeserver:
    Terminal window
    docker build --build-arg TARGETARCH=x86_64 -t pubky:core .
    docker run --network=host -it pubky:core
  4. Publish Homeserver location to PKARR
  5. Configure rate limiting and moderation

📘 Guide: Homeserver Documentation

Signup Verification:

Use Homegate to prevent spam:

  • SMS verification (rate-limited per phone)
  • Lightning payment verification
  • Open-source and self-hostable

DNS Resolution:

Run a PKDNS server for your users:

  • Resolves public-key domains
  • Supports traditional DNS
  • DoH/DoT encryption

Next Steps for Developers

Section titled “Next Steps for Developers”

Common First Questions

Section titled “Common First Questions”

Q: Do users need to download Pubky Ring to use my app? A: Currently yes for secure key management, though apps can implement their own key storage. Pubky Ring provides the best UX for multi-app identity.

Q: Can I use Pubky without running my own Homeserver? A: Yes! Users can choose any public Homeserver provider. You can host your own or use existing providers.

Q: Is Pubky compatible with Nostr/Bluesky/etc? A: Not directly. Pubky uses a different architecture (Homeservers + PKARR vs relays/PDSs). See Comparisons for details.

Q: How do I handle user authentication? A: The SDK handles it automatically via signature-based auth. No passwords, OAuth, or tokens needed. See Authentication.

Q: Can I build private apps? A: Currently Pubky is optimized for public data. Private/encrypted features are coming via Pubky Noise.

Q: How do I make money? A: Several models work: Homeserver hosting, indexing services (like Nexus), premium features, or payments via Paykit (WIP).

Resources

Section titled “Resources”

Documentation

Section titled “Documentation”

Technical

Section titled “Technical”

Tools

Section titled “Tools”

Community

Section titled “Community”

Ready to build the decentralized web? Start with the SDK!