gophertunnel: a Go library for talking Minecraft Bedrock Edition

Several packages aimed at Bedrock Edition tooling

The README calls gophertunnel a Swiss army knife for Minecraft Bedrock Edition software written in Go, and the repository description calls it a general purpose library for Minecraft Bedrock Edition software written in Go. The Overview says it is composed of several packages that may be of use for creating Minecraft related tools.

The phrase several packages is doing real work here. The top-level entries of the repository show the shape: a minecraft directory, a query directory, a main.go, a config.toml and the usual Go project files. The minecraft directory is the entry point for most users, since the README points there for examples on how to dial a connection or start a server, and the query directory suggests the protocol's request handling lives in its own package.

The audience is therefore not players. This is a library for people writing software that speaks the Bedrock Edition protocol, which in practice means server operators, proxy authors and tooling around the game. The topic list on the repository says the same thing in a compressed form, with auth, bedrock, client, go, minecraft, nbt, protocol, proxy, server and tools.

The licence is MIT and the default branch is master, and the README links the package documentation on pkg.go.dev, where a brief overview of all packages is available.

One Minecraft version at a time is the design constraint

The Versions section is short and it is the most consequential paragraph in the README for anyone planning to depend on the library. Gophertunnel supports only one version at a time, generally the latest official Minecraft release, but multiple protocols can be supported with the API. Generally, a new minor version is tagged when gophertunnel supports a new Minecraft version that was not previously supported.

So the library does not abstract over protocol versions. It implements the current one and expects to be replaced when Mojang ships the next, with the version number moving in a minor bump when that happens. For a server whose players are on the current release that is exactly the right shape, because there is no version negotiation to get wrong. For anything that has to span releases, the API's multi-protocol support is the part to study, and the README does not describe it in detail.

The Go version requirement is given separately, and it is stated as of version v1.47.5, gophertunnel requires at least Go 1.24. The go.mod in the repository declares go 1.25.0, so the module itself now expects a slightly newer toolchain than that README sentence names.

The repository publishes no GitHub releases, so the version numbers live in tags rather than in release entries, and the last push was on 2026-10-19.

Two ways to use it: dial a server, or be one

The Examples section points at two distinct starting points, and they sit on opposite sides of a connection.

The first is in the minecraft package, where examples show how to dial a connection or start a server. Dialing is the client-side path, your code initiates the session and speaks the Bedrock protocol. Starting a server is the other path, your code accepts connections and implements the server side of the same protocol. Both are in the same package tree, which is what makes it useful as a library rather than as a tool.

The second example is a MITM proxy implemented in the main.go file. That is a different shape of program again. A proxy sits between a client and a server, terminates sessions on both sides and forwards between them, which means it can observe, filter or modify traffic that would otherwise be opaque to it.

Choosing between them is a design decision with real consequences. If you want a Bedrock server, the server-side path gives you the whole protocol and no intermediary. If you want to bridge or inspect traffic, the proxy example does that for you, but it introduces a component that sees every packet and can therefore alter them.

The repository carries a config.toml at the root for the proxy's settings. The README does not document what the keys are, so expect to read that file to find out.

Microsoft identity and the Xbox services are part of the dependency tree

The go.mod file shows what a Bedrock client actually has to talk to, and authentication accounts for a large share of it.

There is github.com/coreos/go-oidc/v3 at version 3.17.0 for OpenID Connect, golang.org/x/oauth2 for the token flows, and github.com/go-jose/go-jose/v4 for JSON Web Signature handling, which is how a signed token is validated. On top of that sit the Xbox-specific clients, github.com/df-mc/go-xsapi/v2 for the Xbox services and github.com/df-mc/go-playfab/v2 for the PlayFab services, and github.com/df-mc/jsonc for JSON with comments, which the Xbox configuration formats use.

github.com/google/uuid handles identifiers, and golang.org/x/text handles text encoding, both of which appear in Minecraft's data formats.

The auth topic on the repository is therefore not a separate feature but one of the reasons the dependency list is long. A Bedrock session needs a Microsoft identity token before the game protocol even starts, which means any tool that dials a server inherits a chunk of OAuth and JWT handling. That is also why gophertunnel carries the auth code in the first place rather than asking every user to reimplement it.

The README's own note on this point is worth repeating in spirit, because it says the project does not under any circumstance support or endorse the usage of gophertunnel with malicious intent. The library ships with the authentication machinery that makes account-scoped tools possible, and the project states its position on that directly.

Voice chat pulls in the whole WebRTC stack

The indirect requirements are the clearest evidence of what Bedrock Edition sessions involve, and they are dominated by the pion project.

github.com/pion/webrtc/v4 appears as an indirect dependency, and under it sit pion's datachannel, dtls, ice, interceptor, logging, mdns, randutil, rtcp, rtp, sctp, sdp, srtp, stun, transport and turn packages. github.com/coder/websocket sits alongside it for the signalling channel.

That is a WebRTC stack, and it means voice chat in a Bedrock session is carried over WebRTC rather than over a bespoke protocol. For a library author this matters practically. The DTLS, ICE and SRTP packages are security-sensitive code with their own failure modes, the STUN and TURN packages are what make a connection work behind a NAT, and the RTP and RTCP packages carry the media itself.

The other indirect dependencies are more ordinary. golang.org/x/crypto and golang.org/x/sys are the usual standard library extras, golang.org/x/image and golang.org/x/time fill in the remaining gaps, and github.com/wlynxg/anet is a helper for network address handling that the ICE stack relies on.

The practical consequence for a project using gophertunnel is that pulling in the library pulls in WebRTC, whether or not you intend to carry voice. That is a dependency footprint worth knowing about before it lands in a build.

The transport layer is RakNet, and a forked one

Minecraft's networking does not run over TCP, and the go.mod file names the pieces that make it work.

github.com/sandertv/go-raknet appears at a pseudo-version, v1.15.2 with a commit hash suffix rather than a plain release tag, which is the form Go uses for an untagged commit. The sandertv namespace on that dependency means it is a fork maintained alongside this project rather than an upstream release. That is a meaningful detail, because it ties the library to a RakNet implementation that is updated when the protocol moves, and it means the dependency's version number will not tell you much about the protocol coverage.

github.com/df-mc/go-nethernet at v1.0.24 is the other half. Nethernet is the local discovery mechanism the Bedrock protocol uses for finding nearby servers over UDP broadcast, and the package handles that.

github.com/klauspost/compress at v1.18.1 provides the compression the protocol uses on its streams. github.com/pelletier/go-toml at v1.9.5 is there for the config.toml file at the repository root, github.com/go-gl/mathgl at v1.1.0 provides the vector and matrix maths the protocol needs for its movement and physics data, and golang.org/x/exp and golang.org/x/net supply experimental and networking additions from the standard library's extended family.

Together those two transport dependencies explain why the library is written in Go at all. Go's goroutines and channels map onto a protocol that is heavily concurrent and mostly datagram shaped, which is a better fit than a stack built around blocking socket calls.

Development checks, and the tone of the project's disclaimer

The Development section is brief and describes exactly what CI does, which is useful when you want to match the project's own checks locally. Run make lint to check formatting and code quality with the pinned golangci-lint version. Run go test -race ./... and go build ./... to run the same test and build checks as CI.

The Makefile holds that lint target, and it pins the linter version in the command itself so that every contributor runs the same one:

lint:
	go run github.com/golangci/golangci-lint/v2/cmd/[email protected] run ./...

The use of go run with a versioned module path means no separate linter installation is needed, and the race detector in the test command is a sensible choice for a library built on concurrent network code.

The last thing in the README is the note about malicious intent, which we do not under any circumstance support or endorse the usage of gophertunnel with malicious intent, and a Discord invite for contact. Given that the repository's topics include client, proxy and the fact that it ships a MITM proxy implementation, the project stating that boundary plainly is worth taking at face value rather than reading as boilerplate.

The repository itself carries a .golangci.yml for the linter settings, a .github directory for the workflows, a .gitattributes file and the standard Go files. The licence is MIT, which is a permissive grant that allows you to use the library in closed source software, with the obligation to keep the licence text and copyright notice in any copy of the source you distribute.

Editorial conclusion

gophertunnel fits a Go developer who needs a Bedrock Edition server or a proxy and would rather build on a maintained protocol implementation than write one from scratch. It is the wrong choice if your program needs to talk to several Minecraft versions at once, since the library supports only the current one, and the wrong choice if you need a packaged game client, because what is published here is a library and a proxy example rather than an application. Verify first that the version tag you depend on matches the Minecraft release you need, that the Go toolchain meets the 1.24 floor the README states, and that the MITM proxy in main.go is a starting point rather than a finished tool.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Sandertv/gophertunnel on GitHub