xworkspace-console/docs/en/designs/2026-06-07-ai-workspace-desktop-design.md

🇺🇸 English | 🇨🇳 中文

AI Workspace Desktop Design

Date: 2026-06-07 Project: xworkspace-console Status: Draft for implementation alignment

1. Overview

This document defines the target design for the AI Workspace desktop environment built on top of XFCE, with xworkspace-console as the merged implementation repository.

The goal is not to build a new desktop environment. The goal is to assemble a minimal, reliable AI workspace shell by combining:

• XFCE as the desktop base layer
• XFCE panel and GTK/XDG-compatible configuration for desktop chrome
• Plank as the preferred auto-hide dock
• systemd --user for per-user service orchestration
• Go for the local status collection API
• React + Vite + TypeScript for the dashboard UI
• ttyd for the embedded terminal surface
• Chrome or Chromium app mode for the primary operator entrypoint

The intended visual direction is a low-distraction workspace that feels closer to NomadBSD, ChromeOS, and a simplified macOS Dock setup than to a traditional Linux desktop.

2. Product Goals

The desktop should boot into a focused AI operations environment where the browser-based control plane is the primary user experience.

Primary outcomes:

• A user signs into XFCE and lands in a minimal workspace, not a classic Linux desktop
• The top status bar surfaces only essential runtime state
• The bottom dock provides fast access to a fixed set of operator tools
• The browser opens directly into the XWorkspace control plane
• OpenClaw, Bridge, LiteLLM, Vault, and console services are managed and inspectable through systemd
• The control plane can show local service health, basic host metrics, and terminal access

3. Non-Goals

The first phase explicitly avoids these directions:

• No custom window manager
• No custom desktop shell framework
• No full desktop theming engine
• No KDE or GNOME dependencies
• No traditional application launcher menu as a primary interaction model
• No desktop widgets or icon clutter
• No attempt to replace XFCE internals with a new compositor or shell

4. User Experience

4.1 Desktop Experience

The default desktop session should feel intentional and appliance-like:

• Top panel height between 28px and 32px
• Left side of top panel shows XWorkspace
• Right side shows compact indicators for CPU, memory, network, agent readiness, vault status, and time
• No desktop icons
• No visible applications menu
• Bottom dock is hidden by default and revealed on pointer-to-screen-edge
• Dock entries are fixed and role-based, not open-ended

4.2 Dock Entries

The preferred first set of dock actions is:

• Browser
• Terminal
• Files
• VS Code
• XWorkmate
• OpenClaw

These launchers should point to stable system binaries or app-mode URLs, not ephemeral user shell aliases.

4.3 Browser Entry

The primary operator shell is Chrome or Chromium app mode:

• Preferred default URL: http://127.0.0.1:17000
• Alternate deployment URL: https://workspace.local

The app-mode launch path should be encapsulated in a script rather than duplicated across autostart and service files.

5. Architecture

The design is split into five layers:

1. Desktop shell layer
2. Service orchestration layer
3. Local status API layer
4. Dashboard UI layer
5. Deployment/configuration layer

5.1 Desktop Shell Layer

This layer is composed of:

• XFCE session
• XFCE top panel
• GTK/XDG configuration files
• Plank dock
• XDG autostart entries

Responsibilities:

• enforce minimal desktop layout
• disable desktop icons and traditional menu clutter
• expose a stable operator shell
• preserve compatibility with standard Linux tooling

5.2 Service Orchestration Layer

This layer uses systemd --user.

Managed services:

• xworkspace-console.service
• xworkspace-openclaw.service
• xworkspace-bridge.service
• xworkspace-litellm.service
• xworkspace-vault.service

Responsibilities:

• service startup order
• restart policy
• operator-facing unit naming
• local introspection via systemctl --user

5.3 Local Status API Layer

This layer is written in Go.

Responsibilities:

• expose health endpoints for the dashboard
• normalize service state from systemd
• collect simple machine metrics
• answer lightweight polling traffic from the local dashboard

Endpoints:

• /health
• /services
• /metrics/simple

The API should stay intentionally small and local-first.

5.4 Dashboard UI Layer

This layer is written in React + Vite + TypeScript.

Responsibilities:

• render service cards
• render task and agent placeholders in MVP
• surface artifacts and settings sections
• embed or link terminal access through ttyd
• act as the default browser control plane

The visual language should be dark, precise, and operational rather than decorative.

5.5 Deployment and Configuration Layer

This layer uses:

• shell scripts
• YAML configuration
• XFCE XML templates
• systemd service files

The repo should maintain a single human-editable YAML config file for desktop-level defaults such as ports, browser preference, and service naming. Generated or copied runtime files can still be XML or .desktop files where required by XFCE and XDG.

6. Canonical Repository Structure

The merged repository should keep this shape:

xworkspace-console/
├─ api/
├─ assets/
│  ├─ icons/
│  ├─ themes/
│  └─ wallpaper/
├─ config/
│  ├─ autostart/
│  ├─ systemd/
│  │  └─ user/
│  ├─ xfce4/
│  └─ xworkspace-desktop.yaml
├─ dashboard/
│  ├─ src/
│  ├─ package.json
│  ├─ tsconfig.json
│  └─ vite.config.ts
├─ docs/
│  └─ designs/
├─ scripts/
│  ├─ reset-xfce-profile.sh
│  ├─ setup-xworkspace-desktop.sh
│  └─ start-chromium-console.sh
└─ README.md

Removed from scope:

• Flutter
• Dart
• static web shell duplication

7. Naming Model

The repository standardizes on xworkspace-console as the primary control-plane name.

Naming decision:

• Keep: xworkspace-console
• Keep: xworkspace-openclaw
• Keep: xworkspace-bridge
• Keep: xworkspace-litellm
• Keep: xworkspace-vault
• Treat as historical/overlapping labels only: xworkspace-dashboard, xworkspace-portal

Reasoning:

• console is broad enough to cover desktop shell plus browser control plane
• dashboard is too narrow once service orchestration and desktop concerns are merged
• portal overlaps with one specific web surface and causes naming duplication

8. Online Environment Alignment

The live reference host is:

• SSH entry: ubuntu@xworkmate-bridge.svc.plus
• effective host: jp-xhttp-contabo.svc.plus

Reference online service behavior already observed:

8.1 Bridge

Live unit:

• xworkmate-bridge.service

Observed shape:

• WorkingDirectory=/opt/cloud-neutral/xworkmate-bridge
• ExecStart=/home/ubuntu/.local/bin/xworkmate-go-core serve --listen 127.0.0.1:8787

8.2 OpenClaw

Live unit:

• openclaw-gateway.service

Observed shape:

• WorkingDirectory=/home/ubuntu
• ExecStart=/home/ubuntu/.local/bin/openclaw gateway run --port 18789 --force

8.3 Implication

The local repo should preserve these real startup patterns in the service templates, even if repo-level names are normalized to:

• xworkspace-bridge.service
• xworkspace-openclaw.service

This prevents the desktop repo from drifting away from the live environment.

9. Systemd Design

9.1 Units

Required user units:

• xworkspace-console.service
• xworkspace-openclaw.service
• xworkspace-bridge.service
• xworkspace-litellm.service
• xworkspace-vault.service

Recommended optional units later:

• xworkspace-status-api.service
• xworkspace-ttyd.service

9.2 Service Rules

Each service should define:

• a clear Description
• After=network-online.target when it depends on network readiness
• Restart=always
• explicit WorkingDirectory when runtime behavior depends on cwd
• explicit Environment= entries when tool paths or configs matter

9.3 Console Service

xworkspace-console.service should run the React dashboard dev server in MVP, but the intended evolution is:

• dev mode during early iteration
• built static assets served by a lightweight local web server later

That future transition should not change the service name.

10. YAML Configuration Model

Primary config file:

• config/xworkspace-desktop.yaml

Responsibilities:

• browser binary selection
• dashboard URL and ports
• service naming defaults
• shell-level UI defaults such as dock strategy and panel height

The setup scripts should read this YAML and use it to patch or generate deployment-facing files when reasonable.

11. XFCE and Theme Configuration

11.1 XFCE

Config templates should remain in config/xfce4/.

Key responsibilities:

• panel placement
• panel size
• shortcut defaults
• session behavior
• window focus defaults

11.2 GTK / XDG

Theme customization should be kept lightweight:

• GTK theme selection
• icon theme selection
• XDG autostart entries
• desktop icon suppression

No large theming subsystem is needed in MVP.

12. Dashboard MVP

12.1 Sections

The dashboard should expose these sections:

• Services
• Tasks
• Agents
• Artifacts
• Terminal
• Settings

12.2 Terminal

Terminal behavior should be one of:

• embedded ttyd frame
• local link-out to ttyd

MVP can begin with an embedded panel or status-linked shell area.

12.3 Visual Direction

The interface should follow:

• dark background
• blue/white operational accents
• low visual noise
• strong spacing and readable density
• appliance-like focus rather than marketing aesthetics

13. Go API MVP

13.1 Endpoints

• /health
  • status, arch, OS, CPU count, service snapshot
• /services
  • normalized systemd service states
• /metrics/simple
  • machine-readable metrics line output

13.2 Data Sources

MVP may use:

• systemctl --user is-active
• standard library HTTP only
• simple host runtime introspection

Later versions may add:

• CPU percentage
• memory usage
• disk usage
• network availability
• agent readiness probes

14. Setup and Reset Flows

14.1 Setup

scripts/setup-xworkspace-desktop.sh should:

• install required packages
• create target config directories
• copy XFCE and systemd templates
• copy XDG autostart entry
• enable relevant user services

14.2 Reset

scripts/reset-xfce-profile.sh should:

• remove copied XFCE panel/session config
• remove XWorkspace autostart entry
• remove XWorkspace user service files and symlinks

The reset path must avoid damaging unrelated shell configuration.

15. Risks and Constraints

15.1 Browser Binary Variants

Different Debian/Ubuntu variants may provide:

• google-chrome
• chromium-browser
• chromium

The launcher must support at least a preferred binary plus fallback.

15.2 XFCE Plugin Availability

Dock strategy may vary by distro packaging:

• prefer Plank
• use xfce4-docklike-plugin as fallback when needed

15.3 Dev Server vs Static Build

Running Vite in dev mode is acceptable in MVP, but long-term desktop reliability improves if the dashboard is built and served as static files.

15.4 Online Drift

The desktop repo must periodically re-validate service templates against the live host to avoid stale assumptions, especially for:

• OpenClaw startup flags
• bridge binary path
• auth-related environment variables

16. Implementation Roadmap

Phase 1

• remove Flutter/Dart leftovers
• keep YAML + Go + React + XFCE/systemd only
• align openclaw and bridge service templates with live host
• keep dashboard as local Vite MVP

Phase 2

• add real host metrics to the Go API
• add ttyd integration to dashboard
• add generated dock/panel setup behavior from YAML config
• improve Plank auto-hide setup and launcher provisioning

Phase 3

• package as Debian artifact
• prepare ISO/bootstrap path
• switch dashboard serving from dev mode to production static assets

17. Acceptance Criteria

The desktop environment is considered acceptable for MVP when:

1. A fresh Ubuntu or Debian VM can run the setup script successfully
2. XFCE loads into a minimal workspace shell
3. Desktop icons are hidden
4. Traditional application menu is not central to the workflow
5. Browser app mode opens the XWorkspace console automatically
6. Dashboard can read local service health
7. Reset script can roll back XWorkspace-specific desktop changes
8. Standard terminal, browser, and file manager behavior remains intact

18. Current Repository Direction

As of this design draft, xworkspace-console should be treated as:

• the canonical merged repo
• the source of desktop shell templates
• the source of systemd service templates
• the source of the Go local API
• the source of the React dashboard

This design supersedes the earlier split between a Flutter console repo, a static portal concept, and a separate desktop skeleton.