Imagine a world where apps don't need servers. Where your data lives with you, not in some far-away data center. Where you can talk to your friends directly, without going through Facebook or Google first. That's what Holepunch enables.

What You'll Learn

By the end of this guide, you'll understand:

✅ What peer-to-peer (P2P) computing really means
✅ How Holepunch makes P2P easy for developers
✅ The core building blocks (Hypercore, Hyperswarm, etc.)
✅ Why this matters for privacy, security, and freedom
✅ How to start building P2P applications yourself

The Problem: Today's Internet

To understand why Holepunch matters, let's first understand how today's internet works.

The Client-Server Model

When you use most apps today, here's what happens:

    ┌─────────┐          ┌─────────────────┐          ┌─────────┐
    │  You    │ ───────► │    SERVER       │ ◄──────  │ Friend  │
    │(Client) │          │  (The Middleman)│          │(Client) │
    └─────────┘          └─────────────────┘          └─────────┘
    
    Your message goes: You → Server → Friend

Example: Sending a text message

You type a message on WhatsApp
It goes to Facebook's servers
Facebook's servers send it to your friend
Your friend downloads it from Facebook's servers

The problem? The server sees everything, controls everything, and if it's down, no one can communicate.

Problems with This Approach

Problem	What It Means	Real Impact
Censorship	Central authority can block content	Governments can silence people
Privacy	Server sees all your data	Advertisers track everything
Single Point of Failure	If server dies, app dies	Service outages affect millions
Latency	Data goes through middleman	Slower for everyone
Cost	Companies pay for servers	You indirectly pay too

The Solution: Peer-to-Peer

What if instead of going through a server, you could talk directly to your friend?

    ┌─────────┐          ┌─────────┐
    │  You    │ ◄──────► │ Friend  │
    │ (Peer)  │  Direct  │ (Peer)  │
    └─────────┘          └─────────┘
    
    Your message goes: You → Friend (no middleman!)

This is Peer-to-Peer (P2P).

Benefits of P2P

✅ No Middleman - You talk directly to who you want
✅ Censorship Resistant - No single point to block
✅ Private - Nobody sees your messages except the recipient
✅ Always On - Works as long as at least two people are connected
✅ Faster - No detour through a server
✅ Cheaper - No server costs to pay

What is Holepunch?

Holepunch is a toolkit that makes building P2P applications actually practical for developers.

Think of it like this:

HTTP is the language the web uses for client-server
Hyperswarm is the language P2P apps use to talk to each other
Holepunch provides all the tools in one nice package

The Holepunch Team Built:

A database that syncs automatically (Hypercore)
A way to find peers without a server (Hyperswarm)
A file system that lives on everyone's computers (Hyperdrive)
A tiny JavaScript engine for phones (Bare)
A way to install apps from peers (Pear)

And many more modules that have been documented in this repository - from data structures like Hyperbee, HyperDB, and Autobase, to networking tools like HyperDHT and UDX, all the way to security primitives and platform components.

All open source. All designed to work together.

Real-World Examples

Here's what you can build with Holepunch:

Keet - P2P Chat & Video Calls

End-to-end encrypted messaging, voice & video calls
No phone number, email, or sign-up required
Your identity is a 24-word seed phrase (like a crypto wallet)
Unlimited file sharing - send any size directly device-to-device
Works on desktop and mobile, syncs across devices
100% free, no ads, no servers - just direct P2P

PearPass - Passwords That Stay With You

Your passwords live on your devices
Share with family without sending passwords over the internet
No "cloud" to get hacked

Hyperbeam - Send Files Directly

Send gigabyte files to friends
Goes directly from your computer to theirs
No Dropbox, no Google Drive

Hypershell - SSH Over P2P

Access remote computers without setting up servers
All traffic encrypted and direct

How This Guide Works

We've organized this guide in phases:

Phase 1: Understand the basics (what & why)
Phase 2: Core concepts (how it works)
Phase 3: Networking (connecting peers)
Phase 4: Data structures (building blocks)
Phase 5: The platform (running apps)
Phase 6: Real examples
Phase 7: Build your first app
Phase 8: Advanced topics

Start from the beginning if you're new to P2P. Jump around if you just need to understand specific parts.

Prerequisites

This guide is designed for:

Anyone curious about P2P technology
Developers who want to learn Holepunch
Non-technical people who want to understand why this matters

You don't need to know:

Advanced cryptography
Distributed systems
Network programming

We explain everything in plain English with lots of examples.

Quick Start: Your First P2P App

Want to see how easy it is? Here's a complete P2P chat app in about 15 lines of code:

// Just 15 lines to build a P2P chat!
const Hypercore = require('hypercore')
const Hyperswarm = require('hyperswarm')

const core = new Hypercore('./chat-room')
const swarm = new Hyperswarm()

// Join the chat room
swarm.join(core.discoveryKey, { server: true, client: true })

// When someone connects, sync data
swarm.on('connection', conn => core.replicate(conn))

// Send a message
await core.append(Buffer.from('Hello from P2P World!'))

// Read all messages
for (let i = 0; i < core.length; i++) {
  console.log((await core.get(i)).toString())
}

That's it! Run this code and you have a working P2P chat application.

What's Next?

Ready to dive in? Start your journey:

Phase 1: Understanding P2P Basics - Learn what P2P is and why it matters
Phase 2: Core Concepts - Understand how it works under the hood
Phase 3: Networking - Learn how peers find each other
Phase 4: Data Structures - Hypercore, Hyperbee, HyperDB, and more
Phase 5: The Platform - Bare runtime and Pear distribution
Phase 6: Real Examples - See working P2P applications
Phase 7: Building Your First App - Build a complete P2P application
Phase 8: Advanced Topics - Performance, scaling, and production

Or jump straight to:

Glossary - Look up any term you encounter
Quick Reference - Key commands and patterns

Summary

Term	What It Means
P2P	Peer-to-Peer - computers talking directly
Holepunch	The toolkit for building P2P apps
Server	A computer that mediates between users
Peer	A computer in the P2P network
Client	Your device (computer, phone)

This guide is part of the Holepunch ecosystem. For more technical details, see the main KB documentation.