7.2 KiB
7.2 KiB
XWorkspace Architecture
XWorkspace is an AI Workspace Shell built on top of standard Linux, systemd, Chrome / Chromium, and local runtime services.
The core idea is simple:
Do not expose a traditional Linux desktop to the user. Use Chrome / Chromium as the Desktop Shell, and use a local AI Workspace Portal as the main entry point.
XWorkspace is not trying to build a full operating system from scratch. It keeps the Linux base stable and standard, while replacing the user-facing desktop experience with an AI-native workspace.
⸻
1. Design Goals
XWorkspace is designed around the following principles:
1. Chrome / Chromium as Desktop Shell
The user enters the workspace through Chrome / Chromium instead of XFCE, GNOME, or a traditional desktop environment.
2. Portal-first user experience
The main workspace UI is a local web portal, usually exposed at: http://localhost:17000
- Minimal traditional desktop exposure XWorkspace avoids exposing panels, desktop icons, file manager desktops, or traditional application menus.
- Local-first runtime services Core services run locally through user-level systemd services.
- AI Agent oriented workflow The workspace is optimized for Agent, Terminal, Browser Use, Computer Use, Model Gateway, Vault, Workflow, Skill, and Plugin scenarios.
- Composable service architecture Each runtime capability is an independent service that can be started, stopped, upgraded, or replaced separately.
⸻
2. High-level Architecture
┌──────────────────────────────────────────────┐
│ Layer 1：Chrome / Chromium Desktop Shell │
│ │
│ - App mode / kiosk mode │
│ - Fullscreen workspace entry │
│ - Replaces traditional Linux desktop entry │
│ - Opens http://localhost:17000 │
└──────────────────────┬───────────────────────┘
↓
┌──────────────────────────────────────────────┐
│ Layer 2：AI Workspace Portal │
│ │
│ - Dashboard │
│ - App launcher │
│ - Runtime status │
│ - Agent sessions │
│ - Terminal / VSCode / Files │
│ - Model / Vault / Workflow entry │
└──────────────────────┬───────────────────────┘
↓
┌──────────────────────────────────────────────┐
│ Layer 3：Core Services │
│ │
│ - Bridge │
│ - Agent Runtime / Gateway │
│ - LiteLLM Proxy │
│ - Vault / Vault Proxy │
│ - ttyd │
│ - Status Generator │
│ - Local API / SSE / WebSocket │
└──────────────────────┬───────────────────────┘
↓
┌──────────────────────────────────────────────┐
│ Layer 4：App / Extra Services │
│ │
│ - Agent │
│ - Skill │
│ - Workflow │
│ - Plugin │
│ - Computer Use │
│ - Browser Use │
│ - Code Server │
│ - File Browser │
└──────────────────────────────────────────────┘
## 3. Runtime Flow
Linux boot
↓
User-level systemd session
↓
Core services start
↓
xworkspace-portal.service starts local portal
↓
xworkspace-shell.service starts Chrome / Chromium
↓
Chrome / Chromium opens http://localhost:17000
↓
User enters AI Workspace Portal
↓
Portal talks to Bridge, Agent, LiteLLM, Vault, ttyd, and extra services
## 4. Core Concept
Traditional Linux desktop:
Desktop Environment
├─ Panel
├─ File Manager
├─ Terminal
├─ Browser
├─ App Menu
└─ Settings
XWorkspace desktop
Chrome / Chromium Desktop Shell
└─ AI Workspace Portal
├─ Agent Console
├─ Terminal
├─ VSCode / Code Server
├─ Files
├─ Model Gateway
├─ Vault Secrets
├─ Runtime Status
├─ Workflow Runner
├─ Plugin Center
├─ Browser Use
└─ Computer Use
## 5. Display Stack Strategy
XWorkspace avoids supporting the traditional X11 desktop experience as a product surface.
However, Chrome / Chromium still needs a display stack.
Recommended evolution path:
Stage 1:
Use XFCE or a lightweight desktop session, but hide traditional desktop components and only expose Chrome / Chromium Shell.
Stage 2:
Replace XFCE with a minimal window manager. Only Chrome / Chromium is launched as the visible workspace shell.
Stage 3:
Move to Wayland / Weston / Cage mode. Chrome / Chromium becomes the only user-facing shell.
## Access & Exposure Strategy
XWorkspace follows a secure-by-default access strategy.
By default, XWorkspace does not expose the full AI Workspace Portal, WebRTC Desktop, ttyd, LiteLLM, Vault, or other internal services directly to the public Internet.
The default public entry should be limited to: https://xworkmate-bridge.example.com
This endpoint is protected by an access token in the early stage and should evolve to JWT-based authentication in future versions.
Default Access Model
Public Internet
↓
https://xworkmate-bridge.example.com
↓
Token / Future JWT Auth
↓
XWorkmate Bridge
↓
Local Core Services
The AI Workspace Portal remains local by default:
Chrome / Chromium Desktop Shell
↓
http://localhost:17000
↓
AI Workspace Portal
Not exposed by default:
- AI Workspace Portal
- WebRTC Desktop
- ttyd
- LiteLLM
- Vault
- OpenClaw Gateway
- Internal status endpoints
- Plugin / workflow services
Advanced User Mode
Advanced users may choose to expose additional services, but they should do so explicitly and with stronger access controls.
Recommended advanced exposure requirements:
- HTTPS
- MFA
- JWT authentication
- IP allowlist, optional
- Reverse proxy access policy
- Audit logs
- Rate limiting
- Separate subdomains for sensitive services