Mirrors/vuinputd
1
0
Fork 0
mirror of https://github.com/joleuger/vuinputd.git synced 2026-07-29 05:50:17 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

improve readme

Browse source
This commit is contained in:
Johannes Leupolz 2025-10-24 22:05:37 +00:00
parent a23e01486c
commit 1f8b0b7c77
1 changed files with 27 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

46
README.md
View file

@ -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.
---