1 files changed, 70 insertions, 0 deletions
diff --git a/docs/design/2026-08-07-podman-socket-and-camera-udev.md b/docs/design/2026-08-07-podman-socket-and-camera-udev.md
new file mode 100644
index 0000000..7eb99e8
--- /dev/null
+++ b/docs/design/2026-08-07-podman-socket-and-camera-udev.md
@@ -0,0 +1,70 @@
+# Enable podman.socket at install time (and one related USB rule)
+
+From winvm, 2026-08-07 on ratio.
+
+## 1. The ask: enable the rootless podman socket
+
+    systemctl --user enable --now podman.socket
+
+**What was wrong.** On ratio this was `disabled` / `inactive`, and
+`$XDG_RUNTIME_DIR/podman/podman.sock` did not exist at all. Podman's CLI does
+not need it, so nothing surfaces the gap until something speaks the REST API.
+
+**Why it matters.** Every podman GUI and API client connects over that socket
+rather than by shelling out. I installed Pods (`com.github.marhkb.Pods`,
+flathub) to manage the Windows VM container, and without the socket it opens to
+an empty window with no useful error — it looks like the app is broken or has no
+containers, when in fact there is nothing listening. That is a bad first-run
+experience and a hard one to diagnose from the symptom.
+
+It is socket-activated, so enabling it costs nothing while idle: podman starts
+on demand when a client connects, and `enable` brings the socket back on login
+without a daemon sitting resident. This is the ordinary way to run the podman
+API rootless.
+
+**Verified after enabling:** socket present at
+`/run/user/1000/podman/podman.sock`, the API answers
+`/v5.0.0/libpod/containers/json`, and it reported the `WinVM` container.
+
+**One Flatpak note worth recording**, because it looks like a problem and is
+not. The Pods flatpak ships `xdg-run/podman:ro` in its filesystem permissions,
+which reads as though a client could not connect. Tested from inside the
+sandbox: the socket is visible, and both readable *and writable*, so the
+read-only directory mount does not block the connection. No `flatpak override`
+is needed.
+
+**Client-side, not your problem but context:** Pods stores connections in
+`~/.var/app/com.github.marhkb.Pods/config/pods/` and only writes that file after
+the user adds a connection through the UI, so it can't be pre-seeded from an
+install script without inventing the format. The one-time step is adding
+`unix:///run/user/1000/podman/podman.sock` as a connection; a
+`last-used-connection` gsetting makes it stick after that. So the *socket* is
+the part worth automating, and the connection is not.
+
+## 2. Related, same category — a udev rule for USB camera passthrough
+
+Filing this alongside because it is the same class of one-time machine-level
+setup and it will bite on velox the same way. Take it or leave it separately
+from item 1.
+
+`/etc/udev/rules.d/99-usb-passthrough-cameras.rules`:
+
+    SUBSYSTEM=="usb", ATTR{idVendor}=="3564", ATTR{idProduct}=="ff02", GROUP="video", MODE="0660", TAG+="uaccess"
+    SUBSYSTEM=="usb", ATTR{idVendor}=="046d", ATTR{idProduct}=="085e", GROUP="video", MODE="0660", TAG+="uaccess"
+
+(3564:ff02 is the OBSBOT, 046d:085e the Logitech BRIO.)
+
+**Why.** Streaming a USB camera into the VM runs `usbredirect`, which must open
+the device read-write to claim it and detach the kernel drivers. The node
+defaults to `crw-rw-r-- root:root`, so a normal user has read but no write and
+the attach fails with a bare "Failed to open device!".
+
+**The part worth writing down:** `TAG+="uaccess"` alone is NOT enough, though it
+looks like the right answer and `udevadm test` confirms the tag is applied.
+logind does not turn that tag into an ACL on a raw `/dev/bus/usb/*` node — it
+manages ACLs for a narrower set of seat devices. The `GROUP`/`MODE` grant is
+what actually works. The tag is kept because it is harmless and correct in
+principle; it just isn't sufficient. I lost time on that, so it is recorded
+rather than left to be rediscovered.
+
+Both items are live on ratio and neither exists on velox.