Search

SearchSearch

Getting Started

Jan 30, 20266 min read

Getting Started with Pubky

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.

flowchart TD
    Start[Want to use Pubky?] --> Q1{Are you a developer?}
    Q1 -->|Yes| Dev[Install SDK]
    Q1 -->|No| User[Download Pubky Ring]
    Dev --> DevStack[Run Pubky Docker]
    DevStack --> DevBuild[Build Your App]
    DevBuild --> DevDeploy[Deploy to Production]
    User --> UserCreate[Create Identity]
    UserCreate --> UserApp[Try pubky.app]
    UserApp --> UserExplore[Explore Your Data]

For Users: Experience Decentralized Social Media

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)

  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

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

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

For Developers: Build on Pubky

Step 1: Install the SDK

Choose your platform and install the Pubky SDK:

Rust:

cargo add pubky

JavaScript/TypeScript (Web & Node.js):

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

React Native:

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

Use Pubky Docker to run the complete Pubky ecosystem locally:

# Clone the repository
git clone https://github.com/pubky/pubky-docker
cd pubky-docker
 
# Configure environment (testnet recommended for development)
cp .env.example .env
# Edit .env to set ENVIRONMENT=testnet
 
# Start the stack
docker compose up -d

This gives you:

  • PKARR relay (port 6881)
  • Homeserver with PostgreSQL (port 4173)
  • Pubky Nexus with Neo4j & Redis (port 8000)
  • Pubky App frontend (port 5173)

Alternative: Run just a homeserver:

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

Step 3: Build Your First App

Quick Example (JavaScript):

import { Pubky } from '@synonymdev/pubky';
 
// Create client
const pubky = await Pubky.create();
 
// Generate a new identity (signup)
const { publicKey, secretKey } = await pubky.signUp();
console.log('Your pubky:', publicKey);
 
// Store data
await pubky.put('/pub/myapp/profile', JSON.stringify({
  name: "Alice",
  bio: "Building on Pubky!",
  avatar: "https://example.com/avatar.jpg"
}));
 
// Retrieve data
const profile = await pubky.get('/pub/myapp/profile');
console.log('Profile:', JSON.parse(profile));
 
// List directory
const files = await pubky.list('/pub/myapp/');
console.log('Files:', files);
 
// Sign out
await pubky.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

Learn from working examples:

Social App (Pubky App Specs):

CLI Tool:

Simple Examples:

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

Deploy a Homeserver:

  1. Set up a server (VPS, cloud, or self-hosted)
  2. Configure HTTPS (required)
  3. Deploy homeserver: 
    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

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

Documentation

Technical

Tools

Community

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

Graph View