mullvad/gotatun: Using a Userspace WireGuard Implementation

GotaTun's userspace WireGuard boundary

GotaTun addresses the need for a WireGuard implementation that runs in user space rather than in the operating system kernel. The README identifies it as a Rust implementation and a fork of Cloudflare's BoringTun. Its intended users are developers who need either a reusable WireGuard library or a standalone tunnel executable. It is not presented as a complete VPN service or configuration manager. Once the process creates an interface, configuration is left to `wg`, `wg-quick`, or another tool.

That boundary matters when an application needs to control which WireGuard implementation participates in a tunnel. A library integration can avoid launching a separate executable, while the `gotatun` binary provides a direct process that exposes an interface to standard WireGuard configuration tools. The Cargo workspace contains separate `gotatun` and `gotatun-cli` members, and the workspace metadata gives the package version as `0.10.0`.

The repository also documents extensions to the WireGuard configuration protocol in `UAPI.md`. Developers comparing `wg` behavior with GotaTun should consult that file rather than assume every protocol operation is identical. The README itself does not provide a high-level Rust API example, so the crate source and `UAPI.md` are the relevant starting points for integration work.

Cargo library and executable builds

The project offers two explicit Cargo build paths. The library can be compiled without default features, while the executable is built under the `gotatun` binary name. Both documented commands can optionally include a target triple through the bracketed syntax shown by the README.

For the library-only release build, run:

cargo build --lib --no-default-features --release [--target $(TARGET_TRIPLE)]

The brackets are part of the README's notation for the optional target argument, not characters that should be copied into every invocation. For an executable targeting the default build platform, run:

cargo build --bin gotatun --release

The README states that the executable is placed in `./target/release` by default. There is no documented requirement to place it somewhere particular before a first local use, so the release build is the cleaner starting point for inspecting the resulting binary.

The workspace uses Rust edition 2024 and declares Rust 1.95 as its minimum supported version. A developer using an older stable toolchain must address that requirement before the documented builds are expected to work. This declaration does not itself describe feature flags exposed by the library, so `--no-default-features` should not be interpreted as a minimal feature list without checking the crate definitions.

Installing GotaTun for a first interface

Cargo can install the `gotatun` executable directly from the current repository path. This is the most direct documented installation method for someone who already has the source available.

cargo install --bin gotatun --path .

Alternatively, copying the executable manually from the build output is supported. The README does not document package-manager repositories for Linux distributions, Windows, or macOS, so applications that require an operating-system package should not infer one from the Cargo and Nix instructions.

A first tunnel starts with the executable, an optional foreground flag, and an interface name. The README's exact invocation form is:

gotatun [-f/--foreground] INTERFACE-NAME

`INTERFACE-NAME` is a placeholder in the documented syntax, not one fixed name. The process must then be configured as a regular WireGuard tunnel with `wg` or another tool. The README does not give a complete first-use configuration containing an interface address, private key, peer, allowed IP ranges, or DNS settings. Those values are deployment-specific and cannot be inferred from GotaTun's launch command.

The `--foreground` option is relevant when process supervision is handled externally. Without documentation of a separate daemon configuration format, there is no basis for prescribing a service-manager configuration here.

Nix builds and wg-quick integration

Nix users can build the executable through the flake exposed by the repository. The README gives one command:

nix build .#gotatun

It states that the resulting binary is placed at `result/bin/gotatun`. This provides a reproducible repository-based build path, although the README does not enumerate the contents of `flake.nix` or explain which outputs are available besides the named executable.

`wg-quick` can select GotaTun through an environment variable. The documented invocation is:

sudo WG_QUICK_USERSPACE_IMPLEMENTATION=gotatun WG_SUDO=1 wg-quick up CONFIGURATION

`CONFIGURATION` refers to the interface configuration accepted by `wg-quick`; the README does not include its file contents. Setting `WG_QUICK_USERSPACE_IMPLEMENTATION` does not guarantee selection on Linux when the WireGuard kernel module is installed, because `wg-quick` ignores that variable in that environment. Operators must account for the installed kernel implementation rather than assuming the environment variable overrides it.

On macOS, GotaTun expects an explicit interface name matching `utun[0-9]+`, or the name `utun` lets the kernel select the lowest available interface. When `utun` is selected and `WG_TUN_NAME_FILE` is defined, GotaTun writes the allocated name to the specified file. These rules constrain automation on macOS even though the general launch syntax remains simple.

Linux privileges, capabilities, and fwmark behavior

Linux privilege handling is the clearest difference between GotaTun and the `wireguard-go` behavior described in the README. GotaTun drops privileges after startup. Once that happens, it cannot set `fwmark`, which can be required for routing decisions and is identified as relevant when using `wg-quick`.

The README offers two documented ways to retain the ability needed for `fwmark`: start with `--disable-drop-privileges`, or set the environment variable `WG_SUDO=1`. It does not provide a full privilege model or explain which additional actions occur under each option, so deployment documentation should state the selected behavior explicitly rather than treating them as interchangeable defaults.

The executable must receive Linux `CAP_NET_ADMIN`. The exact documented command is:

sudo setcap cap_net_admin+epi gotatun

After this capability is assigned, the README says sudo is not needed to start GotaTun. Assigning the capability to the file is an explicit security decision, particularly when privilege dropping is disabled. The command does not permanently grant every unrelated capability to the process; it grants the capabilities encoded by `cap_net_admin+epi`.

The testing workflow has different needs. Running `cargo test` requires `sudo` because tests create tunnels and prompts for a password. Docker is also required. For Ubuntu or Debian, the README lists this installation command:

apt-get install docker.io

This Docker requirement is documented for testing GotaTun, not for using a prebuilt executable.

Supported targets and feature boundaries

The README distinguishes executable and library availability by target. Both binary and library support are listed for `x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`, `aarch64-apple-darwin`, `x86_64-pc-windows-msvc`, `x86_64-pc-windows-gnullvm`, `aarch64-pc-windows-msvc`, and `aarch64-pc-windows-gnullvm`. Those are the targets for which both forms are explicitly supported in the table.

For `x86_64-linux-android`, `aarch64-linux-android`, and `aarch64-apple-ios`, the table marks library support but does not mark binary support. This makes the library the relevant choice for mobile integration, but the README does not provide a mobile `gotatun` executable workflow. It also does not document application packaging, signing, or lifecycle integration for those systems.

The README says other targets may work, while stating that only the listed targets are tested. That is a narrow assurance. It does not establish that an arbitrary target will compile, that a TUN device will be available, or that platform permissions are configured correctly. Deployment planning should therefore distinguish tested target support from the possibility of unsupported builds working by accident.

The broader workspace dependencies show that GotaTun uses Rust networking, asynchronous runtime, TUN, and cryptography crates. Those dependency names do not by themselves establish public API stability, performance, or platform guarantees. Developers embedding the library must evaluate its exposed interfaces directly rather than infer them from the command-line executable.

MPL-2.0 licensing and release upkeep

Current source code is subject to Mozilla Public License 2.0 unless otherwise stated. Contributions submitted on or after March 5, 2026 are intended to use that license unless the contributor explicitly states otherwise. Earlier contributions remain under the old BSD 3-clause license. A distributor reviewing the repository needs to account for both `LICENSE` and `LICENSE-CLOUDFLARE`.

The project is not archived. Its last push was on 2026-10-15, and releases include `v0.10.0` on 2026-10-14, `v0.9.2` on 2026-08-31, and `v0.9.1` on 2026-08-27. These repository facts show recent code and release activity. They do not establish a long-term support commitment, a stable public API, or a fixed maintenance period.

Upgrade review should center on the versioned crate and release history in `CHANGELOG.md`. The repository includes independent security audit material under `audits/README.md`, but the main README does not state the audit findings, supported revision, or remediation status. The presence of an audit directory is not sufficient to make a security claim for a particular release.

There are at least two license and upgrade surfaces to track: the MPL-2.0 work and the retained BSD-licensed history. The project also targets Rust 1.95, so toolchain movement and target availability are concrete integration constraints. Neither the README nor the workspace metadata describes a semantic-versioning guarantee, so an upgrade requires checking the relevant API and configuration behavior for the selected release.

Editorial conclusion

GotaTun is suitable for developers embedding WireGuard in a Rust application or operating a standalone userspace tunnel through `wg`. It is less suitable when retaining the Linux kernel implementation is mandatory, privilege escalation is unacceptable, or an undocumented target is required. Verify the Rust toolchain, target-specific capabilities, and `wg-quick` selection behavior before adoption.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. mullvad/gotatun on GitHub
4. README
5. Releases