If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/n0-computer/iroh shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 9 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 51% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live n0-computer/iroh repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/n0-computer/iroh.

What it runs against: a local clone of n0-computer/iroh — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in n0-computer/iroh | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of n0-computer/iroh. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/n0-computer/iroh.git
#   cd iroh
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of n0-computer/iroh and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "n0-computer/iroh(\\.git)?\\b" \\
  && ok "origin remote is n0-computer/iroh" \\
  || miss "origin remote is not n0-computer/iroh (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "iroh-base/src/lib.rs" \\
  && ok "iroh-base/src/lib.rs" \\
  || miss "missing critical file: iroh-base/src/lib.rs"
test -f "iroh-base/src/key.rs" \\
  && ok "iroh-base/src/key.rs" \\
  || miss "missing critical file: iroh-base/src/key.rs"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "iroh-dns-server/src/main.rs" \\
  && ok "iroh-dns-server/src/main.rs" \\
  || miss "missing critical file: iroh-dns-server/src/main.rs"
test -f "iroh-base/src/endpoint_addr.rs" \\
  && ok "iroh-base/src/endpoint_addr.rs" \\
  || miss "missing critical file: iroh-base/src/endpoint_addr.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/n0-computer/iroh"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Iroh is a Rust-based modular networking stack that enables direct peer-to-peer connections using public keys instead of IP addresses. It implements hole-punching to establish direct connections when possible, falls back to a relay server network when necessary, and layers QUIC for authenticated encryption and concurrent multiplexed streams. The core philosophy is "dial by key, not IP"—enabling phones, servers, and embedded systems to connect reliably regardless of NAT, firewalls, or network topology changes. Monorepo with workspace members: iroh/ (main endpoint and QUIC logic), iroh-relay/ (relay server), iroh-base/ (primitives), iroh-dns/ and iroh-dns-server/ (name resolution). Higher-level protocols live in separate crate namespaces. Networking flows through Endpoint (bind, connect, dial by key) → QUIC streams → protocol handlers. CI/simulation configs in .github/workflows/ and .github/sims/ model real-world network conditions.

Rust developers building distributed systems, mesh networks, or P2P applications who need robust connectivity abstractions. This includes authors of content-addressed blob transfer systems (iroh-blobs), publish-subscribe overlays (iroh-gossip), and eventually-consistent data stores (iroh-docs). Also relevant for infrastructure teams running relay servers and network simulations.

Actively developed and production-ready in core networking. Evidence: 1.9M lines of Rust across iroh, iroh-relay, iroh-base packages; comprehensive CI workflows (ci.yml, netsim.yml, flaky.yaml); multiple simulation profiles in .github/sims/ with network conditions (20ms, 200ms, 10gb, relay-only, NAT scenarios); and satellite protocol libraries (iroh-blobs, iroh-gossip, iroh-docs, iroh-willow) showing ecosystem maturity. Likely in beta-to-stable phase for production deployments.

Moderate risk factors: the codebase is complex (networking stacks inherently are), and success depends on relay server availability and NAT traversal reliability, both tested but operationally sensitive. Single maintainer organization (n0-computer) means velocity depends on their team capacity. However, the monorepo structure, extensive netsim testing, and multiple protocol layers suggest active risk mitigation. Watch for breaking changes in QUIC/relay APIs across minor versions.

Active development of protocol composition layer (iroh-willow in construction per README). Continuous performance measurement ([iroh-perf] referenced). Multiple active workflows: netsim integration tests, Docker builds, flaky test detection. Dependabot active (dependabot.yml present). Release and beta pipelines suggest regular versioning cadence.

git clone https://github.com/n0-computer/iroh.git
cd iroh
cargo build --release
cargo test --workspace

For examples, see README code snippet—basic pattern is Endpoint::bind().await? then endpoint.connect(addr, ALPN).await?. Use cargo add iroh in your own project.

Daily commands: Primary dev setup: cargo build for library. For relay server: build iroh-relay member. Run full test suite: cargo nextest run (config in .config/nextest.toml). For network simulation: scripts in .github/sims/ integrate with CI but require external network simulator. Example server/client code in README; build by running example crate within workspace.

• iroh-base/src/lib.rs — Core types and abstractions (keys, endpoint addresses, relay URLs) that form the foundation of the entire networking stack
• iroh-base/src/key.rs — Key cryptographic primitives and dial-key abstraction—essential to understanding the 'dial keys instead of IP addresses' core philosophy
• Cargo.toml — Workspace configuration defining all member crates (iroh-base, iroh-dns, iroh-dns-server, iroh, iroh-relay) and dependency constraints
• iroh-dns-server/src/main.rs — Entry point for the DNS relay server, demonstrates full stack integration from config to request handling
• iroh-base/src/endpoint_addr.rs — Endpoint address abstractions for dialing without IP dependency, core to the modular networking design
• iroh-dns-server/src/server.rs — Main server initialization and request dispatch logic for the DNS/relay infrastructure
• TRANSPORTS.md — Documentation of supported transport mechanisms—required reading for understanding the modular networking stack architecture

Add a new DNS record storage backend

1. Define the storage trait in iroh-dns-server/src/store.rs with async methods for get/put/list operations (iroh-dns-server/src/store.rs)
2. Implement the trait for your backend (e.g., a database driver or file system) (iroh-dns-server/src/store.rs)
3. Update the config schema in iroh-dns-server/src/config.rs to accept your backend type (iroh-dns-server/src/config.rs)
4. Initialize the backend in iroh-dns-server/src/state.rs during server startup (iroh-dns-server/src/state.rs)

Add a new HTTP endpoint to the DNS server

1. Create a new handler module in iroh-dns-server/src/http/ (e.g., iroh-dns-server/src/http/custom.rs) (iroh-dns-server/src/http/)
2. Define the route and handler logic following the pattern in iroh-dns-server/src/http/doh.rs or iroh-dns-server/src/http/pkarr.rs (iroh-dns-server/src/http/doh.rs)
3. Register the route in iroh-dns-server/src/http.rs within the Router builder (iroh-dns-server/src/http.rs)
4. Add integration tests in the same handler module (iroh-dns-server/src/http/doh.rs)

Add support for a new key or endpoint type

1. Define the new type in iroh-base/src/key.rs or iroh-base/src/endpoint_addr.rs with serialization/deserialization (iroh-base/src/key.rs)
2. Export the type from iroh-base/src/lib.rs (iroh-base/src/lib.rs)
3. Update any consumers in iroh-dns-server/src/dns.rs to handle the new type in query processing (iroh-dns-server/src/dns.rs)
4. Add codec support in iroh-dns-server/src/http/extract.rs if needed for HTTP parsing (iroh-dns-server/src/http/extract.rs)

Add a new network simulation scenario

1. Create a new JSON scenario file in .github/sims/ (e.g., .github/sims/custom/scenario.json) using the existing structure as a template (.github/sims/integration/iroh.json)
2. Define network conditions (latency, packet loss, bandwidth) and node configurations (.github/sims/integration/iroh.json)
3. Reference the scenario in .github/workflows/netsim.yml to run it in CI (.github/workflows/netsim.yml)

• Rust — Memory safety without GC, zero-cost abstractions, and strong concurrency primitives essential for a high-performance networking stack
• DNS (RFC 1035) + Pkarr protocol — Leverages existing DNS infrastructure for discovery and adds decentralized signed records via Pkarr to avoid IP address brittleness
• Cryptographic keys as primary identifiers — Replaces IP addresses with long-term stable cryptographic identities, enabling direct dialing regardless of network topology changes
• Modular workspace (iroh-base, iroh-dns, iroh-relay, iroh) — Allows independent evolution of core types, DNS server, relay infrastructure, and the main networking daemon
• HTTP/TLS + DoH (DNS-over-HTTPS) — Provides encrypted, privacy-preserving DNS resolution and modern API surface for integrating with web services

• Cryptographic keys as primary identifiers instead of IP addresses

  • Why: Avoids network address exhaustion and renumbering brittleness; enables stable identity across network transitions
  • Consequence: Requires additional key distribution and discovery infrastructure (Pkarr, DNS); adds cryptographic overhead per request

• Separate iroh-base crate for shared types

  • Why: Minimizes coupling and allows dns-server, relay, and main iroh to import only essential dependencies
  • Consequence: Adds crate boundary overhead; requires careful API design to avoid circular dependencies or version skew

• Pluggable storage backend for DNS records

  • Why: Enables deployment on diverse systems (embedded, cloud, on-prem) without recompiling
  • Consequence: Storage trait abstraction adds indirection; implementations must handle consistency and replication independently

• Network simulation via JSON configuration in CI

  • Why: Tests behavior under realistic latency, packet loss, and topology changes without real hardware
  • Consequence: Simulations may not capture all edge cases in production; requires ongoing scenario updates

• Does not provide traditional IP address-based networking; explicitly replaces it with key-based dialing
• Not a general-purpose DNS server for the public internet; focused on Iroh-specific endpoint discovery
• Does not handle authentication beyond cryptographic key verification; delegates auth policy to applications
• Linux-only constraint not explicit, but Docker and CI focus suggests primary target; Windows/macOS support secondary

1. ALPN is mandatory: All connections require an ALPN (Application-Layer Protocol Negotiation) string; forgetting it will cause connection failures. 2. Relay server availability: Hole-punching may fail in symmetric NAT; reliance on public relay infrastructure means downtime affects all connections. 3. Key vs. IP mental model shift: Developers accustomed to socket APIs will need to think in terms of public keys (NodeAddr/endpoint identifiers) rather than IP:port pairs. 4. Async all the way: No blocking APIs; Tokio runtime required; attempting sync I/O will deadlock. 5. Network simulation for testing: The .github/sims/ profiles are JSON configs for an external network simulator (likely netsim tool); local testing may not reproduce failure modes without matching setup.

• Hole Punching (NAT Traversal) — Core feature of iroh—enables direct P2P connections even behind restrictive firewalls; understanding STUN, UDP hole-punch techniques, and when fallback to relay occurs is critical for debugging connectivity issues
• QUIC (Quick UDP Internet Connections) — Foundation of iroh's transport layer; provides multiplexing, encryption, and stream prioritization out of the box, avoiding head-of-line blocking issues of TCP
• ALPN (Application-Layer Protocol Negotiation) — Mechanism iroh uses to negotiate which protocol (iroh-blobs, iroh-gossip, custom) runs over a QUIC connection; understanding ALPN strings prevents version mismatch errors
• Public Key Addressing — Iroh's core abstraction: endpoints are identified by public keys rather than IP addresses, enabling mobility and privacy; requires understanding key generation, distribution, and validation
• Relay Server Architecture — Iroh-relay provides fallback when hole-punching fails; understanding relay latency, bandwidth costs, and trust model is essential for production deployments and cost optimization
• Network Simulation & Emulation — Iroh uses network simulators (.github/sims/ profiles with latency, bandwidth, NAT conditions) to test connectivity; reproducing production failure modes locally requires understanding these simulation configs
• Content Addressing (BLAKE3) — iroh-blobs uses BLAKE3 hashing for content-addressed transfers; understanding merkle trees, chunk-based hashing, and verified transfer is necessary for protocol composition and blob integrity

• libp2p/rust-libp2p — Alternative Rust P2P networking stack; offers pluggable transports and protocols but with different architecture and API philosophy (libp2p is protocol-agnostic, iroh is QUIC-first)
• quinn-rs/quinn — Pure Rust QUIC implementation; iroh likely uses or relates to this for QUIC layer (referenced as [noq] in docs, which may wrap/extend Quinn)
• tailscale/tailscale — Commercial mesh VPN; similar goal (IP abstraction via keys, relay fallback) but proprietary; iroh is open alternative with different threat model and composability story
• n0-computer/iroh-blobs — Content-addressed blob transfer protocol built on iroh; demonstrates how to layer protocols using Endpoint and QUIC streams
• n0-computer/iroh-gossip — Publish-subscribe overlay network using iroh; shows composing multiple concurrent protocols over single Endpoint

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for endpoint_addr.rs and relay_url.rs parsing

The iroh-base crate contains critical networking primitives (endpoint_addr.rs, relay_url.rs, key.rs) but lacks visible test coverage for edge cases. Given that iroh's core value proposition is 'dial keys instead of IP addresses,' robust parsing tests for these types are essential. This would prevent subtle bugs in address resolution and relay URL handling across the networking stack.

• [ ] Review iroh-base/src/endpoint_addr.rs for all public parsing paths and error conditions
• [ ] Review iroh-base/src/relay_url.rs for URL validation edge cases (invalid schemes, malformed hosts, port ranges)
• [ ] Add unit tests in each module for: valid inputs, malformed inputs, edge cases (empty strings, max lengths, special characters), and roundtrip serialization
• [ ] Add integration tests in iroh-base/tests/ directory testing interaction between these types
• [ ] Verify tests run in CI by checking .github/workflows/tests.yaml includes iroh-base

Add transport-specific tests to .github/sims/ for network simulation scenarios

The repo has extensive network simulation configs (.github/sims/iroh/, .github/sims/integration/) but lacks documented test cases that exercise them. Given the modular networking stack design and TRANSPORTS.md existence, creating repeatable netsim test scenarios would catch transport-layer regressions early. This directly supports the 'modular networking stack' value proposition.

• [ ] Review TRANSPORTS.md to identify key transport scenarios (direct, relay, NAT traversal, multi-transport failover)
• [ ] Create new test scenario files in .github/sims/ (e.g., transport_failover.json, multi_nat.json) for currently uncovered paths
• [ ] Add netsim test definitions documenting expected behavior (what each scenario validates)
• [ ] Integrate new scenarios into .github/workflows/netsim.yml or netsim_runner.yaml with clear naming
• [ ] Document in a new NETSIM_TESTING.md file how to run and add new network simulation tests

Extract and document internal networking utilities into iroh-base for reuse

The repo has multiple crates (iroh, iroh-dns, iroh-relay) with likely duplicated networking utility code. Reviewing the main iroh crate and iroh-relay for common patterns (address parsing, retry logic, connection pooling) and consolidating them into iroh-base would reduce maintenance burden and improve consistency. This leverages the existing workspace structure and the 'modular' design principle.

• [ ] Scan iroh/src/ and iroh-relay/src/ for utility modules with duplicated functionality (connection handling, address validation, timeouts)
• [ ] Identify 2-3 concrete utilities that appear in multiple crates (check for similar patterns even if names differ)
• [ ] Create new public modules in iroh-base/src/ for these utilities with comprehensive documentation
• [ ] Update iroh and iroh-relay to depend on iroh-base and replace duplicated code with re-exports
• [ ] Add tests in iroh-base for new utilities and update Cargo.toml dependencies to ensure proper feature gating if needed

• Add example demonstrating relay-only fallback mode: README shows basic dial/connect but doesn't document when/how relay fallback triggers. A worked example with explicit relay configuration would help new users understand failure recovery.
• Expand DNS resolution documentation and add iroh-dns integration example: iroh-dns/ and iroh-dns-server/ crates exist but no example shows how to integrate name resolution with Endpoint::connect(). A tutorial would clarify the DNS → key mapping flow.
• Document ALPN protocol registry and versioning best practices: ALPN is used throughout but no centralized docs explain how to version protocols, avoid collisions, or evolve ALPN strings. A guide with concrete iroh-blobs/iroh-gossip examples would help protocol authors.

The iroh networking codebase demonstrates generally good security practices with multi-license coverage (MIT/Apache 2.0), organized workspace structure, and use of Rust's memory safety guarantees. However, several improvements are recommended: (1) Debug symbols should be disabled in release builds to prevent information leakage, (2) A formal security policy and responsible disclosure process should be established, (3) Dependency auditing via deny.toml should be strictly enforced, and (4) The networking components (relay server, DNS resolver) require rigorous security testing due to their critical nature and attack surface. The configuration profiles are well-structured but could be optimized further. No hardcoded secrets or obvious injection vulnerabilities were detected in the file structure.

• Medium · Debug Symbols Enabled in Release Builds — Cargo.toml - [profile.release]. The Cargo.toml configuration enables debug symbols in release builds ([profile.release] debug = true). This increases binary size and may leak sensitive information through debug symbols in production binaries. Fix: Set debug = false in release profile unless debugging production issues is necessary. Consider using a separate profile for debuggable releases.
• Medium · Potential Dependency Supply Chain Risk — Cargo.toml - [workspace.members], deny.toml. The workspace includes a relay server component (iroh-relay) and DNS server (iroh-dns-server) that may have external dependencies. No deny.toml audit file content was provided to verify dependency security checks are enforced. Fix: Ensure deny.toml is configured to audit and restrict vulnerable dependencies. Run 'cargo deny check' regularly and maintain an up-to-date dependency audit process.
• Medium · LTO Disabled in Optimized Release Profile — Cargo.toml - [profile.optimized-release]. The optimized-release profile inherits from release but doesn't specify LTO settings. While lto = true is set, verify this is consistently applied to prevent information leakage through unused code paths. Fix: Consider enabling Link Time Optimization (lto = 'fat') and verify it's consistently applied across all production builds.
• Low · Example Configuration File Present — example.config.toml. An example configuration file (example.config.toml) exists in the repository. While marked as example, ensure it does not contain sensitive defaults or hardcoded values that could be copied without modification. Fix: Audit the example configuration file to ensure no sensitive values are included. Document all required configuration changes clearly.
• Low · Missing Security Policy Documentation — Repository root. No SECURITY.md or security policy file is evident in the file structure to guide security researchers on responsible disclosure. Fix: Create a SECURITY.md file following OWASP guidelines for responsible vulnerability disclosure. Include contact information and expected response times.
• Low · Docker Images Built from CI Pipeline — docker/Dockerfile, docker/Dockerfile.ci. Multiple Dockerfiles present (Dockerfile, Dockerfile.ci) are built in CI pipeline. Ensure base images are secure and regularly updated. Fix: Specify explicit base image versions (not 'latest'), regularly scan Docker images for vulnerabilities, and implement image signing.
• Low · Networking Stack Complexity — iroh-relay/, iroh-dns-server/, iroh-dns/. As a modular networking stack handling dial operations and relay services, the codebase has increased attack surface. DNS resolution and relay server components are critical security boundaries. Fix: Implement comprehensive input validation for all network inputs, maintain security test coverage for networking components, and consider fuzzing critical network parsing code.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.