A cloud desktop environment powered by Vercel and Vercel Sandbox. Each user gets isolated Linux workspaces accessible from any browser, with a window manager, terminal, file browser, code editor, and X11 app streaming.

This was an AI engineered/vibecoded repository and is not meant for production. It is a proof-of-concept and demo.

Browser (React)                    Vercel (Next.js)                 Vercel Sandbox (microVM)
┌──────────────────┐              ┌──────────────────┐             ┌──────────────────────┐
│ Desktop UI       │◄────────────►│ API Routes       │◄───────────►│ :14081 Services API  │
│ Window Manager   │              │ /api/sandbox/*   │             │   - file CRUD        │
│ Taskbar          │              │ /api/auth/*      │             │   - .desktop scanner │
│ App Launcher     │              │ /api/files/*     │             │   - process launcher │
│ (Cmd+K)          │              │ /api/apps/*      │             │                      │
│                  │              │                  │             │                      │
│ Terminal ────────┼──── WSS ─────┼──────────────────┼────────────►│ :14081 PTY Relay     │
│ (ghostty-web)    │              │                  │             │   - bash over WS     │
│                  │              │ Sandbox SDK      │             │                      │
│ Code Server ─────┼── iframe ───┼──────────────────┼────────────►│ :14082 code-server   │
│                  │              │ (@vercel/sandbox)│             │   - VS Code in browser│
│                  │              │                  │             │                      │
│ Xpra Canvas ─────┼── WSS ─────┼──────────────────┼────────────►│ :14080 Xpra Server   │
│ (X11 apps)       │              │                  │             │   - X11 app streaming│
│                  │              │                  │             │                      │
│ File Manager ────┼── fetch ────┼──► proxy ────────┼────────────►│ :14083 Reserved      │
└──────────────────┘              └────────┬─────────┘             └──────────────────────┘
                                           │
                                  ┌────────▼─────────┐
                                  │ Neon Postgres     │
                                  │ - users           │
                                  │ - workspaces      │
                                  │ - warm_pool       │
                                  │ - config          │
                                  └──────────────────┘

• Window Management -- drag, resize, snap-to-edge tiling, maximize, minimize, z-index focus tracking, debounced persistence
• Keyboard Shortcuts -- configurable KDE-style keybinds (Alt+Tab, Cmd+K launcher, Ctrl+Alt+T terminal, etc.)
• App Launcher (Cmd+K) -- fuzzy search command palette across all apps
• Built-in Apps -- Terminal (Ghostty), File Manager, Code Editor (VS Code), Settings, App Store (dnf package manager)
• X11 Apps -- Firefox, GIMP, Nautilus, GNOME Calculator, Text Editor, and more streamed via Xpra
• Multiple Workspaces -- each backed by its own sandbox VM with independent state
• Theme Sync -- browser light/dark theme synced to GTK settings inside the sandbox
• Desktop Notifications -- D-Bus bridge for notify-send and GLib/GTK notification support
• Mobile Support -- full-screen stacked card view, touch controls, iOS keyboard handling

• Node.js 22+
• pnpm 10+
• Bun (for running scripts)
• A Vercel account with Sandbox access
• A Postgres database (the demo uses Neon via Vercel Marketplace)

git clone <repo-url>
cd sandcastle
pnpm install

Copy the example env file and fill in your values:

cp .env.example .env.local

Then edit .env.local:

# Neon Postgres connection string
DATABASE_URL=postgresql://user:password@host/database?sslmode=require

# Session signing secret (min 32 characters)
SESSION_SECRET=<run: openssl rand -base64 32>

# Secret for authenticating cron jobs (generate a random string)
CRON_SECRET=<run: openssl rand -base64 32>

Auth: In development (NODE_ENV=development), email/password auth is enabled -- no OAuth needed. The codebase includes a Vercel-specific OAuth integration under src/app/api/auth/vercel/ as a reference, but you'll need to swap it for your own OAuth provider (GitHub, Google, etc.) for production use.

If you have a Vercel project linked, you can pull DATABASE_URL and VERCEL_OIDC_TOKEN automatically:

vercel link
vercel env pull

Push the schema to your Neon database:

pnpm db:push

The golden snapshot is a pre-configured VM image with all system packages, desktop apps, and dev tools pre-installed. New workspaces clone from it for fast startup (~5s vs ~2min from scratch).

pnpm snapshot

This takes 2-4 minutes.

pnpm dev

Open http://localhost:3000. In development mode, password-based auth is available in addition to Vercel OAuth.

pnpm test:sandbox

This spawns a sandbox from the golden snapshot and verifies all services (PTY, Xpra, code-server, file API) are working.

1. Push to a git repository connected to Vercel
2. Set all required environment variables in your Vercel project settings
3. VERCEL_OIDC_TOKEN is set automatically -- no action needed
4. Cron jobs are configured in vercel.json and will run automatically:
   • Golden snapshot rebuild -- daily at midnight
   • Sandbox lifecycle -- every 30 minutes (snapshots/stops idle sandboxes)
   • Warm pool maintenance -- every 10 minutes (keeps 3 pre-warmed VMs ready)

The golden snapshot includes:

• System tools: vim, htop, wget, jq, tree, tmux, ripgrep
• X11/GTK4 stack: Xvfb, Xpra, mesa, dbus, GStreamer, Adwaita icons
• Desktop apps: Firefox, GIMP, Nautilus, GNOME Calculator, Text Editor, Loupe, Papers, System Monitor, Ptyxis, Seahorse
• Fonts: Noto Sans, Noto Emoji, DejaVu
• Dev tools: code-server (VS Code + extensions), Claude Code, OpenCode, Bun, pm2
• Config: GTK dark theme, Xpra CSP headers, XDG directories, desktop shortcuts, Firefox profile, shell aliases

Snapshots expire after 7 days and are rebuilt automatically by the daily cron job.

To test a specific snapshot:

pnpm test:sandbox -- --snapshot snap_abc123

• Dusk by Paco Coursey for the app icons
• Xpra for the X11 streaming technology
• code-server for the in-browser VS Code experience
• Ghostty and ghostty-web for the WASM terminal

MIT