---
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](https://huggingface.co) account
- Git installed locally (or use the HF web UI)

### Step 1 — Create a new Space

1. Go to **huggingface.co/new-space**
2. Choose **Docker** as the Space SDK
3. Set hardware to **CPU Basic** (free tier)
4. 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:

```bash
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 `/data` is 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:

```ini
command=Xvnc :1 -geometry 1920x1080 -depth 24 ...
```

---

## 🛠 Troubleshooting

### Desktop doesn't load / black screen

1. Open the **Dashboard** → check all services show **Running**
2. Check **Xvnc** and **XFCE4** logs for errors
3. 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.