Clawbox UI

[yalexx]

Summary by CodeRabbit

Release Notes

• New Features

  • Full desktop environment with draggable app icons, window management, wallpaper customization, and system tray
  • VNC remote desktop support with enhanced keyboard and mouse input handling
  • System update workflow with version checking and branch selection
  • GitHub CLI and AI developer tools installation
  • Power management (reboot/shutdown) with recovery flow
  • Desktop auto-login and dark theme customization options
  • Telegram configuration during setup

• Improvements

  • Enhanced browser reliability with improved X11 display detection and process launch resilience
  • Gateway authentication now uses token-based system for improved security
  • Refined terminal server lifecycle management

• Configuration

  • Gateway network binding and hostname configuration updates

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (4)

• main
• master
• develop
• clawbox-*

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: e6bd477b-7453-4465-937d-42e5d6a322c3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR restructures the application's UI/UX architecture by moving the desktop interface from the setup page to the main page, adding desktop window management with persistent state, installing VNC remote access, GitHub CLI, and AI tools via the installer, reconfiguring gateway authentication to token-based mode, and refactoring terminal server lifecycle management.

Changes

Cohort / File(s)	Summary
Configuration & Gateway .coderabbit.yaml, config/clawbox-gateway.service, next.config.ts	Minor config updates: enabled auto-reviews for clawbox-* branches; changed gateway binding from loopback to LAN with token auth; updated allowed dev origin from IP to hostname.
Installer Steps install.sh	Added four new installation steps (desktop customization, VNC remote access, GitHub CLI, AI tools); updated OpenClaw config to use LAN binding; added cleanup of deprecated config keys; increased total step count from 19 to 22.
Gateway & Terminal Server scripts/gateway-pre-start.sh, scripts/terminal-server.ts, src/instrumentation.ts, src/instrumentation-node.ts, src/lib/gateway-proxy.ts	Refactored gateway pre-start config to use token-based auth; consolidated terminal server lifecycle into new instrumentation module; exported gateway token function and updated client-side script to persist connection settings to localStorage.
Setup Flow & Completion src/app/page.tsx, src/app/route.ts, src/app/setup/page.tsx, src/components/SetupWizard.tsx, src/components/DoneStep.tsx, src/components/ProgressBar.tsx	Moved desktop UI from setup page to main page with full window/app management; removed old gateway route; simplified setup page to only render wizard; extended setup steps to include credentials, AI models, and Telegram; removed system update UI from done step.
Browser & System Management src/app/setup-api/browser/manage/route.ts, src/app/setup-api/gateway/route.ts, src/components/BrowserApp.tsx, src/components/SystemTray.tsx, src/components/SettingsApp.tsx	Enhanced browser detection and launch with GPU/X11 flags and dynamic display selection; updated gateway route to inject token via localStorage; added reboot/shutdown flow with reconnection polling; integrated system update workflow into settings; added VNC preview button to browser app.
VNC & Component Enhancements src/components/VNCApp.tsx, src/components/ChromeShelf.tsx, src/components/UpdateStep.tsx, src/components/Window.tsx, src/lib/updater.ts	Enhanced VNC keyboard/focus handling for better interactivity; added power button to shelf; updated update step with loading state and up-to-date detection; added window data attributes; inserted vnc_install step into update pipeline.

Sequence Diagram

sequenceDiagram
    participant Client as Browser Client
    participant SetupAPI as Setup API
    participant MainPage as Main Page (Desktop)
    participant WindowMgr as Window Manager
    participant Installer as Installer Service

    Client->>SetupAPI: GET /setup-api/setup/status
    alt Setup Incomplete
        SetupAPI-->>Client: setup_complete: false
        Client->>SetupAPI: Redirect to /setup
    else Setup Complete
        SetupAPI-->>Client: setup_complete: true
        Client->>MainPage: Render Desktop
    end

    MainPage->>SetupAPI: GET /setup-api/preferences?all=1
    SetupAPI-->>MainPage: Return saved preferences (apps, wallpaper, windows, etc.)
    MainPage->>MainPage: Restore desktop state from localStorage

    Client->>WindowMgr: Launch app (click desktop icon)
    WindowMgr->>WindowMgr: Create window, manage z-index
    WindowMgr->>MainPage: Update window state
    MainPage->>SetupAPI: POST /setup-api/preferences (debounced save)
    SetupAPI-->>MainPage: Persisted

    Client->>MainPage: Drag icon / manage desktop
    MainPage->>MainPage: Update icon grid positions
    MainPage->>SetupAPI: POST /setup-api/preferences (sync)

    alt User accesses VNC
        Client->>WindowMgr: Click VNC app
        WindowMgr->>SetupAPI: VNC window opens
        SetupAPI-->>WindowMgr: X11 stream via noVNC
    end

    alt User triggers system update
        Client->>SetupAPI: POST /setup-api/update/run
        SetupAPI->>Installer: Run update steps (including vnc_install)
        Installer-->>SetupAPI: Poll /setup-api/update/status
        SetupAPI-->>Client: Update progress
        Client->>Client: Reload on completion
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~70 minutes

Possibly related PRs

• PR #5: Overlapping installer step additions and DISPATCH_STEPS/TOTAL_STEPS updates.
• PR #2: Shared gateway startup and token-based authentication configuration changes.
• PR #8: Related src/lib/updater.ts modifications for update step pipeline and version target logic.

Suggested labels

enhancement

Poem

🐰 A desktop blooms where setup once did play,
Windows dance, icons drag through the day,
VNC whispers from afar so grand,
Token gates guard with steady hand,
The clawbox leaps to life, wise and spry!

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 19.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title 'Clawbox UI' is vague and does not clearly describe the scope or main changes in this large, multi-faceted pull request.	Provide a more specific and descriptive title that captures the primary change, such as 'Restructure app layout with desktop UI at root and setup wizard in /setup' or 'Add desktop OS interface and reorganize routing structure'.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch clawbox-ui

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

✅ Test Report

• Result: passed

View run

[yalexx]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.