Skip to content

Homeserver

The Pubky network allows multiple, independent data stores, known as “Homeservers.” This improves censorship-resistance and prevents any single entity from controlling the flow of information, or locking people & data in as a walled garden.

Homeservers are meant to represent a primary place to retrieve data from a specific PKARR public key, but the user can redefine the location of their Homeserver at will by updating their PKARR record in the Mainline DHT.

Architecture

Section titled “Architecture”

The Homeserver implementation consists of several components: the main HTTP API server (supporting both ICANN HTTP and Pubky TLS), an admin server, a Prometheus metrics server, and republishers that keep user and server keys alive on the DHT.

See the repository for API details and configuration.

Public vs Private Data

Section titled “Public vs Private Data”

Current implementations only support public, unencrypted data. Encrypted data and guarded (access-controlled) data are planned — see Security Model for the trust implications.

Event Stream

Section titled “Event Stream”

Homeservers expose event streams for clients to sync data changes:

  • GET /events-stream — SSE real-time stream with user and path filters. Primary event API, used by clients to subscribe to specific users on third-party homeservers without processing unwanted traffic
  • GET /events/ — Paginated event feed for all users on the homeserver (cursor-based, 1000 events per batch)

Transport Security

Section titled “Transport Security”

Homeservers expose two endpoints: a PubkyTLS endpoint (TLS with Raw Public Keys, RFC 7250) and an ICANN HTTP endpoint intended to sit behind a reverse proxy with standard X.509 TLS.

Native Pubky clients connect via PubkyTLS; browsers and legacy clients connect via the ICANN domain. See Transport Security for details.

User Data Control and Credible Exit

Section titled “User Data Control and Credible Exit”
  • The current network is being bootstrapped by Synonym’s first Homeserver — over time, more independent Homeserver operators and Pubky applications are needed for the network to fully decentralize
  • Anyone can run their own Homeserver and set their own terms
  • Homeserver operators can use Homegate for signup verification, implementing SMS or Lightning Network verification to prevent spam while preserving user privacy
  • For true credible exit, users should maintain local backups via Pubky Backup. Homeserver mirroring is planned but not yet implemented
  • Users can migrate to a new Homeserver at any time by moving their data and updating their PKARR record

See Security Model for the full trust analysis and failure recovery scenarios.

Running a Homeserver

Section titled “Running a Homeserver”

Note: Production deployment guides are not yet available. Easy deployment packages (Umbrel, apt, docker, start9) are under development.

For local development and testing:

Terminal window
cargo run -p pubky-homeserver

To spin up an ephemeral testnet:

Terminal window
cargo run -p pubky-testnet

Embedded Postgres

Section titled “Embedded Postgres”

Since v0.7.0, the testnet supports an optional embedded Postgres mode via the embedded-postgres feature flag. This allows fully self-contained test environments without requiring an external database:

Terminal window
cargo run -p pubky-testnet --features embedded-postgres

The examples use embedded Postgres by default. For programmatic use:

use pubky_testnet::EphemeralTestnetBuilder;


let testnet = EphemeralTestnetBuilder::new()
    .with_embedded_postgres()
    .build()
    .await?;