diff --git a/images/how-iroh-works/connect-by-key.svg b/images/how-iroh-works/connect-by-key.svg
new file mode 100644
index 0000000..f686cee
--- /dev/null
+++ b/images/how-iroh-works/connect-by-key.svg
@@ -0,0 +1,112 @@
+
diff --git a/images/how-iroh-works/embedding-phone.svg b/images/how-iroh-works/embedding-phone.svg
new file mode 100644
index 0000000..df4cb51
--- /dev/null
+++ b/images/how-iroh-works/embedding-phone.svg
@@ -0,0 +1,121 @@
+
diff --git a/images/how-iroh-works/endpoint-startup.svg b/images/how-iroh-works/endpoint-startup.svg
new file mode 100644
index 0000000..2e8c23a
--- /dev/null
+++ b/images/how-iroh-works/endpoint-startup.svg
@@ -0,0 +1,137 @@
+
diff --git a/images/how-iroh-works/hole-punching-lan.svg b/images/how-iroh-works/hole-punching-lan.svg
new file mode 100644
index 0000000..c62dfaa
--- /dev/null
+++ b/images/how-iroh-works/hole-punching-lan.svg
@@ -0,0 +1,156 @@
+
diff --git a/images/how-iroh-works/hole-punching.svg b/images/how-iroh-works/hole-punching.svg
new file mode 100644
index 0000000..d4757f1
--- /dev/null
+++ b/images/how-iroh-works/hole-punching.svg
@@ -0,0 +1,257 @@
+
diff --git a/images/how-iroh-works/publish-relay-dht.svg b/images/how-iroh-works/publish-relay-dht.svg
new file mode 100644
index 0000000..cdf67db
--- /dev/null
+++ b/images/how-iroh-works/publish-relay-dht.svg
@@ -0,0 +1,149 @@
+
diff --git a/images/how-iroh-works/publish-relay.svg b/images/how-iroh-works/publish-relay.svg
new file mode 100644
index 0000000..ca079a7
--- /dev/null
+++ b/images/how-iroh-works/publish-relay.svg
@@ -0,0 +1,125 @@
+
diff --git a/images/how-iroh-works/routing-moves.svg b/images/how-iroh-works/routing-moves.svg
new file mode 100644
index 0000000..357ba06
--- /dev/null
+++ b/images/how-iroh-works/routing-moves.svg
@@ -0,0 +1,148 @@
+
diff --git a/what-is-iroh.mdx b/what-is-iroh.mdx
index 2333e9b..a36c91a 100644
--- a/what-is-iroh.mdx
+++ b/what-is-iroh.mdx
@@ -2,9 +2,17 @@
title: "What is iroh?"
---
-iroh is a modular networking stack written in Rust. It provides
-the building blocks to create applications that can communicate
-using fast, cheap, and reliable connections.
+iroh is a modular networking stack written in Rust. It provides the building
+blocks to create applications that can communicate using fast, cheap, and
+reliable connections.
+
+It's a lightweight native library meant to be embedded directly into your
+application — in Rust, or in C, C++, Swift, Python, JavaScript, and Kotlin
+through [our bindings](/languages).
+
+
+
+
## Core features
- **Fast**: iroh enables direct connections between
@@ -32,6 +40,120 @@ and data synchronization. Any kind of CRDT or OT sync protocol can be integrated
services](/protocols/rpc), and [streaming data](/protocols/streaming) with
iroh's communication protocols.
+## How iroh works
+
+iroh's job comes down to two promises: you can reach a peer no matter where it
+is, and the connection you get is the best one available.
+
+### Connect by key
+
+Every iroh [endpoint](/concepts/endpoints) is identified by a cryptographic key.
+That key — not an IP address — is the address. It lets you connect to a peer no
+matter where it is, even as its network location changes underneath it.
+
+
+
+
+
+### Reliable connections
+
+We make sure you get a connection whenever possible, and that it's as fast as
+possible. When network conditions change, iroh immediately reacts and switches
+to the new best path — transparently, without dropping the connection.
+
+
+
+
+
+Now that we've seen *what* iroh does, here's *how*.
+
+### Library and relays
+
+There are two pieces to the system:
+
+- **The iroh library** runs inside your application. It provides the API to
+ create endpoints, connect to other endpoints, and open connections and data
+ streams.
+- **[Relays](/concepts/relays)** run in the background on publicly reachable
+ servers. They help endpoints find each other and establish direct
+ connections, and relay data as a fallback when a direct connection isn't
+ possible.
+
+### Endpoint startup
+
+An iroh endpoint is configured with a set of relays — the rate-limited public
+relays operated by number 0, relays from iroh services, or self-hosted ones.
+iroh works fine with a single relay, but works best with relays in every region
+where your users are.
+
+On startup, an endpoint sends
+[QAD](https://datatracker.ietf.org/doc/draft-ietf-quic-address-discovery/)
+probes to all configured relays. This does two things: it learns the endpoint's
+own public IP address, and it learns which relay is closest by latency. The
+closest relay becomes the **home relay**, and the endpoint keeps a secure
+WebSocket connection open to it.
+
+
+
+
+
+### Finding peers
+
+When there are multiple relays, Alice needs to know which relay to use to reach
+Bob. iroh offers two ways to publish and look up that information.
+
+#### DNS-based lookup
+
+Out of the box, iroh uses DNS. Bob publishes a signed record with his home relay
+to a DNS server operated by number 0 via an HTTPS `PUT`. Anyone who wants to
+reach Bob resolves that record with a DNS or HTTPS query. See
+[DNS address lookup](/connecting/dns-address-lookup).
+
+
+
+
+
+#### Mainline DHT lookup
+
+DNS works in most cases, but sometimes you want something fully peer-to-peer.
+For that, iroh offers an optional lookup over the Mainline DHT: it publishes the
+exact same signed record using the
+[BEP 44](https://www.bittorrent.org/beps/bep_0044.html) extension. See
+[DHT address lookup](/connecting/dht-address-lookup).
+
+
+
+
+
+### Direct connections
+
+So far we've described a system where endpoints can always talk — but all data
+flows through the relays. That adds latency, limits throughput, and costs the
+relay operator money. Making connections fast and direct is arguably the most
+complex part of the system.
+
+#### Hole punching
+
+Hole punching happens *inside* the QUIC connection via an
+`n0_nat_traversal` extension, inspired by the
+[QUIC NAT traversal draft](https://datatracker.ietf.org/doc/draft-seemann-quic-nat-traversal/)
+but using its own transport parameter ID. See
+[NAT traversal](/concepts/nat-traversal).
+
+
+
+
+
+#### Local connections
+
+If two devices are on the same network, hole punching isn't needed — each side
+just needs to learn the other's local address. See
+[local address lookup](/connecting/local-address-lookup).
+
+
+
+
+
## How the pieces stack together
An iroh application is a stack of small layers, each with one job:
@@ -100,4 +222,4 @@ To get started with iroh, check out the [quickstart guide](/quickstart) or explo
how to use them in your applications.
Read the [how it works documentation](/concepts/endpoints) to understand the underlying
-principles and architecture of iroh.
\ No newline at end of file
+principles and architecture of iroh.
+
## Core features
- **Fast**: iroh enables direct connections between
@@ -32,6 +40,120 @@ and data synchronization. Any kind of CRDT or OT sync protocol can be integrated
services](/protocols/rpc), and [streaming data](/protocols/streaming) with
iroh's communication protocols.
+## How iroh works
+
+iroh's job comes down to two promises: you can reach a peer no matter where it
+is, and the connection you get is the best one available.
+
+### Connect by key
+
+Every iroh [endpoint](/concepts/endpoints) is identified by a cryptographic key.
+That key — not an IP address — is the address. It lets you connect to a peer no
+matter where it is, even as its network location changes underneath it.
+
+
+ 
+
+
+### Reliable connections
+
+We make sure you get a connection whenever possible, and that it's as fast as
+possible. When network conditions change, iroh immediately reacts and switches
+to the new best path — transparently, without dropping the connection.
+
+
+ 
+
+
+Now that we've seen *what* iroh does, here's *how*.
+
+### Library and relays
+
+There are two pieces to the system:
+
+- **The iroh library** runs inside your application. It provides the API to
+ create endpoints, connect to other endpoints, and open connections and data
+ streams.
+- **[Relays](/concepts/relays)** run in the background on publicly reachable
+ servers. They help endpoints find each other and establish direct
+ connections, and relay data as a fallback when a direct connection isn't
+ possible.
+
+### Endpoint startup
+
+An iroh endpoint is configured with a set of relays — the rate-limited public
+relays operated by number 0, relays from iroh services, or self-hosted ones.
+iroh works fine with a single relay, but works best with relays in every region
+where your users are.
+
+On startup, an endpoint sends
+[QAD](https://datatracker.ietf.org/doc/draft-ietf-quic-address-discovery/)
+probes to all configured relays. This does two things: it learns the endpoint's
+own public IP address, and it learns which relay is closest by latency. The
+closest relay becomes the **home relay**, and the endpoint keeps a secure
+WebSocket connection open to it.
+
+
+ 
+
+
+### Finding peers
+
+When there are multiple relays, Alice needs to know which relay to use to reach
+Bob. iroh offers two ways to publish and look up that information.
+
+#### DNS-based lookup
+
+Out of the box, iroh uses DNS. Bob publishes a signed record with his home relay
+to a DNS server operated by number 0 via an HTTPS `PUT`. Anyone who wants to
+reach Bob resolves that record with a DNS or HTTPS query. See
+[DNS address lookup](/connecting/dns-address-lookup).
+
+
+ 
+
+
+#### Mainline DHT lookup
+
+DNS works in most cases, but sometimes you want something fully peer-to-peer.
+For that, iroh offers an optional lookup over the Mainline DHT: it publishes the
+exact same signed record using the
+[BEP 44](https://www.bittorrent.org/beps/bep_0044.html) extension. See
+[DHT address lookup](/connecting/dht-address-lookup).
+
+
+ 
+
+
+### Direct connections
+
+So far we've described a system where endpoints can always talk — but all data
+flows through the relays. That adds latency, limits throughput, and costs the
+relay operator money. Making connections fast and direct is arguably the most
+complex part of the system.
+
+#### Hole punching
+
+Hole punching happens *inside* the QUIC connection via an
+`n0_nat_traversal` extension, inspired by the
+[QUIC NAT traversal draft](https://datatracker.ietf.org/doc/draft-seemann-quic-nat-traversal/)
+but using its own transport parameter ID. See
+[NAT traversal](/concepts/nat-traversal).
+
+
+ 
+
+
+#### Local connections
+
+If two devices are on the same network, hole punching isn't needed — each side
+just needs to learn the other's local address. See
+[local address lookup](/connecting/local-address-lookup).
+
+
+ 
+
+
## How the pieces stack together
An iroh application is a stack of small layers, each with one job:
@@ -100,4 +222,4 @@ To get started with iroh, check out the [quickstart guide](/quickstart) or explo
how to use them in your applications.
Read the [how it works documentation](/concepts/endpoints) to understand the underlying
-principles and architecture of iroh.
\ No newline at end of file
+principles and architecture of iroh.