# Yggdrasil Network as an Embedded Go Library

asciimoth maintains a fork of yggdrasil-go (the official `yggdrasil-network/yggdrasil-go` is, in their words, "not especially convenient" because of leaky abstractions and tight coupling). The fork — `asciimoth/ygg` — refactors the codebase into a real library called `ygglib`, with a separate `yggd` daemon for the conventional use case. This article walks through embedding `ygglib` inside another Go application.

The architecture has two clean layers:

**Carrier network** — the underlying transport Yggdrasil uses to reach peers. Represented by the `Network` interface; implementations include the OS native network, a SOCKS proxy, an in-memory loopback (for tests), or even another Yggdrasil network.

**Yggdrasil IPv6 network** — the overlay. Each node gets a stable IPv6 address derived from its public key. Once connectivity is established, ordinary TCP/UDP/HTTP applications can run on top.

The minimal embedding has four pieces:
- `core.Core` — the routing engine, generates the node's IPv6 address from its certificate
- `transport.Manager` — registers transport implementations (`tcp://`, `tls://`, custom schemes like `metered+tcp://`) and maps host patterns (`*.onion`, `127.0.0.1`) to specific carrier networks
- `vtun.VTun` — embedded userspace TCP/IP stack that turns Core's L3 packet stream into `net.Listener` / `net.Conn` interfaces, so standard `http.Client` and friends just work
- `autopeer.Manager` + `multicast.Multicast` — public-peer-list-driven and link-local discovery, replacing manual `CallPeer` invocations

The transport-manager design is the most interesting bit operationally. You can route `*.onion` through Tor, `*.i2p` through I2P, block `*.loki` entirely, and have everything else go through the OS network — all in the manager config, with mappings live (changing a network closes affected listeners and connections so new ones use the new network). This means a single Yggdrasil node can be the user-facing mesh layer over a heterogeneous carrier mix.

VTun is what makes the embedded story actually clean. The official daemon creates a system TUN interface (requires root, OS-specific). The fork's userspace TCP/IP stack (built on `gonnect-netstack/vtun`) keeps everything in-process — no kernel interaction, no privilege escalation, ports allocated inside the embedded stack. The cost is performance (a userspace stack will never match `XDP_REDIRECT`) and extra memory; the win is that an Electron app or a Matrix client or a browser-tab-style application can be a Yggdrasil node.

Why this matters in 2026: the [[russia-vpn-bypass-state-2026-04]] story is partly a story about user-space networking — eBPF-based [[bypassing-dpi-with-ebpf]], userspace TLS desync, and now mesh networking that doesn't require system-level interfaces. The embeddable mesh primitive is one more tool in the [[serverless-relay-transport]] / circumvention toolbox, but it's also useful for ordinary distributed systems where you want stable identity-derived addresses without a coordination layer.

Cross-references: [[yggdrasil-network]], [[asciimoth-ygg]], [[domain-fronting]], [[bypassing-dpi-with-ebpf]], [[serverless-relay-transport]].