From 05079fb24ad90fb20eb580c46f92eb7d19783a63 Mon Sep 17 00:00:00 2001
From: Jarvis <jarvis@johnmaguire.me>
Date: Thu, 19 Feb 2026 07:22:25 +0000
Subject: [PATCH] Initial commit: DNClient Home Assistant add-on

---
 README.md             | 32 ++++++++++++++++++++++++++++++++
 dnclient/CHANGELOG.md |  8 ++++++++
 dnclient/DOCS.md      | 24 ++++++++++++++++++++++++
 dnclient/Dockerfile   |  7 +++++++
 dnclient/build.yaml   |  3 +++
 dnclient/config.yaml  | 17 +++++++++++++++++
 dnclient/run.sh       | 26 ++++++++++++++++++++++++++
 repository.json       |  5 +++++
 8 files changed, 122 insertions(+)
 create mode 100644 README.md
 create mode 100644 dnclient/CHANGELOG.md
 create mode 100644 dnclient/DOCS.md
 create mode 100644 dnclient/Dockerfile
 create mode 100644 dnclient/build.yaml
 create mode 100644 dnclient/config.yaml
 create mode 100644 dnclient/run.sh
 create mode 100644 repository.json

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d2819c0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,32 @@
+# Home Assistant Add-on: DNClient (Defined Networking)
+
+Run [Defined Networking's DNClient](https://www.defined.net/) (Managed Nebula) as a Home Assistant add-on to provide overlay network connectivity to your Home Assistant OS instance.
+
+## Installation
+
+1. In Home Assistant, go to **Settings → Add-ons → Add-on Store**
+2. Click the **⋮** menu (top right) → **Repositories**
+3. Add this repository URL: `https://github.com/johnmaguire/homeassistant-addon-dnclient`
+4. Find **DNClient** in the store and click **Install**
+
+## Configuration
+
+| Option | Description |
+|--------|-------------|
+| `enrollment_code` | Your enrollment code from the [Defined Networking Admin Panel](https://admin.defined.net). Only needed for first run. |
+
+### First Run
+
+1. Generate an enrollment code from [admin.defined.net](https://admin.defined.net)
+2. Paste it into the add-on configuration
+3. Start the add-on
+4. Once enrolled, you can clear the enrollment code — the host identity is persisted
+
+## How It Works
+
+The add-on runs `dnclient` with host networking and `NET_ADMIN` capability so it can create the Nebula tun interface directly on the Home Assistant host. Configuration is persisted in the add-on's data directory, so the host only needs to enroll once.
+
+## Supported Architectures
+
+- `amd64`
+- `aarch64`
diff --git a/dnclient/CHANGELOG.md b/dnclient/CHANGELOG.md
new file mode 100644
index 0000000..dead57b
--- /dev/null
+++ b/dnclient/CHANGELOG.md
@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release
+- Runs dnclient with host networking and NET_ADMIN capability
+- Persistent enrollment across restarts
+- Supports amd64 and aarch64
diff --git a/dnclient/DOCS.md b/dnclient/DOCS.md
new file mode 100644
index 0000000..8191445
--- /dev/null
+++ b/dnclient/DOCS.md
@@ -0,0 +1,24 @@
+# DNClient Add-on for Home Assistant
+
+## About
+
+This add-on runs [Defined Networking's DNClient](https://www.defined.net/) on your Home Assistant OS instance, giving it connectivity to your Managed Nebula overlay network.
+
+## Setup
+
+1. Go to [admin.defined.net](https://admin.defined.net) and create a host for your Home Assistant instance
+2. Generate an enrollment code for the host
+3. Paste the enrollment code into this add-on's configuration
+4. Start the add-on
+
+After the first successful enrollment, the host identity is persisted. You can clear the enrollment code from the configuration — it won't be needed again unless you re-enroll.
+
+## Network
+
+The add-on uses **host networking** so the Nebula tun interface is created directly on the Home Assistant host. This means other add-ons and Home Assistant itself can communicate over the Nebula network.
+
+## Troubleshooting
+
+- Check the add-on logs for enrollment or connection errors
+- Ensure the enrollment code hasn't expired (they are single-use)
+- If you need to re-enroll, stop the add-on, clear the persistent data, set a new enrollment code, and restart
diff --git a/dnclient/Dockerfile b/dnclient/Dockerfile
new file mode 100644
index 0000000..f874e68
--- /dev/null
+++ b/dnclient/Dockerfile
@@ -0,0 +1,7 @@
+ARG BUILD_FROM=definednet/dnclient:latest
+FROM ${BUILD_FROM}
+
+COPY run.sh /
+RUN chmod a+x /run.sh
+
+CMD [ "/run.sh" ]
diff --git a/dnclient/build.yaml b/dnclient/build.yaml
new file mode 100644
index 0000000..de6717e
--- /dev/null
+++ b/dnclient/build.yaml
@@ -0,0 +1,3 @@
+build_from:
+  amd64: definednet/dnclient:latest
+  aarch64: definednet/dnclient:latest
diff --git a/dnclient/config.yaml b/dnclient/config.yaml
new file mode 100644
index 0000000..b31ddae
--- /dev/null
+++ b/dnclient/config.yaml
@@ -0,0 +1,17 @@
+name: DNClient
+version: "0.1.0"
+slug: dnclient
+description: "Run Defined Networking's DNClient (Managed Nebula) on Home Assistant OS"
+url: "https://github.com/johnmaguire/homeassistant-addon-dnclient"
+arch:
+  - amd64
+  - aarch64
+startup: system
+boot: auto
+host_network: true
+privileged:
+  - NET_ADMIN
+options:
+  enrollment_code: ""
+schema:
+  enrollment_code: "str?"
diff --git a/dnclient/run.sh b/dnclient/run.sh
new file mode 100644
index 0000000..b1005de
--- /dev/null
+++ b/dnclient/run.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env sh
+set -e
+
+CONFIG_DIR="/data/defined"
+SYSTEM_DIR="/etc/defined"
+
+# Ensure persistent config directory exists
+mkdir -p "${CONFIG_DIR}"
+
+# Symlink /etc/defined -> /data/defined for persistence across restarts
+if [ ! -L "${SYSTEM_DIR}" ]; then
+    rm -rf "${SYSTEM_DIR}"
+    ln -s "${CONFIG_DIR}" "${SYSTEM_DIR}"
+fi
+
+# Read enrollment code from HA options
+ENROLLMENT_CODE="$(cat /data/options.json | sed -n 's/.*"enrollment_code" *: *"\([^"]*\)".*/\1/p')"
+
+# Only set enrollment code if non-empty and host is not already enrolled
+if [ -n "${ENROLLMENT_CODE}" ] && [ ! -f "${CONFIG_DIR}/config.yml" ]; then
+    export DN_ENROLLMENT_CODE="${ENROLLMENT_CODE}"
+    echo "Enrolling host with provided enrollment code..."
+fi
+
+echo "Starting dnclient..."
+exec dnclient
diff --git a/repository.json b/repository.json
new file mode 100644
index 0000000..f380e5a
--- /dev/null
+++ b/repository.json
@@ -0,0 +1,5 @@
+{
+  "name": "Defined Networking Add-ons",
+  "url": "https://github.com/johnmaguire/homeassistant-addon-dnclient",
+  "maintainer": "John Maguire"
+}