diff --git a/nixos/README_VNC.md b/nixos/README_VNC.md
new file mode 100644
index 0000000..7c4febe
--- /dev/null
+++ b/nixos/README_VNC.md
@@ -0,0 +1,62 @@
+# VNC Desktop Setup
+
+Web-accessible virtual desktop at `vnc.quinefoundation.com`, running TigerVNC + noVNC in a Podman container.
+
+## First-time setup
+
+### 1. Create the VNC password secret
+
+```bash
+printf "VNC_PASSWORD=yourpassword\n" | nix run nixpkgs#age -- \
+  -r "$(cat /root/petersweb-infra/nixos/keys/mainframe.pub)" \
+  -o /root/petersweb-infra/nixos/secrets/vnc-password.age
+```
+
+### 2. Create the nginx basic auth secret
+
+Generate an htpasswd entry (requires `apache2-utils` or `httpd-tools`):
+
+```bash
+htpasswd -n admin
+# Enter password when prompted; copy the output line (e.g. admin:$apr1$...)
+```
+
+Encrypt it:
+
+```bash
+printf "admin:\$apr1\$...\n" | nix run nixpkgs#age -- \
+  -r "$(cat /root/petersweb-infra/nixos/keys/mainframe.pub)" \
+  -o /root/petersweb-infra/nixos/secrets/vnc-htpasswd.age
+```
+
+### 3. Build and push the container image
+
+```bash
+cd nixos/vnc-desktop
+docker build -t forge.quinefoundation.com/ironmagma/vnc-desktop:latest .
+docker push forge.quinefoundation.com/ironmagma/vnc-desktop:latest
+```
+
+### 4. Commit the new secrets and apply
+
+```bash
+git add nixos/secrets/vnc-password.age nixos/secrets/vnc-htpasswd.age
+git commit -m "add vnc secrets"
+git push
+./nixos/apply.sh
+```
+
+## Accessing the desktop
+
+Visit `https://vnc.quinefoundation.com/vnc.html` in a browser. You'll be prompted for:
+
+1. **HTTP basic auth** — the username/password from step 2 above
+2. **VNC password** — the `VNC_PASSWORD` from step 1 above
+
+## SSHing to the host from inside the container
+
+The host machine is reachable as `hetzner-host` from within the container, and the host's SSH keys are mounted read-only at `/root/host-ssh/`:
+
+```bash
+ssh -i /root/host-ssh/id_rsa root@hetzner-host
+```