Lab is a modern, lightweight virtualization management platform designed for home servers. It provides a beautiful, responsive web interface to manage your virtual machines, containers, networks, and storage without the overhead of enterprise-grade hypervisors.
Built with performance and simplicity in mind, Lab leverages libvirt, QEMU/KVM, and LXC to give you full control over your hardware.
- Full VM Lifecycle: Create, start, stop, pause, and clone VMs with ease.
- Advanced Hardware: Support for TPM 2.0, Secure Boot, and PCI/GPU Passthrough.
- LXC & Docker: Native support for LXC containers and Docker Compose stacks.
- Resource Control: Dynamically adjust CPU, memory, and boot order.
- Real-time Metrics: Live charts for CPU, RAM, disk, and network I/O.
- Uptime Monitoring: Integrated health checks for your services with historical data.
- Task Tracking: Background job monitoring with real-time status updates.
- Centralized Logging: Persistent logs for all virtual machines and containers.
- Integrated Reverse Proxy: Domain-based routing with automatic SSL (ACME/Certbot support).
- Virtual Networks: Manage bridges, NAT networks, and firewall rules.
- Consoles: Built-in high-performance VNC and Serial consoles.
- Storage Pools: Manage directory, LVM, and ZFS pools.
- Snapshots & Backups: Point-in-time snapshots and scheduled backups with retention policies.
- Security First: JWT-based authentication with MFA support and role-based access control (RBAC).
- Alerting: Configurable alerts via Email (SMTP) or Webhooks.
| Component | Technology |
|---|---|
| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS, shadcn/ui |
| Backend | Go 1.25+, chi, ConnectRPC |
| API | Protobuf / gRPC / Connect |
| Database | SQLite (embedded with WAL mode) |
| Virtualization | libvirt, QEMU/KVM, LXC |
| DevOps | pnpm, Turbo, Playwright (E2E) |
Ubuntu/Debian users: See the complete Installation Guide for step-by-step instructions.
- OS: Linux (Ubuntu 22.04+, Debian 12+, Fedora 39+, Arch) or macOS (M1/M2/M3, Intel)
- Virtualization: Intel VT-x or AMD-V enabled in BIOS
- Software:
libvirt,qemu-system-x86,pnpm,go,node
See Development Guide for complete setup instructions.
Three ways to develop:
# 1. DIRECT (fastest, requires Go + libvirt on host)
make proto && cd apps/api && go vet ./...
# 2. DOCKER (consistent with CI, works on any platform)
make docker-vet
# 3. VAGRANT (full x86_64 VM, best for ARM Mac)
make vagrant-up && make vagrant-vet# Clone the repository
git clone https://github.com/doomedramen/lab.git
cd lab
# Install dependencies
pnpm install
# Start development servers (API & Web)
pnpm devOpen http://localhost:3000 to access the dashboard.
Since Lab relies on Linux-native features (KVM, LXC), we provide multiple options for testing and development on other platforms.
Option 1: Docker (any platform)
make docker-vet # Run go vet
make docker-test # Run tests
make docker-build # Build serverOption 2: Vagrant VM (ARM Mac recommended)
make vagrant-setup # Install Vagrant + QEMU
make vagrant-up # Start VM (first time: 5-10 min)
make vagrant-vet # Run go vet in VM
make vagrant-test # Run tests in VMSee Development Guide for detailed setup instructions.
Since Lab relies on Linux-native features (KVM, LXC), we provide multiple options for testing and development on other platforms.
Option 1: Docker (any platform)
make docker-vet # Run go vet
make docker-test # Run tests
make docker-build # Build serverOption 2: Vagrant VM (ARM Mac recommended)
make vagrant-setup # Install Vagrant + QEMU
make vagrant-up # Start VM (first time: 5-10 min)
make vagrant-vet # Run go vet in VM
make vagrant-test # Run tests in VMSee Vagrant Guide for Vagrant setup details.
# Build the static web UI
pnpm --filter web build
# Build the API server
cd apps/api
go build -o bin/lab-server ./cmd/serverFor detailed production setup, including systemd service configuration, see the Deployment Guide.
graph TD
User([Web Browser]) <-->|HTTPS/ConnectRPC| WebUI[Next.js Frontend]
WebUI <-->|ConnectRPC| API[Go API Server]
API <-->|SQLite| DB[(Local DB)]
API <-->|libvirt| LV[libvirt Daemon]
LV <-->|KVM| VMs[Virtual Machines]
LV <-->|LXC| CT[Containers]
API <-->|Reverse Proxy| Internet([Public Internet])
- Phase 1: Operational Foundation (Task tracking, VM updates, Clone, Disk management)
- Phase 2: Home Server Essentials (Alerting, Guest Agent, TPM 2.0, Secure Boot)
- Phase 5: Reverse Proxy & Uptime Monitoring (Core proxy, monitoring loop)
- Phase 2.4: PCI / GPU Passthrough (In progress)
- Phase 3: Management & Hardening (Host shell, Boot order, Session mgmt)
- Phase 4: RBAC & Security Polish (User groups, IP whitelisting, TLS)
- Phase 8: Infrastructure as Code (Pulumi integration)
See Project Plan for the full roadmap and implementation details.
For comprehensive documentation, see the Documentation Index.
Key Documents:
- AGENTS.md — Guide for AI agents (start here for AI assistance)
- Development Guide — Setup and workflows (Direct, Docker, Vagrant)
- Deployment Guide — Production deployment (systemd, Docker, manual)
- Architecture — System design and architecture
- Security Audit — Security posture and audit report
- Project Plan — Roadmap and feature status
- API Style Guide — Go API coding standards
We welcome contributions! Please follow these steps:
- Fork the repo.
- Create a feature branch (
git checkout -b feature/cool-new-thing). - Commit your changes (
git commit -m 'Add some cool thing'). - Push to the branch (
git push origin feature/cool-new-thing). - Open a Pull Request.
Please see CONTRIBUTING.md for more details.
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.
- libvirt for providing the industry-standard virtualization API.
- Proxmox VE for being a constant inspiration for home server management.
- shadcn/ui for the beautiful UI primitives.
- ConnectRPC for making type-safe APIs effortless.