Bamboo add-on for Home Assistant

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,3 @@
+# editors and local builds
+.DS_Store
+Thumbs.db

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`.

bamboo/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.5
+
+* First version of the add-on. Installs Bamboo v0.1.5.

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.

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" ]

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

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

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

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.

repository.yaml

@@ -0,0 +1,3 @@
+name: Bamboo add-on repository
+url: https://git.veillax.com/Veillax/bamboo-ha
+maintainer: Veillax