diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f030af8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,51 @@
+# Build and Set Up a Github-compatible Forgejo Runner on Proxmox
+
+In order for Forgejo workflows to be usable out-of-the-box with as many
+actions as possible, it is useful to habe a runner that supports the same
+tools as the standard Github runner `ubuntu-latest`. Github does publish the
+code they use to build their runner images at
+https://github.com/actions/runner-images, but that repo cannot be used
+directly to build KVM images for use with Proxmox.
+
+The fork https://github.com/fffonion/runner-images-kvm has the necessary
+changes to enable building such images.
+
+## Building the KVM runner image
+
+The script `build-github-runner-kvm-ubuntu-latest-qcow.sh` installs the
+necessary package dependencies to build a KVM image, Hashicorp Packer (in
+the latest version still licensend under the MPL), and builds the Ubuntu
+image (24.04 at the moment). The resulting image
+`github-runner-image-ubuntu-24.04.qcow2` can then be used in Proxmox, or any
+other KVM based virtualization solution.
+
+## Creating a Proxmox template VM
+
+The script `build-forgejorunner-template.sh` runs on a Proxmox cluster host.
+It runs the build script via SSH on a builder VM (that has nested virtualization
+enabled), in case of CCCHH a Debian 12 install. It then copies the resulting VM to the
+Proxmox host.
+
+It creates a template VM from the image, installing https://code.forgejo.org/forgejo/runner
+and some helper scripts.
+
+## Cloning the Template VM
+
+You can clone the template VM from the GUI, or through `qm clone`. Make the
+necessary changes and boot the VM.
+
+You can clone and register the runner using the script
+`clone-and-register.sh`.
+
+## Registering the Runner
+
+You can run the registration by logging in to the VM either on the console
+or through SSH, by running `forgejo-runner register` as the `forgejo-runner`
+user, or by invoking `/usr/local/bin/register-forgejo-runner`, supplying the
+registration token as the first argument.
+
+You can run the registration from the Proxmox cluster host:
+```
+qm guest exec 150 -- sudo -iu forgejo-runner register-forgejo-runner iwKWPwI3H6h93kRuhXqMPcmCR2OGpgZlDT3mufGb
+qm guest exec 150 -- systemctl restart forgejo-runner
+```
diff --git a/build-forgejorunner-template.sh b/build-forgejorunner-template.sh
index 288c8b9..04e1cd4 100755
--- a/build-forgejorunner-template.sh
+++ b/build-forgejorunner-template.sh
@@ -19,20 +19,26 @@ vm_storage="local-zfs"
 #ssh ${builder_host} sudo sh <${builder_script}
 #scp ${builder_host}:${runner_image} .
 
-#wget --output-document=forgejo_runner ${forgejo_runner_url} 
+wget --output-document=forgejo-runner ${forgejo_runner_url} 
 wget -N https://git.hamburg.ccc.de/CCCHH/infrastructure-authorized-keys/raw/branch/trunk/authorized_keys
 
 virt-customize -a ${runner_image} \
 	--update \
+	--run-command 'apt dist-upgrade -y' \
 	--install qemu-guest-agent \
 	--run-command 'systemctl enable fstrim.timer' \
 	--edit '/etc/passwd:$_ = "" if /^forgejo:/' \
 	--edit '/etc/group:$_ = "" if /^forgejo:/' \
-	--run-command 'useradd --groups docker --create-home --shell /bin/bash --uid 2000 --user-group forgejo' \
-	--copy-in forgejo_runner:/usr/local/bin \
-	--run-command 'chown root:bin /usr/local/bin/forgejo_runner' \
-	--run-command 'chmod 0555 /usr/local/bin/forgejo_runner' \
+	--run-command 'useradd --groups docker --create-home --shell /bin/bash --uid 2000 --user-group forgejo-runner' \
+	--copy-in forgejo-runner:/usr/local/bin \
+	--run-command 'chown root:bin /usr/local/bin/forgejo-runner' \
+	--run-command 'chmod 0555 /usr/local/bin/forgejo-runner' \
 	--copy-in forgejo-runner.service:/etc/systemd/system \
+	--copy-in register-forgejo-runner.sh:/usr/local/bin \
+	--run-command "mv /usr/local/bin/register-forgejo-runner.sh /usr/local/bin/register-forgejo-runner" \
+	--run-command "chown root:bin /usr/local/bin/register-forgejo-runner" \
+	--run-command "chmod +x /usr/local/bin/register-forgejo-runner" \
+
 
 qm destroy ${vm_id} || true
 qm create ${vm_id} --name "${vm_name}" --memory 2048 --net0 virtio,bridge=${vm_bridge}
diff --git a/build-github-runner-kvm-ubuntu-latest-qcow.sh b/build-github-runner-kvm-ubuntu-latest-qcow.sh
index ef5dce9..c2b8673 100755
--- a/build-github-runner-kvm-ubuntu-latest-qcow.sh
+++ b/build-github-runner-kvm-ubuntu-latest-qcow.sh
@@ -31,5 +31,5 @@ cd runner-images-kvm/images/ubuntu/templates
 packer init ubuntu-24.04.pkr.hcl
 packer build ubuntu-24.04.pkr.hcl
 cd ${HERE}
-mv runner-images-kvm/images/ubuntu/templates/output-custom_image/ubuntu-24.04 github-runner-image-ubuntu-24.04.qcow
+mv runner-images-kvm/images/ubuntu/templates/output-custom_image/ubuntu-24.04 github-runner-image-ubuntu-24.04.qcow2
 rm -r runner-images-kvm
diff --git a/clone-and-register.sh b/clone-and-register.sh
new file mode 100644
index 0000000..289c499
--- /dev/null
+++ b/clone-and-register.sh
@@ -0,0 +1,24 @@
+#!/bin/sh
+
+#
+# Clone the template VM and register the runner with Forgejo
+#
+
+if [ $# -ne 2 ]; then
+	echo "usage: $0 vmid registration-token"
+fi
+
+vm_id="$1"
+token="$2"
+
+qm clone 9042 ${vm_id}
+qm start ${vm_id}
+while :; do
+	qm agent ${vm_id} ping && break
+	echo "waiting for VM ${vm_id} to complete boot..."
+	sleep 10
+done
+
+qm guest exec ${vm_id} -- sudo -iu forgejo-runner register-forgejo-runner "${token}"
+qm guest exec ${vm_id} -- systemctl restart forgejo-runner
+
diff --git a/forgejo-runner b/forgejo-runner
new file mode 100644
index 0000000..470763c
Binary files /dev/null and b/forgejo-runner differ
diff --git a/register-forgejo-runner.sh b/register-forgejo-runner.sh
new file mode 100644
index 0000000..1581df6
--- /dev/null
+++ b/register-forgejo-runner.sh
@@ -0,0 +1,14 @@
+#!/bin/sh
+
+if [ -z "$1" ]; then
+	echo "usage: $0 <registration token>"
+	exit 64
+fi
+
+rel="$(lsb_release -rs 2>/dev/null)"
+
+forgejo-runner register --no-interactive \
+  --name "ubuntu-${rel}-$(hostname)" \
+  --instance https://git.hamburg.ccc.de/ \
+  --labels ubuntu-latest:host://-self-hosted,ubuntu-${rel}:host://-self-hosted \
+  --token "$1"