diff --git a/README.md b/README.md index ded94fe..b2b269d 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,53 @@ # vuinputd -A minimal **CUSE-based proxy for `/dev/uinput`** that lets unmodified applications (like [Sunshine](https://github.com/LizardByte/Sunshine)) run inside a container while creating virtual input devices on the host. + +A minimal **CUSE-based proxy for `/dev/uinput`** that lets unmodified applications (like [Sunshine](https://github.com/LizardByte/Sunshine)) run inside containers while creating virtual input devices safely on the host. + +> **Run Sunshine and other uinput-based apps inside containers โ€” with full input isolation and zero kernel patches.** + +--- ## Overview -This project makes it possible to run [Sunshine](https://github.com/LizardByte/Sunshine) inside `systemd-nspawn` containers without breaking input isolation. +Containerizing input-producing software (e.g. Sunshine, Moonlight host replacements, remote desktop servers) improves separation and simplifies deployment. +However, exposing the hostโ€™s `/dev/uinput` directly into a container breaks isolation: -Normally, Sunshine creates virtual input devices via `/dev/uinput`. If `/dev/uinput` is simply bind-mounted into a container: +* Containers can create devices visible system-wide or to other containers. +* Keyboards and mice may attach to host seats or inject input into active host sessions. -* Devices from one container can leak into another. -* Keyboards and mice may attach to host seats that are attached to a running session. +`vuinputd` solves this by introducing a **mediated input stack**: -This project solves that by introducing a **mediated input stack**: +* A **fake `/dev/uinput`** inside each container. +* A **host proxy daemon** that safely creates the actual devices via `/dev/uinput`. +* The proxy **forwards add/remove udev events** into the container so SDL2, Wayland, and libinput see devices natively. +* **udev rules** tag and isolate devices per container, preventing the host from consuming them. -* A **fake `/dev/uinput`** inside the container. -* A daemon that **forward** add/remove events into the container, making SDL2 and Wayland/libinput behave correctly. -* A **host proxy** that safely creates the real devices. -* **udev rules** that tag and isolate devices per-container. +Applications use `/dev/uinput` unmodified, and the mediation adds **negligible overhead**. --- ## Architecture -* **Container**: Sunshine writes to fake `/dev/uinput`. -* **Host Proxy**: Creates real devices on the host, labeled with container identity Forwards add/remove events into the container, so SDL2 and Wayland see devices natively. -* **udev**: Matches by identity, prevents host use. +* **Container:** The app writes to the fake `/dev/uinput`. +* **Host Proxy:** Creates real devices on the host (labeled with container identity); forwards add/remove events back into the container. +* **udev:** Matches devices by identity and prevents the host input stack from attaching. + +This design works with any container runtime โ€” **systemd-nspawn, Docker, LXC, Podman**, and others. --- ## Benefits -* ๐ŸŽฎ **SDL2 / Wayland compatibility**: fake-udev ensures compositors and games see device events properly. -* ๐Ÿ”’ **Isolation**: containers only see their own devices; host also sees them, but ignores them completely. -* โ™ป๏ธ **Lifecycle safety**: devices are removed cleanly when Sunshine stops. -* ๐Ÿ› ๏ธ **Simple integration**: no kernel patches, just userspace tools + udev rules. +* ๐ŸŽฎ **SDL2 & Wayland compatibility:** `vuinputd` ensures compositors and games recognize input devices correctly. +* ๐Ÿ”’ **Strong isolation:** Containers see only their own devices; the host sees them but ignores them completely. +* โ™ป๏ธ **Safe lifecycle:** Devices are removed cleanly when the containerized app stops. +* ๐Ÿ› ๏ธ **Simple integration:** No kernel patches required โ€” only userspace tools and udev rules. --- ## Documentation -See [docs/BUILD.md](docs/BUILD.md) for short build and install guide. -See [docs/DESIGN.md](docs/DESIGN.md) for detailed architecture, design tradeoffs, and security considerations. +See [docs/BUILD.md](docs/BUILD.md) for a short build and installation guide. +See [docs/DESIGN.md](docs/DESIGN.md) for a detailed overview of the architecture, design trade-offs, and security considerations. ---