codespace-webtop

Files (9)

• SKILL.md
• architecture.md · references/
• disk-optimization.md · references/
• troubleshooting.md · references/
• web-client-no-sidebar.md · references/
• .gitignore · scripts/
• prereqs.sh · scripts/
• selkies-native.sh · scripts/
• autostart.bashrc · templates/

SKILL.md (first lines)

# codespace-webtop

Run a **native Selkies/XFCE webtop (browser desktop)** on any Ubuntu-based system (Codespaces, VMs, bare metal) using the official pixelflux-based `selkies` Python package — not the legacy PyPI `selkies==1.6.1` (GStreamer/WebRTC).

Matches what `linuxserver/webtop:ubuntu-xfce` provides in Docker, but runs natively on the host.

## Architecture

```
Browser (port 3000) → selkies (0.0.0.0:3000, mode=websockets)
  selkies drives pixelflux capture on Xvfb :20 running XFCE
  pixelflux: Rust X11 capture → H.264/JPEG stripes → WebSocket
```

## When to Use

- User wants a remote desktop in browser (Codespaces, SSH, VPN)
- Need clipboard sync, file upload/download, keyboard input, auto-resize
- Pure WebSocket (no WebRTC/UDP) — works behind corporate firewalls
- Auto-start on boot/reboot via systemd or shell hook

## Prerequisites

### Runtime deps (needed by selkies at runtime)

| Component | Purpose | Check |
|-----------|---------|-------|
| `ubuntu` / `debian` base | apt package manager | `lsb_release -is` |
| `sudo` | install system deps | `sudo -n true` |
| `python3` + `pip3` | selkies venv | `python3 --version` |
| `Xvfb` | headless X11 server | `Xvfb -version` |
| `xfce4` + `xfce4-goodies` | desktop environment | `xfce4-session --version` |
| `dbus-x11` | session bus | `dbus-daemon --version` |
| `libva2 libva-drm2 libva-x11-2` | H.264 encoding (pixelflux) | `dpkg -l libva2` |

### Build deps (required to build pixelflux + pcmflux from git source)

The source install (the only reliable path) compiles Rust extensions (pixelflux, pcmflux) that link against system C libraries. **Why git source?** selkies `main` branch requires `pixelflux~=2.1.0` and `pcmflux~=2.1.0`, but these versions are unreleased — PyPI only has up to 2.0.0. The 2.1.0 versions exist in the selkies-project forks' git HEAD (their pyproject.toml says 2.1.0) but were never tagged or published. Building from git is the only way to satisfy these deps. These must be present **before** `pip install`:

| Component | Purpose | Install |
|-----------|---------|--------|
| `rustc` + `cargo` | Rust compiler for pixelflux/pcmflux | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh -s -- -y` |
| `nasm` | x264 SIMD assembly (pixelflux GPL encoder) | `sudo apt-get install -y nasm` |
| `cmake` | builds turbojpeg-sys, x264-sys from source | `sudo apt-get install -y cmake` |
| `pkg-config` | finds system .pc files during cargo build | `sudo apt-get install -y pkg-config` |
| `libudev-dev` | libudev-sys Rust crate build | `sudo apt-get install -y libudev-dev` |
| `libx264-dev` | x264-sys links against system libx264 | `sudo apt-get install -y libx264-dev` |
| `libturbojpeg0-dev` | turbojpeg-sys links against system libturbojpeg | `sudo apt-get install -y libturbojpeg0-dev` |
| `libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libavfilter-dev` | ffmpeg-sys-next links against system ffmpeg | `sudo apt-get install -y libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libavfilter-dev` |
| `libgbm-dev` | gbm-sys Rust crate build | `sudo apt-get install -y libgbm-dev` |
| `libinput-dev` | input-sys Rust crate build | `sudo apt-get install -y libinput-dev` |
| `libwayland-dev libxkbcommon-dev` | wayland crate builds | `sudo apt-get install -y libwayland-dev libxkbcommon-dev` |
| `libegl-dev libgles-dev` | EGL/GLES for smithay renderer | `sudo apt-get install -y libegl-dev libgles-dev` |
| `libclang-dev` | bindgen (Rust FFI generator) | `sudo apt-get install -y libclang-dev` |

**One-liner to install all build deps**:
```bash
# Rust toolchain
export RUSTUP_HOME=~/.rustup CARGO_HOME=~/.cargo
source ~/.cargo/env 2>/dev/null || curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && source ~/.cargo/env
# System build deps
sudo apt-get install -y nasm cmake pkg-config libudev-dev libx264-dev \
  libturbojpeg0-dev libavcodec-dev libavformat-dev libavutil-dev \
  libswscale-dev libavfilter-dev libgbm-dev libinput-dev \
  libwayland-dev libxkbcommon-dev libegl-dev libgles-dev libclang-dev
```

## Quick Start

```bash
# 1. Check prerequisites (auto-install with --fix)
./scripts/selkies-native.sh prereqs --fix

# 2. Install system deps + selkies
./scripts/selkies-native.sh install

# 3. Start desktop
./scripts/selkies-native.sh start
# Forward port 3000 → open in browser → Selkies sidebar visible

# 4. Enable autostart (idempotent)
./scripts/selkies-native.sh autostart enable
```

## Commands

| Command | Description |
|---------|-------------|
| `prereqs [--fix]` | Check (and optionally install) system dependencies |
| `install` | Create venv, install selkies+pixelflux+pcmflux from git, build web client |
| `start` | Xvfb → XFCE → selkies (all via PID tracking) |
| `stop` | Clean shutdown all components |
| `restart` | stop + start |
| `status` | Show PID/health of each component |
| `autostart enable\|disable\|status` | Wire/remove hook into `~/.bashrc` or systemd |
| `logs [component\|all]` | Tail logs (xvfb, xfce, selkies) |

## Procedure

### 1. Prerequisites Check (`prereqs`)

```bash
# Check only
./scripts/prereqs.sh

# Auto-install missing apt packages
./scripts/prereqs.sh --fix
```

Validates: OS, sudo, python3, pip3, and all apt packages listed above.

### 2. Install (`install`)

1. Creates venv at `~/.selkies/venv` (or `$SELKIES_VENV_DIR`)
2. Installs pixelflux, pcmflux, and selkies from pinned git commits. **Why git source?** selkies `main` branch requires `pixelflux~=2.1.0` and `pcmflux~=2.1.0`, which are unreleased — PyPI only has up to 2.0.0. The 2.1.0 versions exist only in git HEAD. Pins to specific commits for reproducibility. When updating, get the new HEAD SHAs from `git ls-remote` and update the pins in `selkies-native.sh`:
     ```bash
     source ~/.selkies/venv/bin/activate
     pip install \
       "git+https://github.com/selkies-project/pixelflux.git@<SHA>" \

From gitricko/.minions, MIT.

More from gitricko/.minions