Table of Contents

• Commands
  • iroh
  • iroh-relay
  • iroh-dns-server
  • wasmrelaytest
  • Commands in the experiment modules
  • Next steps

Commands

The binaries go-iroh ships — iroh, iroh-relay, iroh-dns-server, wasmrelaytest — with their real flags and output.

The core module ships four commands. Install one with go install, or run it from a checkout with go run:

go install github.com/tmc/go-iroh/cmd/iroh@latest

iroh

A key and address utility. It takes arguments, not stdin, and has no flag package — the only option is --seed= on key gen.

usage: iroh <command> [args]

commands:
  key gen [--seed=<hex32>]   generate a secret key (prints secret hex)
  key public <secret-hex>    print the public key (endpoint id) for a secret
  key z32 <key>              print the z-base-32 form of a public key
  id parse <key>             parse and re-print a public key (hex)
  addr parse <addr>          parse a transport address and re-print it
  sign <secret-hex> <msg>    sign msg, print signature hex
  verify <pub> <sig-hex> <msg>  verify a signature (exit 0 ok, 1 fail)

A worked session (values differ per run):

$ iroh key gen
13903a6d9ea9da31…                       # 64 hex characters
$ iroh key public 13903a6d9ea9da31…
70a5eaa72e54b657c4fd753ffd32f7a8b34594cfbb9d52ef423e0b2ec46fb998
$ iroh key z32 70a5eaa72e54b657c4fd753ffd32f7a8b34594cfbb9d52ef423e0b2ec46fb998
qn16ij3qk15fxt87qw994czzin3wmfgxzqqif54n8af17tdxzgcy
$ iroh sign 13903a6d9ea9da31… hello
…                                       # 128 hex characters
$ iroh verify 70a5eaa72e… <sig> hello
ok

key gen --seed=<hex32> is deterministic: the seed is exactly key.SeedSize bytes in hex.

addr parse expects a transport address in kind:value form — the same form netaddr.ParseTransportAddr accepts — and re-prints it:

$ iroh addr parse ip:127.0.0.1:4433
ip:127.0.0.1:4433
$ iroh addr parse relay:https://use1-1.relay.iroh.network./
relay:https://use1-1.relay.iroh.network./

A bare 127.0.0.1:4433 fails with unknown kind "127.0.0.1"; the ip: prefix is required.

iroh-relay

Runs a self-hostable relay server: the relay endpoint at /relay and a liveness endpoint at /healthz.

Usage of iroh-relay:
  -addr string
    	listen address (default ":3340")
  -shutdown-timeout duration
    	grace period for in-flight connections on shutdown (default 5s)

$ iroh-relay -addr=127.0.0.1:34331
iroh-relay listening on 127.0.0.1:34331 (relay: /relay, health: /healthz)

GET /healthz returns 200. GET /relay with a plain HTTP client returns 426 (Upgrade Required) — it is a WebSocket endpoint, so that response means the relay is up, not that something is broken.

Point endpoints at it with relay.ModeCustomURLs(...). To embed it in your own server instead, use the relayserver package.

iroh-dns-server

Runs the pkarr HTTP and DNS surfaces used by iroh discovery.

Usage of iroh-dns-server:
  -addr string
    	listen address (default ":3350")
  -dns-addr string
    	UDP DNS listen address

-dns-addr is empty by default, which serves the HTTP (pkarr) surface only; set it to also serve UDP DNS. The embeddable form is the dnsserver package.

Clients reach it with iroh.NewPkarrPublisher / iroh.NewPkarrResolver pointed at your relay URL, and iroh.NewDNSAddressLookup pointed at your origin — see Relays and discovery.

wasmrelaytest

A browser smoke test for the js/wasm relay-only transport path. It builds only under GOOS=js GOARCH=wasm and takes no flags; see its README in the go-iroh repository for how it is driven.

Commands in the experiment modules

Each go-iroh-experiments module ships its own binaries (content-tracker, grpc-iroh-demo, tlog-iroh, x402-iroh, and others). The generated module index lists them per module.

Next steps

• Relays and discovery — pointing endpoints at the servers above.
• Testing and interop — verifying a change.