---
title: Examples
description: The go-iroh-examples repository — 44 small runnable programs, from key generation to a verified-blob HTTP gateway, each demonstrating one API surface.
icon: code
---

[`github.com/tmc/go-iroh-examples`](https://github.com/tmc/go-iroh-examples)
is a separate repository of small runnable examples, one command per
directory, numbered in a learning progression. The examples build against the
go-iroh version pinned in that repository's `go.mod`.

Run one from the repository root:

```sh
go run ./cmd/03-direct-echo
```

Run all default examples and package tests:

```sh
go test ./... -count=1
```

Examples `01` through `10` use loopback direct paths and avoid live relay and
DNS dependencies. Examples `11` through `15` demonstrate non-local workflows
and either print their required environment variables or require an explicit
live-network opt-in.

## The progression

The one-line descriptions below are the repository's own. Each example's
directory contains its full source and any flags it takes.

| Example | Shows |
| --- | --- |
| `01-keys` | endpoint identity: `key.SecretKey`, `key.EndpointID`, signatures |
| `02-addresses` | address construction with `netaddr.EndpointAddr` |
| `03-direct-echo` | two localhost endpoints exchanging a QUIC stream |
| `04-router-echo` | ALPN dispatch through `iroh.Router` |
| `05-memory-discovery` | connecting by endpoint id through `iroh.MemoryLookup` |
| `06-manual-incoming` | manual `AcceptIncoming`, `Accepting.ALPN`, and connection verification |
| `07-source-validation` | local QUIC Retry source-address validation |
| `08-hooks` | observing outbound dials and handshakes with `EndpointHooks` |
| `09-metrics` | endpoint counter snapshots after a connection |
| `10-multi-alpn` | one router dispatching multiple application protocols |
| `11-public-server` | binding a server on a public UDP address and advertising its endpoint address |
| `12-connect-public` | connecting to a peer described by endpoint id plus public IP or relay URL |
| `13-relay-online` | opting into the default public relay map and waiting for relay connectivity |
| `14-dns-resolve` | resolving a published endpoint id through DNS endpoint discovery |
| `15-pkarr-publish-resolve` | publishing endpoint data to pkarr and resolving it back |
| `16-sendme-file` | `sendme`-style BAO-verified blob transfer |
| `17-dumbpipe` | `dumbpipe`-style byte piping over an iroh stream |
| `18-callme-frames` | `callme`-style realtime media frame transport with datagrams |
| `19-rpc-workqueue` | concurrent postcard RPC work with `irpc.Call` and `irpc.Handler` |
| `20-resumable-chunks` | resumable BAO-verified blob range transfer |
| `21-memory-mesh` | multi-node loopback mesh broadcast using memory endpoint discovery |
| `22-watch-observer` | observing endpoint address changes with `watch.Observer` |
| `23-watch-value` | using `watch.Value` and observer streams directly |
| `24-irohcat` | `nc`-style stdin/stdout piping over an iroh stream |
| `25-http-over-iroh` | serving `net/http` over stream-backed iroh `net.Conn` values |
| `26-stream-netconn-deadline` | using `Conn.OpenStreamConn`, `Conn.AcceptStreamConn`, and deadlines |
| `27-local-infra` | embedding local DNS, relay, and metrics infrastructure packages |
| `28-net-report` | reading endpoint network reports, with live relay probing opt-in |
| `29-address-filtering` | publishing filtered DNS/pkarr address sets locally |
| `30-transport-tuning` | tuning stable QUIC keepalive and idle timeout settings |
| `31-stream-listener` | serving stream-backed `net.Listener` values directly and through a router |
| `32-graceful-shutdown` | draining router handlers and closing endpoints after SIGINT/SIGTERM |
| `33-path-upgrade` | watching selected paths as a relay connection advertises direct candidates |
| `34-uni-streams` | publishing independent telemetry events over unidirectional streams |
| `35-close-codes` | decoding application close codes and reasons from peer shutdown |
| `36-incoming-filter` | router admission control with `RouterConfig.IncomingFilter` and `AcceptingHandler` |
| `37-doctor` | printing local relay, net-report, latency, and path diagnostics |
| `38-app-envelope-ticket` | wrapping endpoint tickets with app metadata in a base32 envelope |
| `39-datagram-vs-stream` | sending small payloads as datagrams and falling back to streams |
| `40-iroh-ping` | minimal custom protocol over ALPN `iroh/ping/0`: `PING` to `PONG` |
| `41-framed-messages` | length-delimited messages over one bidirectional stream |
| `42-iroh-automerge` | Automerge CRDT sync messages over an iroh protocol handler |
| `43-iroh-smol-kv` | signed key-value updates over a joined gossip topic |
| `44-iroh-gateway` | HTTP Range gateway for verified blobs fetched over iroh |

## Next steps

- [Build an echo protocol](first-app) — the tutorial this site walks through
  end to end.
- [Tools](tools) — the same building blocks packaged as installable commands.
- [Ecosystem map](ecosystem-map) — how the repositories relate.