VeillaxandClaude Sonnet 5.5
2e7cb8171f
The site agent: a WireGuard peer that dials out to each edge, accepts TCP streams and native UDP datagrams inside the tunnel, lists local Docker containers, and runs the local SMTP relay for mail egress. Split out of the original single repository; depends on Reef for the shared types. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
46 lines
2.9 KiB
Markdown
46 lines
2.9 KiB
Markdown
# 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](https://git.veillax.com/Veillax/hammerhead) (control plane and dashboard) · [Blacktip](https://git.veillax.com/Veillax/blacktip) (edge) · **Bamboo** (site agent) · [Reef](https://git.veillax.com/Veillax/reef) (shared library). Everything is configured from Hammerhead's web dashboard; the full documentation lives in [its README](https://git.veillax.com/Veillax/hammerhead).
|
|
|
|
## 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.
|
|
|
|
## 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`.
|