codespace-webtop
Native Selkies/XFCE webtop (browser desktop) via pixelflux-based selkies package — install, run, and autostart on any Ubuntu base system
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 2
- Forks
- 2
01 前言 Front Matter
- name
- codespace-webtop
- author
- Hermes Agent
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "selkies", "xfce", "webtop", "desktop", "codespaces", "vnc-alternative", "browser-desktop" ], "related_skills": [ "codespace-port-visibility", "github-codespace" ] } }
- platforms
- [ "linux" ]
- description
- Native Selkies/XFCE webtop (browser desktop) via pixelflux-based selkies package — install, run, and autostart on any Ubuntu base system
02 资源文件 8
- 参考文档references/architecture.md2.7 KB
- 参考文档references/disk-optimization.md2.3 KB
- 参考文档references/troubleshooting.md5.7 KB
- 参考文档references/web-client-no-sidebar.md3.1 KB
- 脚本scripts/.gitignore73 B
- 脚本scripts/prereqs.sh2.3 KB
- 脚本scripts/selkies-native.sh23.9 KB
- 其他templates/autostart.bashrc294 B
03 SKILL.md 正文
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:
# 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
# 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)
# 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)
-
Creates venv at
~/.selkies/venv(or$SELKIES_VENV_DIR) -
Installs pixelflux, pcmflux, and selkies from pinned git commits. Why git source? selkies
mainbranch requirespixelflux~=2.1.0andpcmflux~=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 fromgit ls-remoteand update the pins inselkies-native.sh:source ~/.selkies/venv/bin/activate pip install \ "git+https://github.com/selkies-project/pixelflux.git@<SHA>" \ "git+https://github.com/selkies-project/pcmflux.git@<SHA>" \ "git+https://github.com/selkies-project/selkies.git@<SHA>"(PyPI
selkies==1.6.1is the WRONG legacy GStreamer package.) -
Build the web client (
cmd_build_web): clone the full selkies repo (bothaddons/selkies-web-coreandaddons/selkies-dashboardmust be siblings),npm install+npm run buildselkies-web-core first (the dashboard's prebuild imports itsdist/selkies-core.js), then build selkies-dashboard, and copyaddons/selkies-dashboard/dist/→~/.selkies/web_root. The web client is NOT bundled in the wheel — serve the dashboard, NOT bare web-core (see Pitfalls: bare core = no sidebar).Vite build workaround: The Hermes terminal tool may detect
npx vite buildor./node_modules/.bin/viteas a long-lived server and refuse to run it. Usenode ./node_modules/vite/bin/vite.js buildinstead.Dashboard prebuild:
npm run buildin selkies-dashboard runsnode copy-core.jsas a prebuild hook. If using directnodeinvocation for vite, runnode copy-core.jsmanually before the vite build.
Note: The skill no longer ships vendored wheels in scripts/wheels/ (they're built at install time). A .gitignore in scripts/ keeps any local wheels out of git.
3. Start (start)
Order of operations:
- Xvfb :20 —
Xvfb :20 -screen 0 1920x1080x24 -nolisten tcp - XFCE session —
DISPLAY=:20 dbus-launch --exit-with-session xfce4-session- Auto-creates
~/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-session.xmlfrom system default if missing (prevents "unable to load failsafe session")
- Auto-creates
- selkies —
DISPLAY=:20 selkies --addr=0.0.0.0 --port=3000 --mode=websockets --web-root=~/.selkies/web_root --enable-basic-auth=false --framerate=30--web-rootMUST point at the built web client (~/.selkies/web_root, produced bycmd_build_webat install). Without it selkies returns 404 on/.
Each component tracked via PID file in /tmp/selkies-pids/.
4. Autostart (autostart enable)
Idempotent hook into shell rc file:
- Appends to
~/.bashrc(or~/.zshrc) a guarded block that runsselkies-native.sh start & - Disable removes the hook cleanly
Configuration
Environment variables (all optional, with defaults):
| Variable | Default | Description |
|---|---|---|
SELKIES_VENV_DIR |
~/.selkies/venv |
Python venv location |
SELKIES_PORT |
3000 |
Port for selkies |
SELKIES_ADDR |
0.0.0.0 |
Bind address |
XVFB_DISPLAY |
:20 |
Xvfb display number |
XVFB_SCREEN |
1920x1080x24 |
Screen resolution |
SELKIES_FRAMERATE |
30 |
Capture framerate |
SELKIES_WEB_ROOT |
~/.selkies/web_root |
Web client root dir |
SELKIES_WEB_COMMIT |
1d9b67be6f9c695f187a0509a3c1d3b3e204807b |
Pinned selkies web commit |
SELKIES_PIXELFLUX_COMMIT |
bf07c68 |
Pinned pixelflux commit |
SELKIES_PCMFLUX_COMMIT |
d2683ef |
Pinned pcmflux commit |
Pitfalls
- Wrong selkies package: PyPI
selkies==1.6.1is legacy GStreamer/WebRTC (selkies_gstreamer). Must use pixelflux-basedselkiesfrom GitHub Actionsselkies-wheelartifact (console script isselkies, has--mode=websockets, bundles React client inselkies_web/). - Missing libva: pixelflux needs
libva2 libva-drm2 libva-x11-2for H.264. Without them,import pixelfluxfails. - XFCE failsafe session popup: XFCE needs
~/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-session.xml. Auto-created from system default on first start. - DISPLAY not propagated:
dbus-launchlosesDISPLAYunless explicitly exported:env DISPLAY=:20 dbus-launch ... - WebSocket path: selkies serves WS at
/api/websockets(NOT/websockets/primarywhich 404s). - Port conflict: Default port 3000 must be free.
- CI lint gate (repo
skills/**): Before committing any change to this skill, runbash skills/ci-lint-check/scripts/ci_lint_check.sh. Markdown URLs MUST be wrapped in angle brackets<https://...>or they failMD034/no-bare-urls(this broke the initial PR #3 — two bare URLs in a References block). - selkies wheel acquisition is NOT plug-and-play: The GitHub Actions artifact (
selkies-wheel) requires auth (401 unauthenticated), thereleases/latest/download/selkies-wheel.zipURL returns 404, and the PyPI package (selkies==1.6.1) is the wrong legacy GStreamer package. The only reliable unattended path is installing all three from git (built intocmd_install). - Web client MUST be
selkies-dashboard, notselkies-web-core(this is the #1 failure mode). The selkies repo has TWO web addons:addons/selkies-web-core(the embeddable streaming Core only, README literally says "for an external dashboard to interact with the client") andaddons/selkies-dashboard(the standalone UI that embeds the Core). Ifinstallservesselkies-web-core, the webtop WILL launch and the desktop WILL render, but there is NO sidebar — the Core mounts with_isSidebarOpen = !1(closed) and only opens on atoggleDashboardwindow.postMessage. Symptom when this is wrong: video/audio/clipboard work fine, WS handshake returnsMODE websockets, HTTP 200 — but the Selkies sidebar chrome (settings/stats/clipboard/files/shortcuts) is absent. Fix: buildselkies-dashboard(itsprebuildcopies../selkies-web-core/dist/selkies-core.js, so both addons must be siblings under one cloned repo), then point--web-rootat the dashboard'sdist/. Verify by grepping the served bundle forsidebar/toggle(dashboard has ~90sidebar+ ~100toggle; bare core has almost none and starts closed). Seereferences/web-client-no-sidebar.mdfor the full diagnosis recipe. autostart enablemust keep{ ...; }with a trailing;: the appended rc line is[[ -x ... ]] && { "$SCRIPT_DIR/selkies-native.sh" start; } &>/dev/null &. A missing;before}(i.e.{ ... start }) makes bash throwsyntax error: unexpected end of filefor EVERY new login shell — it silently breaks.bashrcand anything that sources it. The template and script both use the;-terminated form; if you ever regenerate the hook by hand, keep it.npm cifails on a fresh shallow clone:git clone --depth 1may not ship apackage-lock.jsonthatnpm cirequires, sonpm cierrors and the build silently produces nothing (then the dashboard'sprebuildaborts with "missing selkies-core.js"). Always wrap asnpm ci ... || npm install ..., and buildselkies-web-coreBEFOREselkies-dashboard— dashboard'sprebuild(copy-core.js) exits 1 if../selkies-web-core/dist/selkies-core.jsis absent.- Interrupted apt install leaves dpkg broken: Installing XFCE4 (a large package set) frequently hits the terminal timeout. When
prereqs --fixfails mid-apt,dpkgis left in an unconfigured state and subsequent apt calls fail with "dpkg was interrupted". Fix:sudo DEBIAN_FRONTEND=noninteractive dpkg --configure -abefore retrying. TheDEBIAN_FRONTEND=noninteractiveis critical — without it,keyboard-configurationlaunches an interactive debconf dialog that hangs the terminal. - pcmflux~=2.1.0 is a hidden dependency: selkies requires
pcmflux~=2.1.0(audio capture), but like pixelflux, 2.1.0 is unreleased on PyPI (max: 2.0.0). The git-source install must build pixelflux and pcmflux before selkies — pip resolves all~=2.1.0constraints at once, but only if the packages are already installed in the venv.
Security
Authentication posture — intentional, not a bug. The webtop runs selkies with --enable-basic-auth=false. This is deliberate:
- In a GitHub Codespace the public port (3000) is only reachable through GitHub's authenticated port-forward — unauthenticated users cannot reach it. No additional app-level auth is needed for the normal Codespace flow.
- On a bare-metal/VM host (the skill's other supported target), a publicly routed port with auth off means anyone with the URL gets full XFCE control (input, clipboard, file transfer).
If you run this on a VM/bare-metal host:
- Keep the forwarded port private, or
- Put selkies behind an authenticating reverse proxy (e.g. Authelia, OAuth2 Proxy, Cloudflare Access), or
- Enable selkies basic-auth (note: a single shared credential — weak on its own; defense-in-depth only).
Greptile flagged this as P1 on PR #41. We keep auth off by design for the Codespace case (already gated) and document the exposure for the VM case rather than flipping the default, which would break the frictionless Codespace flow.
Verification
# Full health check
./scripts/prereqs.sh && \
./scripts/selkies-native.sh install && \
./scripts/selkies-native.sh start && \
sleep 3 && \
./scripts/selkies-native.sh status && \
curl -s http://127.0.0.1:3000/ | grep -q "selkies" && echo "HTTP OK" && \
python3 -c "
import asyncio, websockets
async def t():
async with websockets.connect('ws://127.0.0.1:3000/api/websockets') as ws:
await ws.send('ping')
r = await asyncio.wait_for(ws.recv(), timeout=3)
assert 'MODE websockets' in r
asyncio.run(t())
print('WS OK')
" && \
./scripts/selkies-native.sh stop
Expected: All components RUNNING, HTTP serves React client, WS handshake returns MODE websockets.
Files
codespace-webtop/
├── SKILL.md # This file (frontmatter + docs)
├── scripts/
│ ├── selkies-native.sh # Main control script (install/start/stop/restart/...)
│ └── prereqs.sh # Prerequisites checker + auto-fix
├── templates/
│ └── autostart.bashrc # Shell hook snippet
└── references/
├── architecture.md # Detailed architecture diagram
└── troubleshooting.md # Common issues + fixes
References
- Architecture details:
references/architecture.md - Troubleshooting:
references/troubleshooting.md - Disk optimization:
references/disk-optimization.md - PyPI selkies==1.6.1 is WRONG: https://pypi.org/project/selkies/ (legacy GStreamer package)
- Correct pixelflux-based selkies: https://github.com/selkies-project/selkies (install from git source)
04 同仓库更多 Skills
version-single-source
Use when adding a new component dependency or versioning a binary in install/boot scripts.
tdd
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
shell-path-login
Use when a binary or script works in one shell context but not another (interactive vs non-interactive login vs non-login shell).
self-update-fix
Fix a failing dependency update PR. Use when a self-update PR's CI fails, or when invoked by scripts/self-update-fix.sh.
pr-change-log
Use when a multi-commit PR needs its description written/updated, or when closing out a long branch with many fix commits.
persistent-knowledge
Persistent skills/knowledge in Codespace via symlinks.