From cd453221f6caf77dc4ae3a3ef7a47be8a6352a7f Mon Sep 17 00:00:00 2001 From: Veillax <126523099+Veillax@users.noreply.github.com> Date: Mon, 26 Oct 2026 23:16:37 -0600 Subject: [PATCH] Bamboo add-on for Home Assistant Co-Authored-By: Claude Sonnet 5.5 --- .gitignore | 3 +++ README.md | 19 +++++++++++++++- bamboo/CHANGELOG.md | 5 +++++ bamboo/DOCS.md | 44 +++++++++++++++++++++++++++++++++++++ bamboo/Dockerfile | 30 +++++++++++++++++++++++++ bamboo/build.yaml | 4 ++++ bamboo/config.yaml | 21 ++++++++++++++++++ bamboo/run.sh | 19 ++++++++++++++++ bamboo/translations/en.yaml | 7 ++++++ repository.yaml | 3 +++ 10 files changed, 154 insertions(+), 1 deletion(-) create mode 100644 .gitignore create mode 100644 bamboo/CHANGELOG.md create mode 100644 bamboo/DOCS.md create mode 100644 bamboo/Dockerfile create mode 100644 bamboo/build.yaml create mode 100644 bamboo/config.yaml create mode 100644 bamboo/run.sh create mode 100644 bamboo/translations/en.yaml create mode 100644 repository.yaml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..40ed403 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +# editors and local builds +.DS_Store +Thumbs.db diff --git a/README.md b/README.md index 9c8c78d..9ca74d1 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,19 @@ -# bamboo-ha +# Bamboo for Home Assistant +A Home Assistant add-on (also called an app) that runs [Bamboo](https://git.veillax.com/Veillax/bamboo), the site agent of the Hammerhead stack. It connects your home network to a Blacktip edge over WireGuard, so Home Assistant and your other devices can be reached from the internet without opening ports on your router. + +## Install + +1. In Home Assistant, go to **Settings**, then **Add-ons**, then **Add-on store**. +2. Open the menu at the top right, choose **Repositories**, and add `https://git.veillax.com/Veillax/bamboo-ha`. +3. Install **Bamboo**, fill in its configuration, and start it. See the add-on's Documentation tab for the details, including the `http:` setting Home Assistant needs. + +It builds on your Home Assistant machine the first time you install it. It supports amd64, aarch64 and armv7. + +## For maintainers + +The add-on version is the Bamboo release it installs: version `0.1.5` downloads Bamboo `v0.1.5` and checks it against that release's `SHA256SUMS`. To follow a new Bamboo release, change `version` in `bamboo/config.yaml` (and the default of `BUILD_VERSION` in `bamboo/Dockerfile`), and add a line to `bamboo/CHANGELOG.md`. + +## License + +AGPL-3.0, the same as Bamboo. See `LICENSE`. diff --git a/bamboo/CHANGELOG.md b/bamboo/CHANGELOG.md new file mode 100644 index 0000000..112ce41 --- /dev/null +++ b/bamboo/CHANGELOG.md @@ -0,0 +1,5 @@ +# Changelog + +## 0.1.5 + +* First version of the add-on. Installs Bamboo v0.1.5. diff --git a/bamboo/DOCS.md b/bamboo/DOCS.md new file mode 100644 index 0000000..b2816d9 --- /dev/null +++ b/bamboo/DOCS.md @@ -0,0 +1,44 @@ +# Bamboo + +Bamboo connects your home network to a Blacktip edge over WireGuard. Websites and ports you open in Hammerhead can then reach Home Assistant, and any other device at home, without opening a port on your router. Bamboo only makes outbound connections. + +## Set up + +1. In Hammerhead, open **Sites**, choose **Add site**, and copy the site's token with **Show command**. +2. Install this add-on and open its **Configuration** tab. +3. Enter the **Hammerhead address** (for example `https://hammerhead.example.com`) and the **Site token**, then save. +4. Start the add-on. The site shows as online in Hammerhead within a few seconds, and the add-on's log says `WireGuard up`. + +## Reach Home Assistant from the internet + +Add a resource in Hammerhead: + +* **What are you sharing:** Website +* **Where does it point:** this site, host `127.0.0.1`, port `8123` +* **How do people reach it:** your hostname, for example `home.example.com` + +Home Assistant refuses requests that come through a proxy unless it trusts the proxy. Bamboo connects from the same machine, so add this to `configuration.yaml` and restart Home Assistant: + +```yaml +http: + use_x_forwarded_for: true + trusted_proxies: + - 127.0.0.1 + - ::1 +``` + +Without it, the page fails with "400: Bad Request". Home Assistant has its own sign-in, so you can leave the resource without a login in Hammerhead, or put one in front for a second layer. + +## Reach other devices at home + +The add-on uses host networking, so a resource can also point at any address on your network, such as a camera at `192.168.1.40`. Pick this site as the target and enter that address and port. + +## Updates + +The add-on version is the Bamboo release it installs. Update it from the add-on's page when a new version appears. Bamboo's own auto-update is not used here, because a new version arrives as an add-on update instead. Your WireGuard key and settings are kept across updates. + +## Troubleshooting + +* **The log asks for configuration:** the address or token is empty. +* **The site stays offline:** check that the address opens in a browser from the same network, and that the token belongs to a site, not an edge. +* **Home Assistant shows "400: Bad Request":** add the `http:` block above. diff --git a/bamboo/Dockerfile b/bamboo/Dockerfile new file mode 100644 index 0000000..cab93e6 --- /dev/null +++ b/bamboo/Dockerfile @@ -0,0 +1,30 @@ +ARG BUILD_FROM +FROM ${BUILD_FROM} + +# The add-on version in config.yaml is the Bamboo release it installs (0.1.5 installs v0.1.5). +ARG BUILD_ARCH +ARG BUILD_VERSION=0.1.5 + +# Download the release for this CPU and check it against the release's SHA256SUMS before installing. +RUN set -eu; \ + case "${BUILD_ARCH}" in \ + amd64) arch=amd64 ;; \ + aarch64) arch=arm64 ;; \ + armv7) arch=arm ;; \ + *) echo "unsupported architecture: ${BUILD_ARCH}" >&2; exit 1 ;; \ + esac; \ + tag="v${BUILD_VERSION}"; \ + name="bamboo_${tag}_linux_${arch}"; \ + base="https://git.veillax.com/Veillax/bamboo/releases/download/${tag}"; \ + cd /tmp; \ + curl -fsSLO "${base}/${name}.tar.gz"; \ + curl -fsSLO "${base}/SHA256SUMS"; \ + grep " ${name}.tar.gz\$" SHA256SUMS | sha256sum -c -; \ + tar xzf "${name}.tar.gz"; \ + install -m 0755 "${name}/bamboo" /usr/local/bin/bamboo; \ + rm -rf /tmp/* + +COPY run.sh /run.sh +RUN chmod a+x /run.sh + +CMD [ "/run.sh" ] diff --git a/bamboo/build.yaml b/bamboo/build.yaml new file mode 100644 index 0000000..0418395 --- /dev/null +++ b/bamboo/build.yaml @@ -0,0 +1,4 @@ +build_from: + amd64: ghcr.io/home-assistant/amd64-base:3.21 + aarch64: ghcr.io/home-assistant/aarch64-base:3.21 + armv7: ghcr.io/home-assistant/armv7-base:3.21 diff --git a/bamboo/config.yaml b/bamboo/config.yaml new file mode 100644 index 0000000..44e007c --- /dev/null +++ b/bamboo/config.yaml @@ -0,0 +1,21 @@ +name: Bamboo +version: "0.1.5" +slug: bamboo +description: Connects Home Assistant and your home network to a Blacktip edge, so you can reach them from the internet without opening any ports. +url: https://git.veillax.com/Veillax/bamboo +arch: + - amd64 + - aarch64 + - armv7 +startup: services +boot: auto +init: false +# Bamboo only makes outbound connections. Host networking lets it reach Home Assistant at +# 127.0.0.1:8123 and every device on your home network. +host_network: true +options: + hammerhead_url: "" + token: "" +schema: + hammerhead_url: url + token: password diff --git a/bamboo/run.sh b/bamboo/run.sh new file mode 100644 index 0000000..2a135bf --- /dev/null +++ b/bamboo/run.sh @@ -0,0 +1,19 @@ +#!/usr/bin/with-contenv bashio +# Starts Bamboo with the address and token from the add-on's configuration. +set -e + +url="$(bashio::config 'hammerhead_url')" +token="$(bashio::config 'token')" + +if [ -z "${url}" ] || [ -z "${token}" ]; then + bashio::log.fatal "Set the Hammerhead address and the site token in this add-on's Configuration tab, then start it again." + bashio::exit.nok +fi + +# Settings go in through the environment so the token does not show up in the process list. +export BAMBOO_HAMMERHEAD="${url%/}" +export BAMBOO_TOKEN="${token}" + +bashio::log.info "Starting $(bamboo -version), connecting to ${BAMBOO_HAMMERHEAD}" +# /data survives restarts and updates; it holds this site's WireGuard key. +exec bamboo -data /data diff --git a/bamboo/translations/en.yaml b/bamboo/translations/en.yaml new file mode 100644 index 0000000..0615661 --- /dev/null +++ b/bamboo/translations/en.yaml @@ -0,0 +1,7 @@ +configuration: + hammerhead_url: + name: Hammerhead address + description: The address of your Hammerhead dashboard, such as https://hammerhead.example.com. + token: + name: Site token + description: The token of the site you created for this network. In Hammerhead, open Sites and use Show command to copy it. diff --git a/repository.yaml b/repository.yaml new file mode 100644 index 0000000..3bf4bc8 --- /dev/null +++ b/repository.yaml @@ -0,0 +1,3 @@ +name: Bamboo add-on repository +url: https://git.veillax.com/Veillax/bamboo-ha +maintainer: Veillax