Skip to content

Developer Guide

Build on Pubky if you want your users to control their identities and publish data to a Homeserver they choose, rather than to a data server dictated by and tied to whichever app they use. Pubky’s architecture preserves their freedom to move between apps and Homeservers.

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. Start PostgreSQL and configure database_url first; see the Homeserver documentation for details:

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

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
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 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 (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

Section titled “Next Steps”

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: 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!