Blacktip

Blacktip runs on your public server. It owns the IP addresses and opens the TCP, UDP, HTTP and HTTPS ports you pick, including the same port on different IPs. It terminates the WireGuard tunnels, puts logins in front of websites (optionally through Traefik), checks target health, and delivers your outgoing mail with DKIM signing and MTA-STS.

Part of the sharks stack: Hammerhead (control plane and dashboard) · Blacktip (edge) · Bamboo (site agent) · Reef (shared library). Everything is configured from Hammerhead's web dashboard; the full documentation lives in its README.

Run it

In Hammerhead, go to Server → Edges → add an edge. The dashboard shows the exact command with your token. It looks like this:

blacktip -hammerhead https://hammerhead.example.com -token <edge token> -tunnel :51820 -docker

Open the WireGuard UDP port (default 51820) and any ports you open from the dashboard in this machine's firewall. Blacktip only needs to reach Hammerhead over HTTPS; it never needs inbound access from it.

Flag	Environment	Meaning
-hammerhead	BLACKTIP_HAMMERHEAD	URL of Hammerhead
-token	BLACKTIP_TOKEN	the edge's token
-tunnel	BLACKTIP_TUNNEL	UDP listen address for WireGuard (default :51820)
-data	BLACKTIP_DATA	folder for the WireGuard key and certificates
-docker	BLACKTIP_DOCKER=1	report local Docker containers so they can be picked as targets
-traefik	BLACKTIP_TRAEFIK	path to a Traefik v3 binary, to serve http/https with Traefik. Release archives and the Docker image include a tested one
-acme-dns	BLACKTIP_ACME_DNS	with Traefik: DNS-challenge provider for wildcard certificates
-no-acme		with Traefik: serve its self-signed certificate instead of Let's Encrypt
-env		.env file to read (default ./.env)

Settings and secrets can live in a .env file instead of the command line; see .env.example. Real environment variables always win.

What it does

• Ports: TCP, UDP, HTTP, HTTPS and TLS passthrough, one listener per IP and port, opened and closed live as you change them in the dashboard. Port ranges for TCP and UDP. Round-robin load balancing and failover across several targets, with health checks.
• PROXY protocol (v1/v2) on TCP and TLS ports, so the target sees the real client address.
• Web: automatic Let's Encrypt certificates, HTTP/2, websockets, and logins (account, password, PIN, emailed code, share links, path and IP rules) enforced in front of any site. Use the built-in proxy, or -traefik to let Traefik serve http/https (raw TCP, UDP and TLS-passthrough ports always stay with Blacktip, since Traefik can't open ports without a restart).
• Traffic analytics: counts connections and bytes in and out for every port, and the busiest client addresses on each (the ten biggest per report, at most a few thousand tracked between reports), and sends them to Hammerhead with its regular report. Hammerhead keeps the history, draws the charts and raises traffic alerts. Nothing is stored on this machine, and a report that fails to arrive is added to the next one.
• Mail egress: delivers your mail server's outgoing mail straight to the recipient's server from a public IP you choose, with the HELO name you set, opportunistic STARTTLS, optional DKIM signing, MTA-STS enforcement, a per-minute send limit and a deliverability checklist.
• Tunnel: WireGuard through a userspace network stack, so no root, no kernel interface and no driver. It works on Windows, macOS and Linux, and sites behind NAT connect out to it.

Deploying

Releases are built by Gitea Actions. Pushing a tag such as v0.2.0 runs .gitea/workflows/release.yml, which tests the code, builds Blacktip for Linux (amd64) and Windows (amd64), publishes the archives with a SHA256SUMS file on the Releases page, and pushes a container image (linux/amd64) to this server's registry (git.veillax.com/veillax/blacktip). Every push and pull request runs .gitea/workflows/ci.yml: formatting, vet, tests, and a check that every release platform still compiles.

On a Linux server (systemd)

curl -LO https://git.veillax.com/Veillax/blacktip/releases/download/v0.1.0/blacktip_v0.1.0_linux_amd64.tar.gz
curl -LO https://git.veillax.com/Veillax/blacktip/releases/download/v0.1.0/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
tar xzf blacktip_v0.1.0_linux_amd64.tar.gz && cd blacktip_v0.1.0_linux_amd64
sudo ./install.sh                 # installs the binary and a hardened systemd service
sudoedit /etc/blacktip/blacktip.env   # your settings and secrets
sudo systemctl start blacktip

Releases are published for x86-64 only; for ARM machines build it yourself (TARGETS=linux/arm64 sh deploy/build.sh). To upgrade, repeat the same steps: your settings and data are kept. sudo ./install.sh --uninstall removes the service and binary but leaves /etc/blacktip and /var/lib/blacktip alone. blacktip -version tells you which build is running.

Updates

Set BLACKTIP_AUTO_UPDATE=1 (or pass -auto-update) and Blacktip checks this server for a newer release every few hours, verifies it against SHA256SUMS, checks that the new binary runs, swaps it in and restarts itself. It only follows full releases (never pre-releases), never downgrades, and keeps the old binary if anything looks wrong. setup.sh turns it on. It is not available on Windows, and it is for the systemd and plain-binary installs: with Docker, pull a new image instead.

With Docker

cp .env.example .env              # fill it in
docker compose -f deploy/docker-compose.yml up -d

The image is git.veillax.com/veillax/blacktip:<version> (and :latest for full releases). The compose file is in the repository and inside each Linux archive.

Setting up the build (once)

• A Gitea Actions runner with the label ubuntu-latest, and Docker on it if you want the container image.
• Nothing else is required: the workflows use the automatic job token. If your server doesn't let that token publish releases or packages, add the secrets RELEASE_TOKEN and REGISTRY_TOKEN (access tokens with release and package write permission) and optionally the variable REGISTRY_USER.
• To skip the container image, set the repository variable PUBLISH_DOCKER to false.
• Build locally with sh deploy/build.sh (archives in dist/).

Build and test

go env -w GOPRIVATE=git.veillax.com   # once, so Go fetches straight from this server
go build -o bin/ ./cmd/blacktip
go test ./...

The end-to-end tests that run Blacktip together with Hammerhead and Bamboo live in the Hammerhead repository.

License

AGPL-3.0. See LICENSE.