Table of Contents
Examples
The go-iroh-examples repository — 44 small runnable programs, from key generation to a verified-blob HTTP gateway, each demonstrating one API surface.
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:
go run ./cmd/03-direct-echo
Run all default examples and package tests:
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 — the tutorial this site walks through end to end.
- Tools — the same building blocks packaged as installable commands.
- Ecosystem map — how the repositories relate.