Bamboo/README.md

Bamboo

Bamboo runs inside your home or private network. It dials out to Blacktip over WireGuard, so it works behind NAT, and passes traffic to your real services. It can also list your Docker containers as targets and run a local mail relay for outgoing mail.

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 Sites → add a site. The dashboard shows the exact command with your token. It looks like this:

bamboo -hammerhead https://hammerhead.example.com -token <site token> -docker

Bamboo only makes outbound connections (HTTPS to Hammerhead, and WireGuard UDP to each edge), so it needs no open ports and no port forwarding.

Flag	Environment	Meaning
-hammerhead	BAMBOO_HAMMERHEAD	URL of Hammerhead
-token	BAMBOO_TOKEN	the site's token
-data	BAMBOO_DATA	folder for this agent's WireGuard key (default ./bamboo-data)
-docker	BAMBOO_DOCKER=1	report local Docker containers so they can be picked as targets
-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

• Tunnel: one WireGuard peer per edge, through a userspace network stack (no root, no kernel interface, no driver; works on Windows, macOS and Linux). Its private key never leaves this machine. TCP connections and native UDP datagrams are accepted from the edge and handed to your services.
• Docker discovery: with -docker, lists running containers (and their ports and networks) so you can pick one as a target in the dashboard.
• Mail relay: for a mail egress configured in the dashboard, opens a small SMTP relay on this machine (default 127.0.0.1:2525). Point your mail server at it (Postfix: relayhost = [127.0.0.1]:2525) and each outgoing message leaves from the edge's public IP, so reverse DNS, SPF and your HELO name line up. Supports AUTH PLAIN/LOGIN, requires a password if it listens beyond 127.0.0.1, relays one destination domain per transaction (extra domains get 452 so your server resends them separately), and passes your server's queue and retries through unchanged. 50 MB message limit.

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 Bamboo for Linux (amd64, arm64, armv7), Windows (amd64) and macOS (amd64, arm64), publishes the archives with a SHA256SUMS file on the Releases page, and pushes a multi-architecture container image to this server's registry (git.veillax.com/veillax/bamboo). 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/bamboo/releases/download/v0.1.0/bamboo_v0.1.0_linux_amd64.tar.gz
curl -LO https://git.veillax.com/Veillax/bamboo/releases/download/v0.1.0/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
tar xzf bamboo_v0.1.0_linux_amd64.tar.gz && cd bamboo_v0.1.0_linux_amd64
sudo ./install.sh                 # installs the binary and a hardened systemd service
sudoedit /etc/bamboo/bamboo.env   # your settings and secrets
sudo systemctl start bamboo

Use linux_arm64 or linux_arm for Raspberry Pi and other ARM machines. To upgrade, repeat the same steps: your settings and data are kept. sudo ./install.sh --uninstall removes the service and binary but leaves /etc/bamboo and /var/lib/bamboo alone. bamboo -version tells you which build is running.

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/bamboo:<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/bamboo
go test ./...

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

License

AGPL-3.0. See LICENSE.