gobetween

Last reviewed Sep 13, 2026 · 744 words

gobetween is a layer-4 balancer, which means it never looks inside your traffic. It takes a TCP or UDP connection on one port and hands the bytes to one of a list of backends, and the list can come from Docker, Consul, DNS SRV records, a script, or a static block in a TOML file. That is the whole product. If you want host-based routing, certificates from Let's Encrypt, or anything that involves reading an HTTP header, this is the wrong tool and you want Traefik or Caddy. If you want to spread a Minecraft server, a database, a syslog feed or a VPN endpoint across 3 machines, gobetween does it in one 64 MB binary with less config than HAProxy.

Where it sits in a self-hosted stack

Nobody runs gobetween as their only proxy. It goes in front of the things a layer-7 proxy handles badly: raw TCP services (Postgres read replicas, Redis, MQTT, game servers), UDP services (DNS, syslog, some VPNs), and anything where you need a dumb, fast pass-through without terminating TLS. The common shape is Caddy or Traefik on 80 and 443 for the web apps, and gobetween on a few other ports for everything that is not HTTP. The reverse proxy roundup covers the layer-7 side; this guide covers the layer-4 gap those tools leave.

A config that balances a real service

[servers.pg]
bind = "0.0.0.0:5432"
protocol = "tcp"
balance = "leastconn"

  [servers.pg.discovery]
  kind = "static"
  static_list = [
    "10.0.0.11:5432 weight=1",
    "10.0.0.12:5432 weight=1"
  ]

  [servers.pg.healthcheck]
  kind = "ping"
  interval = "5s"
  timeout = "2s"
  fails = 2
  passes = 1

Save that as /etc/gobetween/conf/gobetween.toml, run gobetween -c /etc/gobetween/conf/gobetween.toml or the yyyar/gobetween Docker image with the file mounted, and you have a balanced Postgres endpoint that pulls a node after 2 failed TCP pings and adds it back after 1 pass. Strategies are weight, roundrobin, leastconn, leastbandwidth, iphash and iphash1; for stateful protocols use iphash so a client keeps landing on the same backend.

Discovery is the reason to pick it over HAProxy

HAProxy can do everything above, with more tuning knobs and a far larger community. What it does not do without extra tooling is watch Docker and rebuild its backend list when containers come and go. gobetween has that built in: set kind = "docker" in the discovery block, point it at the Docker socket, filter on a label, and scaled-up replicas of a container join the pool within the polling interval. The same works for Consul services, DNS SRV, an LXD host, a JSON endpoint, or the output of any script you write with kind = "exec". For a homelab running Compose on 2 or 3 hosts, that removes the "regenerate the config and reload" script you would otherwise write around HAProxy.

Health checks are ping (TCP connect), probe (send bytes, expect bytes back, works for UDP too) and exec (your script, your rules). There is also a REST API on port 8888 that exposes backend state and lets you add and remove servers at runtime, which is handy for draining a node before maintenance.

The honest limits

It is layer 4 only, and it will stay that way. It can terminate TLS on the listener, forward to TLS backends, and route by SNI hostname without decrypting, but it never reads an HTTP header, so no path routing, no redirects, no rewriting. The community is small: about 1,986 stars, and release activity has slowed enough that you should read the last few commits before betting an important path on it. Documentation is a wiki with gaps; expect to read the example config directory in the repository. For anything internet-facing at scale, HAProxy remains the safer choice by a wide margin, and for a single-host homelab you may not need a layer-4 balancer at all.

What I'd do

Use gobetween when you have a specific non-HTTP service to balance across more than one host and you want Docker or Consul discovery without writing glue. Keep the layer-7 job with Caddy or Traefik. If you only have one backend, do not install it; a port forward is simpler. And if you are building something where the balancer failing means the business stops, spend the extra afternoon on HAProxy.