A modern web dashboard to manage your Linux system: Docker, WireGuard, updates, users, shares, sensors, and more, from one unified interface.
Linux I/O is built around a simple idea: your homelab should have a single control plane.
Its primary inspiration is Cockpit: one place to operate Linux systems end to end.
This project also draws inspiration from many projects across the homelab ecosystem, including FileBrowser Quantum, Portainer, Homepage, Unraid, and many others.
The file-management experience and visual style are intentionally very closely inspired by FileBrowser Quantum, as it fits very nicely into the app's theme so that influence is explicitly acknowledged.
LinuxIO's filesystem indexer follows up on the work done by FileBrowser Quantum and builds on its indexing code, reworked as a dedicated LinuxIO service. The goal is to provide a low-memory filesystem index with an on-demand API, fast(ish) full indexing, and efficient query responses.
Linux I/O combines workflows usually split across multiple tools:
- System administration (users, networking, updates, sensors)
- Container operations (Portainer-style Docker management)
- Secure remote access (WireGuard configuration)
- File operations (FileBrowser Quantum-style management)
Goal: One tool to rule them all: one login, one dashboard, one workflow for your Linux stack.
- PAM Authentication - Login with your Linux credentials
- Live System Stats - CPU, memory, disk, and network monitoring
- Metrics Daemon - First-party
linuxio-monitoringcollector with metrics history - Processes - Live process and program tables with CPU, memory, disk I/O, and container attribution
- Docker Manager - Container management
- WireGuard UI - VPN configuration
- File Explorer - Integrated file explorer
- Filesystem Indexer - Fast search, directory sizes, and scheduled indexing
- User Accounts - User management
- Share Manager - Samba/NFS shares
- NetworkManager - Network configuration
- Software Updates - PackageKit integration
- Hardware Sensors -
lm-sensorsand SMART monitoring - Terminal - Web-based command execution
LinuxIO supports Linux kernels 5.9+.
Step 1 — Install the bootstrap dependencies (PAM, PolicyKit, and PackageKit):
curl -fsSL https://raw.githubusercontent.com/mordilloSan/LinuxIO/main/packaging/scripts/install-dependencies.sh | sudo bashPackageKit is required because LinuxIO uses it for capability installation from the dashboard. Docker is separate from this bootstrap; when container support is needed, install it from the Capability Manager (which runs Docker's convenience script and shows its output) or run the script directly:
curl -fsSL https://get.docker.com | sudo shStep 2 — Install LinuxIO binaries:
curl -fsSL https://raw.githubusercontent.com/mordilloSan/LinuxIO/main/packaging/scripts/install-linuxio-binaries.sh | sudo bashUse the dashboard URL printed by the installer. It preserves an existing valid
LinuxIO port when possible, otherwise selects an available port from
8090–8099. After signing in, install optional capabilities such as sensors,
SMART monitoring, NFS, or Avahi from LinuxIO Capability Manager. Avahi
installation includes the required Debian mDNS NSS integration. On RHEL-family
hosts the responder remains usable if the optional nss-mdns package is
unavailable, and LinuxIO warns that EPEL may be needed for client-side .local
resolution. The dashboard is then reachable at
https://<your-hostname>.local:<port> using the same selected port. Installing
lm-sensors from the Capability Manager also runs the required
sensors-detect --auto hardware probe.
A versioned installation downloads immutable binaries from that release, but intentionally fetches current main systemd, PAM, configuration, MOTD, and
helper assets. This recovery policy lets packaging fixes repair already published releases; current packaging assets must therefore remain compatible
with supported historical binaries.
On first startup, LinuxIO creates a managed self-signed certificate in
/var/lib/linuxio/webserver/certificates. It covers localhost, the system
hostname, <hostname>.local, and the host's current IP addresses. The same
certificate is reused across restarts, reboots, and updates until it enters its
30-day renewal window.
The installer places eight binaries in /usr/local/bin: linuxio,
linuxio-webserver, linuxio-bridge, linuxio-auth, linuxio-docker-update,
linuxio-indexer, linuxio-monitoring, and linuxio-btrfs-timer. From a
checkout, make localinstall runs the same installer with --local against the
binaries in build/.
The first-party linuxio-monitoring binary is installed and enabled with
LinuxIO rather than through Capability Manager. It samples the host, keeps the
metrics history in /var/lib/linuxio/monitoring/metrics.db, and serves
read-only metrics on /run/linuxio/monitoring/api.sock with commands behind the
root-only /run/linuxio/monitoring/control.sock. Its strict YAML configuration
lives at /etc/linuxio/monitoring/config.yaml; see the
monitoring daemon guide for the sockets, sampling
semantics, configuration fields, and troubleshooting.
The first-party linuxio-indexer binary is installed with LinuxIO rather than
through Capability Manager. Its root-only Unix API is socket activated at
/run/linuxio/indexer.sock; the webserver keeps the daemon warm while it is
running, and the daemon exits after a fixed 90-second idle grace once the
webserver and active work are gone. A systemd timer requests periodic full indexing. Its two-field YAML
configuration and rebuildable cache live under /etc/linuxio/indexer and
/var/lib/linuxio/indexer; see the filesystem indexer guide
for permissions, lifecycle, and recovery.
What gets installed?
| Category | Packages | Required |
|---|---|---|
| PAM, PolicyKit, PackageKit | Authentication, authorization, system updates, and in-app capability installation | Mandatory bootstrap dependencies |
| Docker | Container management, installed from the Capability Manager with Docker's convenience script | Optional |
| Other capabilities | Sensors, SMART monitoring, NFS, Avahi, and other host facilities | Install from LinuxIO Capability Manager |
See the development guide for setup requirements, supported targets, and configurable overrides. The docs index lists the architecture, API-contract, and frontend guides.
- React 19.2.4 with TypeScript
- Vite for fast builds
- Material-UI (Mira theme)
- TanStack Query for data fetching
- Go 1.27
- Gorilla WebSocket
- PAM authentication
- Main Server: Handles HTTP/HTTPS and WebSocket connections
- Bridge Process: Per-user privileged operations with security isolation
- Indexer Process: Socket-activated SQLite/scanner owner with idle shutdown
- PAM-based authentication
- Session-based auth with secure cookies
- Socket-activated auth worker (no setuid)
- Isolated bridge processes per user
- Persistent managed TLS certificate with a private systemd state directory
See SECURITY.md for details.
LinuxIO/
|- backend/ # Go backend (HTTP + WebSocket)
|- frontend/ # React frontend (Vite + TypeScript)
|- docs/ # Architecture and development docs (plans in docs/TODO)
|- packaging/ # Installation scripts and helpers
|- scripts/ # Shell programs behind the Make targets
|- mk/ # Make targets by concern (go, frontend, auth, quality, install)
|- .github/ # CI/CD workflows
|- Makefile # Build automation entry point (binaries land in build/)
`- README.md # This file
Contributions welcome! Please read the development guide and AGENTS.md first.
Use conventional commits for pull requests:
feat(docker): add container restart functionality
fix(auth): resolve session timeout issue
docs(readme): update installation instructionsThis project is licensed under the Apache License 2.0.
Third-party licenses and notices included in the filesystem indexer are
listed in docs/THIRD_PARTY_NOTICES.md and installed at
/usr/share/linuxio/doc/THIRD_PARTY_NOTICES.md.
- Cockpit - Primary product inspiration and unified Linux operations model
- Arcane - UI and interaction inspiration
- FileBrowser Quantum - File-management UX and visual inspiration, and the foundation for LinuxIO's filesystem indexer
- Beszel - Server monitoring inspiration
- Unraid - Product and homelab management inspiration
- Many other open source and self-hosted projects that shaped LinuxIO's direction