# Meshbird: a distributed private network built from seed addresses

> Meshbird is a Go binary that creates an encrypted overlay network between machines in different clouds, using seed addresses instead of a central control plane. It is small, it is Apache-2.0, and its documentation stops at the --help output.

**meshbird/meshbird** — Distributed private networking

- Repository: https://github.com/meshbird/meshbird
- Website: https://meshbird.com
- Stars: 3,529 · Forks: 208
- Language: Go
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/meshbird-meshbird

## The problem Meshbird targets: one private subnet across clouds

Cloud providers give you a private network inside a region. They do not give you one across providers. A service in one cloud that needs to talk to a service in another usually ends up on public addresses, behind a VPN gateway, or inside a managed mesh with its own control plane and its own account model. Meshbird takes a different route: every node runs the same binary, joins through a seed address, and receives an IP on a shared private range. The README describes the project as "cloud-native multi-region multi-cloud distributed private networking", which is the whole scope statement it offers. The audience is the operator who controls the machines at both ends and would rather run one Go binary than integrate a hosted networking product.

## How Meshbird builds the overlay: seeds, transports and a TUN interface

The repository layout shows the moving parts: a transport/ directory, a protocol/ directory, an iface/ directory, and common/ helpers, with main.go at the top level. The CLI takes --seedaddrs, --publicaddrs, --bindaddrs, --hostaddr, --ip, --mtu, --key, --transportthreads and --verbose. The --ip value is the address the node takes on the overlay, so each machine needs a distinct one. The --seedaddrs value is how a node finds the rest of the network. The iface/ package and the songgao/water dependency in go.mod indicate that the overlay is presented as a TUN interface, which is why the binary needs elevated privileges to create it. The --mtu flag exists because the overlay carries packets inside transport connections, and the usable payload is smaller than the underlying link. The README does not describe the peer discovery protocol, the key exchange behind --key, or how routes are selected when several paths exist. Those details live in protocol/ and transport/, not in the documentation.

## Installing Meshbird and joining two nodes to one network

The README gives one install instruction: download and install the latest release from the GitHub releases page. It does not list distro packages, container images, or a go install line. The releases page currently shows v2.3 from 2019-06-18, v2.2 from 2019-03-17 and v2.1 from 2018-09-19, so a binary from that page is old relative to the source tree. The Makefile builds from source instead:

```bash
make build
```

That target runs go build and writes the binary to bin/meshbird. Once it exists, the help output is the reference for every flag:

```bash
./meshbird --help
```

The Makefile shows the shape of a run invocation with its own targets, which pass --seed_addrs, --local_addr and --ip:

```bash
go run -v src/meshbird/cmd/main.go \
  --seed_addrs "dc1/127.0.0.1:7001" \
  --local_addr "127.0.0.1:7001" \
  --ip 10.237.0.1/16
```

A second machine joins with a different --ip on the same range and the same seed address. If the join works, the TUN interface comes up with the overlay address and the two hosts can reach each other on 10.237.0.0/16. If the interface does not appear, check privileges first: creating a TUN device is a root-level operation on Linux.

## Where Meshbird is thin: documentation, releases and the flag mismatch

The README is short enough to read in a minute, and that is the main limitation. There is no documented failure mode, no troubleshooting section, and no explanation of what happens when a seed goes offline. The Makefile and the README do not agree on flag names either: the README documents --seedaddrs, --bindaddrs and --ip, while the run targets pass --seed_addrs and --local_addr. One of the two is stale, and nothing in the repository says which. Anyone scripting Meshbird should treat the --help output as the contract and read main.go if a flag is rejected. The release history compounds this: the newest tagged release is v2.3 from 2019-06-18, while go.mod targets go 1.26 and the repository was last pushed on 2026-03-04. The source has moved on; the binaries have not. Meshbird is also the wrong tool when the network is inside one cloud and the provider already offers private networking, or when you need a documented API, a web dashboard, or a support contract. The README offers none of those.

## Meshbird against WireGuard and Tailscale: the difference is the control plane

WireGuard gives you an encrypted point-to-point tunnel and a config file listing every peer's public key and endpoint. It is fast and it is in the kernel, but the peer list is your problem: add a machine and you edit configs on the machines that need to reach it. Tailscale keeps WireGuard underneath and adds a coordination service that distributes keys and routes, so joining is a login rather than a config edit, at the cost of depending on that service and its account model. Meshbird sits between the two in design intent. It has no account and no hosted coordinator; the seed address is the rendezvous point, and the binary handles the rest. That is the appeal and the risk. WireGuard's model is boring and fully documented; Tailscale's is managed and documented; Meshbird's is self-hosted and largely undocumented. If you want a mesh without a vendor, Meshbird is one of the few small options, but you are adopting a codebase you may have to read.

## Maintenance, upgrades and what Apache-2.0 means here

The repository is not archived, and the last push was on 2026-03-04. The last tagged release, v2.3, is from 2019-06-18, so the gap between source and release is roughly seven years. That gap is the upgrade story: if you install from the releases page you get old code, and if you build from master you get code that no release has been cut from. There is no documented upgrade procedure, no migration notes, and no version compatibility statement between nodes running different builds. A rolling upgrade across a live mesh is therefore unverified. The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant; it also requires that you keep the licence and notice files and state significant changes. That is a summary of the licence identifier, not legal advice, and anyone embedding Meshbird in a product should read LICENSE in the repository.

## Conclusion

Meshbird fits engineers who want a small, self-hosted overlay across clouds and are willing to read the source when the README runs out. It does not fit anyone who needs a documented control plane, a stable CLI, or supported releases: the newest release is v2.3 from 2019-06-18, while the repository was last pushed on 2026-03-04. Before adopting it, build from master and confirm two nodes on different hosts can reach each other through --seedaddrs, then check whether the --key exchange is documented anywhere you can find.

## FAQ

### What is Meshbird used for?

It creates a private network across machines in different clouds or regions, giving each node an address on a shared subnet so services can talk without public addresses. The README describes it as multi-region multi-cloud distributed private networking.

### What is Meshbird and how does it work?

Meshbird is a Go binary that joins a node to an overlay network through a seed address and assigns it the address given by --ip. The repository contains transport, protocol and iface packages, and the songgao/water dependency indicates the overlay is exposed as a TUN interface.

### How do I install Meshbird?

The README says to download and install the latest release from the GitHub releases page. The Makefile also has a build target that runs go build and writes bin/meshbird from source.

### Why does Meshbird reject a flag that the README documents?

The README and the Makefile use different names for the same options: the README lists --seedaddrs, --bindaddrs and --ip, while the Makefile run targets pass --seed_addrs and --local_addr. Treat the ./meshbird --help output as the authoritative list.

### Does Meshbird need root to run?

The iface package and the songgao/water dependency indicate the overlay is presented as a TUN interface, and creating a TUN device is a privileged operation on Linux. The README does not state the required privileges explicitly.

## Sources

- [License: Apache-2.0](https://github.com/meshbird/meshbird/blob/master/LICENSE)
- [meshbird/meshbird on GitHub](https://github.com/meshbird/meshbird)
- [Project website](https://meshbird.com)
- [README](https://github.com/meshbird/meshbird/blob/master/README.md)
- [Releases](https://github.com/meshbird/meshbird/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/meshbird-meshbird