title: Ubuntu Desktop
emoji: 🐧
colorFrom: indigo
colorTo: blue
sdk: docker
pinned: false
🐧 Ubuntu Desktop on Hugging Face Spaces
A browser-accessible Ubuntu 24.04 XFCE Desktop running on a free Hugging Face Docker Space — inspired by Android Termux + PRoot-Distro workflows, adapted for cloud deployment with zero manual setup.
✨ What You Get
| Feature | Detail |
|---|---|
| Desktop | Ubuntu 24.04 + XFCE4, accessible from any browser |
| VNC | TigerVNC (Xvnc) at 1280×720, 16-bit colour, 24 FPS |
| Browser Access | noVNC via WebSocket — no VNC client needed |
| Persistent Storage | All data stored in /data — survives Space restarts |
| Dashboard | Flask app with live CPU / RAM / disk stats + log viewer |
| Browser | Firefox ESR pre-installed |
| Free CPU Tier | Optimised for low RAM + CPU (≈ 400 MB idle) |
🚀 Deployment to Hugging Face Spaces
Prerequisites
- A Hugging Face account
- Git installed locally (or use the HF web UI)
Step 1 — Create a new Space
- Go to huggingface.co/new-space
- Choose Docker as the Space SDK
- Set hardware to CPU Basic (free tier)
- Enable Persistent Storage in the Space settings (required for
/data)
Step 2 — Upload the files
Either use the HF web editor to paste each file, or clone the Space repo and push:
git clone https://huggingface.co/spaces/<YOUR_USERNAME>/<YOUR_SPACE_NAME>
cd <YOUR_SPACE_NAME>
# Copy all project files here
cp -r /path/to/hf-ubuntu-space/* .
git add .
git commit -m "Initial Ubuntu Desktop Space"
git push
Step 3 — Wait for the build
The first build takes 5–8 minutes (downloading Ubuntu + XFCE packages). Watch the Build Logs tab in the Space UI.
Step 4 — Access your desktop
Once the Space shows Running, click the App tab, or open:
https://<username>-<spacename>.hf.space
Click 🖥 Launch Desktop to open the noVNC browser desktop.
🖥 Browser Desktop Access
| URL | Purpose |
|---|---|
https://…hf.space/ |
Launcher page (recommended) |
https://…hf.space/vnc/vnc.html |
noVNC direct (raw interface) |
https://…hf.space/dashboard |
System stats dashboard |
The launcher page auto-detects your Space's hostname and builds the correct WebSocket URL for noVNC — this is important because HF Spaces use Cloudflare proxying where the port is always 443 externally.
Mobile browsers
noVNC works on mobile. Use the scale/resize button (⤢) in the noVNC toolbar to fit the 1280×720 desktop to your screen.
💾 Persistent Storage
All state lives under /data (Hugging Face's persistent volume):
/data/
├── home/ ← ubuntu user home (~/.bashrc, Desktop, etc.)
├── workspace/ ← your project files (persists forever)
├── downloads/ ← browser and wget downloads
├── firefox/ ← Firefox profile (bookmarks, passwords, etc.)
├── xfce/ ← XFCE session config, wallpaper, themes
├── vnc/ ← VNC server state + xstartup
├── logs/ ← all service logs
└── cache/ ← app-level cache
Note: You must enable Persistent Storage in your Space settings. Without it
/datais ephemeral and resets on every restart.
⚙️ PRoot-Distro Similarities
This Space simulates the Termux + PRoot-Distro workflow:
| Termux / PRoot | This Space |
|---|---|
pkg install proot-distro |
Base Docker layer |
proot-distro install ubuntu |
FROM ubuntu:24.04 in Dockerfile |
proot-distro login ubuntu |
Container starts automatically |
~ (Termux home) |
/data/home (persisted) |
| Internal storage | /data/workspace |
The key difference is that this runs Docker natively (not PRoot), giving full kernel-level isolation without the overhead of a userspace chroot.
🔧 Configuration
Environment variables (set in Space settings)
| Variable | Default | Description |
|---|---|---|
VNC_PASSWORD |
(empty) | Set a VNC password (optional; localhost-only anyway) |
RESOLUTION |
1280x720 |
Desktop resolution |
COLOR_DEPTH |
16 |
VNC colour depth (16 or 24) |
Changing resolution
Edit supervisord.conf, update the Xvnc command:
command=Xvnc :1 -geometry 1920x1080 -depth 24 ...
🛠 Troubleshooting
Desktop doesn't load / black screen
- Open the Dashboard → check all services show Running
- Check Xvnc and XFCE4 logs for errors
- Try restarting XFCE4 from the dashboard restart button
"Failed to connect to server" in noVNC
- Make sure you're using the launcher page (
/) not a hard-coded URL - The WebSocket path must be
/websockify— check the URL bar in noVNC shows the correct host
Space keeps sleeping
HF free CPU Spaces sleep after ~15 min of no browser traffic. This is expected.
Wake it by opening the Space URL. Your /data files are always preserved.
High memory usage
XFCE4 uses ~300–400 MB at idle. With Firefox open, expect 800 MB+. The free CPU tier has 16 GB RAM, so this is fine. If you see OOM kills, close unused browser tabs in the desktop.
Logs
All logs are in /data/logs/ and viewable from the Dashboard log viewer:
/data/logs/supervisord.log
/data/logs/xvnc.log / xvnc_err.log
/data/logs/xfce4.log / xfce4_err.log
/data/logs/websockify.log
/data/logs/dashboard.log
/data/logs/nginx.log / nginx_error.log
🏗 Architecture
Browser (HTTPS :443)
│
▼
nginx :7860 (HF Spaces default port)
├─ / ──────────────────────── Launcher HTML (auto-builds WSS URL)
├─ /vnc/ ─────────────────── noVNC static assets
├─ /websockify ───────────── WebSocket proxy ──► websockify :6080
│ │
│ Xvnc :5901
│ XFCE4 session
├─ /dashboard ────────────── Flask app :5000
└─ /api/ ─────────────────── Flask REST API :5000
📄 Licence
MIT — use freely, no warranties.