Distribox is a self-hosted platform for creating, managing, and sharing virtual machines through a simple web interface.
Create virtual machines with custom specs: CPU cores, RAM, disk size, and operating system. Control VMs with start, stop, restart, duplicate, rename, and delete. Connect to any VM directly from your browser.
Distribox uses Apache Guacamole to stream VM desktops over WebSocket. The browser connects to the backend, which proxies the Guacamole protocol to guacd, which in turn connects to the VM's VNC server. No client-side software required.
VM streaming is secured through authenticated WebSocket tunnels. Access requires either a JWT token with the appropriate policy, or a credential-based token generated per VM. All traffic between the browser and the VM is mediated by the backend.
Distribox uses a policy-based permission system similar to RBAC. Each user is assigned one or more policies that grant access to specific actions (creating VMs, managing users, connecting to VMs, viewing metrics, etc.). If a user lacks a policy, the corresponding feature is hidden and access is denied. Admins have full access by default.
Supported out of the box:
- Ubuntu 22.04
- Debian 12
- Fedora 43
- CentOS 10
- AlmaLinux 9
- Alpine Linux 3.21
- Arch Linux (rolling)
OS images are hosted in a remote S3-based registry. When a VM is created, the backend downloads the corresponding image on demand and caches it locally. This keeps the installation lightweight -- no need to bundle large disk images. Image metadata includes revision tracking so updates are fetched automatically.
Distribox supports a distributed setup where additional machines act as slave nodes. The master coordinates VM placement and proxies operations to slaves. Slaves report resource availability via periodic heartbeats, and the master routes new VMs to the node with the most available memory. The frontend includes a guided tutorial for registering slave nodes.
Once connected, each slave node reports its status and resource usage in realtime.
Monitor CPU, memory, and disk usage for the master node, individual slave nodes, or the entire cluster from the dashboard. When provisioning a VM, you can choose which node to deploy on and see its available resources.
The monitor view displays periodical screenshots of all virtual machines on the instance. Running VMs show a live preview, and you can click on any of them to connect directly.
Events let you distribute a fixed number of VMs with a predefined spec to participants for a set duration. Create an event by choosing an OS, resource allocation, participant limit, and deadline. A shareable link is generated that participants can use to claim their VM.
Each event page shows its details, the provisioned VMs with live previews, and the list of participants.
The share link can be previewed and copied directly from the dashboard.
When an event reaches its deadline, the share link stops working, all VM credentials are revoked, and every virtual machine linked to the event is stopped automatically.
bash setup.sh
docker compose --profile master up -d --buildThe application will be available at localhost:3000.
For development with hot-reloading:
docker compose --profile dev up --buildTo run a slave node on another machine:
bash setup.sh
docker compose --profile slave up -d --buildCopy .env.example to .env and adjust as needed. Key variables:
| Variable | Default | Description |
|---|---|---|
DISTRIBOX_MODE |
master |
master or slave |
MASTER_URL |
- | URL of the master (slave mode only) |
SLAVE_API_KEY |
- | API key for slave authentication |
ADMIN_USERNAME |
admin |
Default admin username |
ADMIN_PASSWORD |
admin |
Default admin password |
DISTRIBOX_SECRET |
secret |
Encryption key for sensitive data |
BACKEND_PORT |
8080 |
Backend API port |
VITE_PORT |
3000 |
Frontend port |
- Backend: FastAPI, SQLModel, PostgreSQL, libvirt, KVM/QEMU
- Frontend: React Router v7, TypeScript, TailwindCSS v4, shadcn/ui
- Streaming: Apache Guacamole (guacd) over WebSocket
- Containerization: Docker Compose
Check out the contributing guide.
If you're interested in how the project is organized at a higher level, contact the current project manager.
- Backend -- environment setup and standalone backend configuration
- Frontend -- environment setup and standalone frontend configuration
- Images -- guide for building and customizing OS images
- Atlas -- syncing tool to upload images to the Distribox registry
Developers
 Loan Riyanto |
|---|
 Laurent Gonzalez |
|---|
🚀 Don't hesitate to follow us on our different networks, and put a star 🌟 on
PoC'srepositories
Made with ❤️ by PoC