Ephemeral desktop & browser containers for your home lab.
A self-hosted, Kasm-style VDI built on LinuxServer.io webtop images and streamed to the browser via Selkies — fronted by Traefik with per-workspace network isolation.
Cove lets you spin up full Linux desktops (XFCE, KDE, MATE, i3 on Ubuntu/Debian/Arch/Fedora/Alpine), security desktops (Kali), single applications (VSCodium, Blender, GIMP, Krita, and more), and single-app browsers (Chromium, Brave, Firefox) on demand — then open them in any browser tab, with no client to install. It's built for home labs: simple to run, low overhead, multi-user.
Quick start · Features · Documentation · Architecture deep-dive
- One-click launch — spin up a desktop or browser container and stream it straight to your browser.
- One launcher — a single flow asks what you want (desktop, browser or app), then shows only images of that kind. Browsers can boot straight at up to six URLs, kiosk-style for web-app delivery, with dark mode and full-screen variants offered only where that browser honours them.
- Seven browsers — Chromium, Brave, Firefox, Edge, Helium, Vivaldi and Opera.
- In-stream controls — fullscreen, a CRT toggle, HALT, and a quick-switch menu to jump between (or boot) other nodes without leaving the stream.
- One screen at a time — opening a workspace on another browser or a thin client moves the stream there, and the page that had it says where it went, with Take it back here.
- Live dashboard — workspaces split into Active/Offline, with per-container CPU & memory on running cards and the Tailscale IP shown (and copyable) for tailnet nodes.
- Screen previews — every running card shows a still of what's actually on that node's screen, captured from its own stream (X11 and Wayland alike). Doubles as the readiness check: a node isn't "running" until its stream renders a real frame. Previews are dropped the moment a workspace halts, and a workspace can't be connected to until its stream has rendered that first frame.
- Per-workspace apps — install distro packages (
universal-package-install), LinuxServer proot-apps, and AppImages (auto-extracted with a desktop launcher) at launch, then manage them from the UI: see what's installed, which proot-apps have a newer build, update/install/remove either kind, and watch it run in a background tasks menu. - Fresh containers — halting a workspace removes its container; bringing it back always pulls the latest image.
- Persistent storage — per-workspace home directories that survive restarts (or go fully ephemeral, wiped on halt).
- Thin clients — turn a spare mini PC into a kiosk that boots straight into Cove (Debian, sway and locked-down Chromium), set up with a one-liner or an install USB. Manage every screen from Admin → Thin clients: screen-off and on-hours, idle sign-out that ends only that screen's session, auto-open the running or a pinned workspace, rotation and brightness, screenshots, OS updates and reboots. Devices only dial out, so no port is opened, and their agent updates itself from Cove. See Thin clients.
- Home Assistant integration — Cove, its zones and its thin clients as Home Assistant devices: user and workspace counts, per-zone workspace CPU and memory, who is signed in on each screen and what it shows, plus switches for screen, mute and keep-awake, a volume slider, and identify, sign-out and reboot buttons. Scoped integration tokens from Admin → Integrations; Home Assistant polls over Cove's usual HTTPS address. See Home Assistant.
- Browser extension — Open in Cove sends any link from your own Chrome-based browser into a disposable Cove browser workspace. Served by your own server from the user menu → Browser extension, no store or internet needed.
- Per-user Tailscale routing — opt a workspace into a per-workspace Tailscale sidecar using your own preauth key, with exit-node selection, accept-routes/DNS, and a custom control server.
- Per-user VPN via Gluetun — route a workspace's egress through a per-workspace Gluetun sidecar. Keep several VPN profiles, each from an uploaded OpenVPN/WireGuard config or one of Gluetun's built-in providers (credentials stored encrypted), and pick one per workspace; each profile is connected to one workspace at a time.
- Custom DNS — point a (non-VPN) workspace at public resolvers (e.g.
1.1.1.1,9.9.9.9) instead of local DNS. - Egress policy — workspaces are WAN-only by default. Docker-internal and cloud-metadata ranges are always blocked (so workspaces can never reach the Cove backend, the socket proxy, or each other); admins can allow specific LAN subnets that a workspace opts into per launch. Tailscale workspaces keep tailnet/subnet/exit-node access while raw-bridge egress stays firewalled.
- Optional subdomain isolation — set
COVE_WORKSPACE_DOMAINto stream each workspace from its own origin ({id}.domain) so it can't reach the SPA's token; unset falls back to subpath routing.
- Authentication — local accounts (bcrypt) and OIDC/SSO against any standards-compliant provider (Kanidm, Authentik, Keycloak, Entra ID, Okta, Google), with an optional OIDC-only mode that disables local login. Password management is hidden for SSO accounts.
- Defense in depth — ForwardAuth-gated streams, per-workspace isolated Docker networks, split read-only/write Docker socket proxies, verified OIDC tokens, dropped capabilities, short-lived JWTs with refresh, real-client-IP rate limiting, audit logging, and optional at-rest DB encryption.
- Auto-populated catalog — images are pulled from the LinuxServer.io API on first run and via one-click admin sync; logos auto-fetched.
- Manual image pulls — pull/re-pull catalog images from the admin UI with live download status; delete the local image only, or the catalog entry too.
- Resource limits — admin-set default CPU (cores) and memory (MB) caps applied to workspace containers (0 = unlimited).
- Admin settings — pin/override the Tailscale and Gluetun sidecar images, toggle LAN access, force-disable sudo, set max runtime and CPU/memory limits, plus a read-only summary of env-configured settings.
- Admin UI — manage users, images, live sessions, and the audit log.
- Per-user zone limits — keep a zone (say, a LAN box) for some accounts: a limited account sees, launches on and stores files to only the zones you tick.
- File browser — browse, upload, download, and delete files in your workspace storage areas.
- User preferences — a self-service page to change your password and manage Tailscale settings.
- Installable PWA — add Cove to your home screen / desktop; offline-aware app shell (the live stream and API are never cached).
- Cyberpunk UI — neon theme with an optional CRT toggle on the stream.
git clone <your-fork-url> cove && cd cove
cp .env.example .env
docker compose up --build -dOpen http://localhost, complete first-run admin setup, and launch a workspace. Full instructions — including HTTPS, OIDC, DNS-01, and storage — are in SETUP.md.
┌────────────────────────────────────────┐
browser ──HTTP/S──▶ Traefik ──▶ cove (FastAPI + Vue SPA) │
│ └─ForwardAuth─▶ /api/auth/forward │
│ │
├──▶ workspace container (webtop/browser) │ each on its own
│ isolated network, port 3000 │ cove-ws-net-<id>
│ │
cove ──┐ └──▶ docker-socket-proxy ──▶ /var/run/docker.sock (filtered)
└─ manages containers via the proxy (DOCKER_HOST)
- Backend — Python 3.14, FastAPI, SQLAlchemy (SQLite/WAL), Docker SDK.
- Frontend — Vue 3 + TypeScript + Vite + Pinia.
- Proxy — Traefik v3 (label-based, auto-routes each workspace; TLS via Let's Encrypt, TLS-ALPN or DNS-01).
- Workspaces —
lscr.io/linuxserver/*images (port 3000,/config).
A full breakdown — runtime topology, auth/stream flows, the workspace lifecycle, and the data model — is in ARCH.md.
# Backend (from backend/, in a venv): ruff + pytest
ruff check server && pytest -q
# Frontend (from frontend/): typecheck + Vitest
npx vue-tsc --noEmit && npm testCI runs lint, both test suites, a frontend build, and a Docker image build (see .gitlab-ci.yml).
Cove is glue around excellent open-source projects — all credit to their authors and maintainers:
- LinuxServer.io (images) — the webtop/desktop & browser container images, the
universal-package-installDocker mod, and proot-apps. Workspaces stream via Selkies (the LinuxServer images Cove ships are all Selkies-based; KasmVNC images also work). - Tailscale (tailscale/tailscale) — the per-workspace tailnet routing sidecar.
- Gluetun by Quentin McGaw (@qdm12) — the per-workspace VPN (OpenVPN/WireGuard) sidecar.
- Traefik (Traefik Labs) — reverse proxy, ForwardAuth, and ACME/Let's Encrypt TLS.
- tecnativa/docker-socket-proxy — the filtered Docker API proxy.
- netshoot by Nicola Kabar — the short-lived helper used to apply per-workspace egress firewall rules.
- WireGuard is a registered trademark of Jason A. Donenfeld.
- Built with FastAPI, SQLAlchemy, Vue, Vite, Pinia, and lucide icons.
These projects are independent of Cove and are not affiliated with it; trademarks belong to their respective owners.
Cove was built with substantial help from AI coding tools (Claude). AI was used for writing, refactoring, and reviewing code throughout the project. Every change is human-reviewed before it lands, but you should evaluate the code on its own merits — read it, test it, and decide whether it fits your needs before relying on it. Contributions are welcome regardless of how they're authored.
Cove is licensed under the GNU General Public License v3.0 — see LICENSE. This follows the licensing of the upstream LinuxServer.io images Cove builds on. LinuxServer.io is not affiliated with this project.