vnc sidecar: per-user desktop sessions via sidecar architecture

replaces the single hardcoded systemd VNC service with a dynamic
sidecar that manages per-user VNC sessions on demand. any authenticated
user can now access their own desktop, not just Super Admin.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/servers/api/desktop/rest.ts

@@ -1,5 +1,6 @@
 import { createRouter } from '../../create-router';
 import { getVncPassword } from './vnc-config';
+import * as sidecar from '@@/sidecar-registry';
 
 export const desktopRouter = createRouter();
 
@@ -11,3 +12,12 @@ desktopRouter.get('/vnc-password', async (ctx) => {
   }
   return ctx.json({ password });
 });
+
+desktopRouter.get('/vnc-status', async (ctx) => {
+  const user = ctx.get('user');
+  if (!sidecar.isVncConnected()) {
+    return ctx.json({ connected: false, session: null });
+  }
+  const session = await sidecar.getVncStatus(user.email);
+  return ctx.json({ connected: true, session });
+});

src/servers/api/desktop/vnc-config.ts

@@ -1,11 +1,8 @@
 import { join } from 'node:path';
-import { getHomeDir } from '@@/data-path';
+import { getHomeDirForRole } from '@@/data-path';
 
 function getVncDir(email: string, role: string | null): string {
-  const home = role === 'Super Admin' && process.env.HOME_DIR
-    ? process.env.HOME_DIR
-    : getHomeDir(email);
-  return join(home, '.vnc');
+  return join(getHomeDirForRole(email, role), '.vnc');
 }
 
 export async function getVncPassword(email: string, role: string | null): Promise<string | null> {
@@ -13,10 +10,3 @@ export async function getVncPassword(email: string, role: string | null): Promis
   if (!(await file.exists())) return null;
   return (await file.text()).trim();
 }
-
-export async function getVncPort(email: string, role: string | null): Promise<number> {
-  const file = Bun.file(join(getVncDir(email, role), 'port'));
-  if (!(await file.exists())) return 5901;
-  const port = parseInt((await file.text()).trim(), 10);
-  return isNaN(port) ? 5901 : port;
-}

src/servers/api/desktop/websocket.ts

@@ -1,6 +1,6 @@
 import type { ServerWebSocket } from 'bun';
 import type { Socket } from 'bun';
-import { getVncPort } from './vnc-config';
+import * as sidecar from '@@/sidecar-registry';
 
 type WSData = { userId: number; email: string; username: string; role: string; sandboxed: boolean; sessionId?: string };
 
@@ -13,15 +13,25 @@ const sessions = new Map<ServerWebSocket<WSData>, VncSession>();
 
 export const desktopWebsocket = {
   async open(ws: ServerWebSocket<WSData>) {
-    if (ws.data.role !== 'Super Admin') {
-      ws.close(4003, 'Forbidden');
-      return;
-    }
-
-    const port = await getVncPort(ws.data.email, ws.data.role);
     const session: VncSession = { tcpSocket: null, pendingMessages: [] };
     sessions.set(ws, session);
 
+    let port: number;
+    try {
+      const result = await sidecar.startVnc({
+        email: ws.data.email,
+        username: ws.data.username,
+        role: ws.data.role,
+      });
+      port = result.port;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Failed to start VNC session';
+      console.error('[desktop] VNC start failed:', message);
+      sessions.delete(ws);
+      ws.close(4004, 'VNC server unavailable');
+      return;
+    }
+
     try {
       const tcpSocket = await Bun.connect({
         hostname: '127.0.0.1',
@@ -36,20 +46,31 @@ export const desktopWebsocket = {
           },
           close() {
             sessions.delete(ws);
-            try { ws.close(); } catch { /* ignore */ }
+            try {
+              ws.close();
+            } catch {
+              /* ignore */
+            }
           },
           error(_socket, err) {
             console.error('[desktop] TCP error:', err.message);
             sessions.delete(ws);
-            try { ws.close(); } catch { /* ignore */ }
+            try {
+              ws.close();
+            } catch {
+              /* ignore */
+            }
           },
           connectError(_socket, err) {
             console.error('[desktop] TCP connect error:', err.message);
             sessions.delete(ws);
-            try { ws.close(4004, 'VNC server unavailable'); } catch { /* ignore */ }
+            try {
+              ws.close(4004, 'VNC server unavailable');
+            } catch {
+              /* ignore */
+            }
           },
           open(socket) {
-            // Flush any pending messages
             for (const msg of session.pendingMessages) {
               socket.write(msg);
             }

src/servers/api/users/provision.ts

@@ -83,6 +83,9 @@ export async function provisionLinuxUser(email: string, username: string): Promi
   const settingsContent = await Bun.file(settingsFile).text();
   await Bun.write(join(claudeDir, 'settings.json'), settingsContent);
 
+  // Provision VNC environment
+  await provisionVncEnv(homeDir);
+
   // Service user (pastilhas) owns everything — server can always read/write.
   // User's personal group gives only that user terminal access. Others get nothing.
   const serviceUser = process.env.USER ?? 'pastilhas';
@@ -139,6 +142,50 @@ async function seedShellConfigs(homeDir: string): Promise<void> {
   mkdirSync(join(homeDir, '.pi', 'agent', 'sessions'), { recursive: true });
 }
 
+async function provisionVncEnv(homeDir: string): Promise<void> {
+  const vncDir = join(homeDir, '.vnc');
+  mkdirSync(vncDir, { recursive: true });
+
+  // Skip if already provisioned
+  if (existsSync(join(vncDir, 'passwd'))) return;
+
+  // Generate random 8-char password
+  const password = Array.from(crypto.getRandomValues(new Uint8Array(6)))
+    .map((b) => String.fromCharCode(33 + (b % 94)))
+    .join('');
+
+  // Write plaintext password (for API to read)
+  await Bun.write(join(vncDir, 'password'), password);
+
+  // Create encrypted passwd using vncpasswd -f
+  const proc = Bun.spawnSync({
+    cmd: ['bash', '-c', `echo '${password.replace(/'/g, "'\\''")}' | vncpasswd -f`],
+    stdout: 'pipe',
+    stderr: 'ignore',
+  });
+
+  if (proc.exitCode === 0 && proc.stdout.byteLength > 0) {
+    await Bun.write(join(vncDir, 'passwd'), proc.stdout);
+  }
+
+  // Write xstartup
+  const xstartup = `#!/bin/sh
+unset SESSION_MANAGER
+unset DBUS_SESSION_BUS_ADDRESS
+eval $(dbus-launch --sh-syntax)
+export DBUS_SESSION_BUS_ADDRESS
+exec startxfce4
+`;
+  await Bun.write(join(vncDir, 'xstartup'), xstartup);
+
+  // Set permissions
+  run(['chmod', '+x', join(vncDir, 'xstartup')]);
+  run(['chmod', '600', join(vncDir, 'passwd')]);
+  run(['chmod', '600', join(vncDir, 'password')]);
+
+  console.log(`[provision] VNC environment provisioned at ${vncDir}`);
+}
+
 export function deprovisionLinuxUser(email: string, username: string): boolean {
   const shellUsername = toShellUsername(username, email);
   console.log(`[provision] deprovisioning Linux user ${shellUsername}`);

src/servers/sidecar-registry.ts

@@ -2,17 +2,18 @@ import type { ServerWebSocket } from 'bun';
 import type {
   SidecarCommand,
   SidecarEvent,
-  SidecarState,
+  ClaudeState,
   ClaudeSpawnParams,
   ClaudeSpawnStreamingParams,
   ClaudeCodeResult,
   PiSpawnParams,
   PtyCommand,
   PtyEvent,
+  VncStartParams,
+  VncSessionInfo,
 } from './sidecar/protocol';
 import type { SidecarRegistration } from './sidecar/registration-protocol';
 import type { PiEvent } from './api/pi/types';
-import type { Job, EnqueueParams } from './queue/types';
 
 // ── Types ──
 
@@ -36,7 +37,7 @@ type EventHandler = (event: SidecarEvent | PtyEvent) => void;
 const sidecars = new Map<string, RegisteredSidecar>();
 const pending = new Map<string, PendingRequest>();
 const eventHandlers = new Map<string, Set<EventHandler>>();
-let cachedState: SidecarState | null = null;
+let cachedState: ClaudeState | null = null;
 let idCounter = 0;
 
 function nextId(): string {
@@ -81,7 +82,7 @@ export function unregisterSidecar(id: string): void {
     pending.delete(reqId);
   }
 
-  // Clear cached state if the process sidecar disconnects
+  // Clear cached state if the claude sidecar disconnects
   if (sc.capabilities.includes('proxy')) {
     cachedState = null;
   }
@@ -110,12 +111,6 @@ function findSidecarByCapability(cap: string): RegisteredSidecar | undefined {
   return undefined;
 }
 
-function requireSidecar(cap: string): RegisteredSidecar {
-  const sc = findSidecarByCapability(cap);
-  if (!sc) throw new Error(`No sidecar with capability "${cap}" is connected`);
-  return sc;
-}
-
 // ── Event dispatch ──
 
 function dispatchEvent(msg: SidecarEvent | PtyEvent) {
@@ -171,17 +166,17 @@ function sendFire(cap: string, cmd: SidecarCommand | PtyCommand): void {
   }
 }
 
-// ── Public API (same signatures as sidecar-client.ts) ──
+// ── Public API ──
 
 export function isConnected(): boolean {
   return findSidecarByCapability('proxy') !== undefined;
 }
 
-export function getCachedState(): SidecarState | null {
+export function getCachedState(): ClaudeState | null {
   return cachedState;
 }
 
-export async function syncState(): Promise<SidecarState> {
+export async function syncState(): Promise<ClaudeState> {
   const res = await sendCommand('proxy', { type: 'state:sync', id: nextId() });
   if (res.type === 'state:sync') {
     cachedState = res.state;
@@ -272,34 +267,6 @@ export function onPiEvent(handler: (sessionId: string, event: PiEvent) => void):
   });
 }
 
-// ── Queue ──
-
-export async function enqueueJob(params: EnqueueParams): Promise<Job> {
-  const res = await sendCommand('queue', { type: 'queue:enqueue', id: nextId(), params });
-  if (res.type === 'queue:enqueued') return res.job;
-  if (res.type === 'queue:error') throw new Error(res.error);
-  throw new Error('Unexpected response');
-}
-
-export async function cancelJob(jobId: string): Promise<Job | null> {
-  const res = await sendCommand('queue', { type: 'queue:cancel', id: nextId(), jobId });
-  if (res.type === 'queue:cancelled') return res.job;
-  if (res.type === 'queue:error') throw new Error(res.error);
-  throw new Error('Unexpected response');
-}
-
-export async function listJobs(): Promise<Job[]> {
-  const res = await sendCommand('queue', { type: 'queue:list', id: nextId() });
-  if (res.type === 'queue:list') return res.jobs;
-  throw new Error('Unexpected response');
-}
-
-export async function getJob(jobId: string): Promise<Job | null> {
-  const res = await sendCommand('queue', { type: 'queue:get', id: nextId(), jobId });
-  if (res.type === 'queue:get') return res.job;
-  throw new Error('Unexpected response');
-}
-
 // ── Terminal (PTY sidecar) ──
 
 export function sendPtyCommand(cmd: PtyCommand): void {
@@ -313,3 +280,26 @@ export async function sendPtyCommandAsync(cmd: PtyCommand, timeoutMs = DEFAULT_T
 export function isTerminalConnected(): boolean {
   return findSidecarByCapability('terminal') !== undefined;
 }
+
+// ── VNC ──
+
+export async function startVnc(params: VncStartParams): Promise<{ port: number; display: number }> {
+  const res = await sendCommand('vnc', { type: 'vnc:start', id: nextId(), params });
+  if (res.type === 'vnc:started') return { port: res.port, display: res.display };
+  if (res.type === 'vnc:error') throw new Error(res.error);
+  throw new Error('Unexpected response');
+}
+
+export function stopVnc(email: string): void {
+  sendFire('vnc', { type: 'vnc:stop', id: nextId(), email });
+}
+
+export async function getVncStatus(email: string): Promise<VncSessionInfo | null> {
+  const res = await sendCommand('vnc', { type: 'vnc:status', id: nextId(), email });
+  if (res.type === 'vnc:status') return res.session;
+  throw new Error('Unexpected response');
+}
+
+export function isVncConnected(): boolean {
+  return findSidecarByCapability('vnc') !== undefined;
+}

src/servers/sidecar/protocol.ts

@@ -1,5 +1,4 @@
 import type { MessageCost, PiEvent } from '../api/pi/types';
-import type { Job, EnqueueParams, JobProgress } from '../queue/types';
 
 // ── Envelope ──
 
@@ -23,17 +22,16 @@ export type SidecarCommand =
   | { type: 'pi:abort'; id: string; sessionId: string; requestId: string }
   | { type: 'pi:kill'; id: string; sessionId: string }
   | { type: 'pi:set-thinking'; id: string; sessionId: string; level: string }
-  // Queue
-  | { type: 'queue:enqueue'; id: string; params: EnqueueParams }
-  | { type: 'queue:cancel'; id: string; jobId: string }
-  | { type: 'queue:list'; id: string }
-  | { type: 'queue:get'; id: string; jobId: string };
+  // VNC
+  | { type: 'vnc:start'; id: string; params: VncStartParams }
+  | { type: 'vnc:stop'; id: string; email: string }
+  | { type: 'vnc:status'; id: string; email: string };
 
 // ── Responses/Events (sidecar → API server) ──
 
 export type SidecarEvent =
   | { type: 'pong'; id: string }
-  | { type: 'state:sync'; id: string; state: SidecarState }
+  | { type: 'state:sync'; id: string; state: ClaudeState }
   | { type: 'proxy:secret'; id: string; secret: string }
   // Claude Code
   | { type: 'claude:spawned'; id: string; sessionKey: string }
@@ -47,22 +45,19 @@ export type SidecarEvent =
   | { type: 'pi:event'; sessionId: string; event: PiEvent }
   | { type: 'pi:error'; id: string; error: string }
   | { type: 'pi:killed'; id: string }
-  // Queue
-  | { type: 'queue:enqueued'; id: string; job: Job }
-  | { type: 'queue:cancelled'; id: string; job: Job | null }
-  | { type: 'queue:list'; id: string; jobs: Job[] }
-  | { type: 'queue:get'; id: string; job: Job | null }
-  | { type: 'queue:error'; id: string; error: string }
+  // VNC
+  | { type: 'vnc:started'; id: string; port: number; display: number }
+  | { type: 'vnc:stopped'; id: string }
+  | { type: 'vnc:status'; id: string; session: VncSessionInfo | null }
+  | { type: 'vnc:error'; id: string; error: string }
   // Generic
   | { type: 'error'; id?: string; error: string };
 
-// ── Shared state snapshot ──
+// ── Claude sidecar state ──
 
-export type SidecarState = {
+export type ClaudeState = {
   proxySecret: string;
   claudeSessions: Record<string, string>; // sessionKey → Claude Code session_id
-  piSessions: PiSessionInfo[];
-  uptime: number;
 };
 
 export type PiSessionInfo = {
@@ -114,6 +109,23 @@ export type PiSpawnParams = {
   sessionFile?: string;
 };
 
+// ── VNC types ──
+
+export type VncStartParams = {
+  email: string;
+  username: string;
+  role: string | null;
+  resolution?: string;
+};
+
+export type VncSessionInfo = {
+  email: string;
+  display: number;
+  port: number;
+  pid: number;
+  alive: boolean;
+};
+
 // ── PTY types ──
 
 export type PtyInitConfig = {

src/servers/sidecar/vnc/index.ts

@@ -0,0 +1,68 @@
+import type { SidecarCommand, SidecarEvent } from '../protocol';
+import * as vncManager from './vnc-manager';
+import { createSidecarConnector } from '../connect';
+
+const API_URL = process.env.API_URL ?? `ws://127.0.0.1:${process.env.PORT ?? '5000'}`;
+
+// ── Command handlers ──
+
+type ReplyFn = (msg: SidecarEvent) => void;
+
+async function handleCommand(cmd: SidecarCommand, reply: ReplyFn) {
+  switch (cmd.type) {
+    case 'ping':
+      reply({ type: 'pong', id: cmd.id });
+      break;
+
+    case 'vnc:start': {
+      try {
+        const { port, display } = await vncManager.startSession(cmd.params);
+        reply({ type: 'vnc:started', id: cmd.id, port, display });
+      } catch (err) {
+        reply({ type: 'vnc:error', id: cmd.id, error: err instanceof Error ? err.message : String(err) });
+      }
+      break;
+    }
+
+    case 'vnc:stop':
+      vncManager.stopSession(cmd.email);
+      reply({ type: 'vnc:stopped', id: cmd.id });
+      break;
+
+    case 'vnc:status': {
+      const session = vncManager.getSession(cmd.email);
+      reply({ type: 'vnc:status', id: cmd.id, session });
+      break;
+    }
+
+    default:
+      reply({
+        type: 'error',
+        id: (cmd as SidecarCommand).id,
+        error: `Unknown command type: ${(cmd as Record<string, unknown>).type}`,
+      });
+  }
+}
+
+// ── Connect to API server ──
+
+const connection = createSidecarConnector({
+  apiUrl: `${API_URL}/api/sidecar/register`,
+  name: 'vnc',
+  capabilities: ['vnc'],
+  onCommand(cmd, reply) {
+    handleCommand(cmd as SidecarCommand, reply as ReplyFn);
+  },
+});
+
+// ── Graceful shutdown ──
+
+function shutdown(signal: string) {
+  console.log(`[vnc] ${signal} received, stopping all sessions...`);
+  vncManager.stopAll();
+  connection.destroy();
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));

src/servers/sidecar/vnc/vnc-manager.ts

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { VncStartParams, VncSessionInfo } from '../protocol';
+import { getHomeDirForRole, toShellUsername } from '@@/data-path';
+
+type VncSession = {
+  email: string;
+  username: string;
+  display: number;
+  port: number;
+  pid: number;
+};
+
+const sessions = new Map<string, VncSession>();
+
+function findFreeDisplay(): number {
+  for (let n = 1; n <= 99; n++) {
+    if (existsSync(`/tmp/.X${n}-lock`)) continue;
+    // Also check no existing session uses this display
+    let inUse = false;
+    for (const s of sessions.values()) {
+      if (s.display === n) {
+        inUse = true;
+        break;
+      }
+    }
+    if (!inUse) return n;
+  }
+  throw new Error('No free display number available');
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureVncEnv(homeDir: string): Promise<void> {
+  const vncDir = join(homeDir, '.vnc');
+  if (existsSync(join(vncDir, 'passwd'))) return;
+
+  mkdirSync(vncDir, { recursive: true });
+
+  // Generate random 8-char password
+  const password = Array.from(crypto.getRandomValues(new Uint8Array(6)))
+    .map((b) => String.fromCharCode(33 + (b % 94)))
+    .join('');
+
+  // Write plaintext password (for API to read)
+  await Bun.write(join(vncDir, 'password'), password);
+
+  // Create encrypted passwd using vncpasswd -f
+  const proc = Bun.spawnSync({
+    cmd: ['bash', '-c', `echo '${password.replace(/'/g, "'\\''")}' | vncpasswd -f`],
+    stdout: 'pipe',
+    stderr: 'ignore',
+  });
+  if (proc.exitCode === 0 && proc.stdout.byteLength > 0) {
+    await Bun.write(join(vncDir, 'passwd'), proc.stdout);
+  }
+
+  // Write xstartup
+  await Bun.write(
+    join(vncDir, 'xstartup'),
+    `#!/bin/sh\nunset SESSION_MANAGER\nunset DBUS_SESSION_BUS_ADDRESS\neval $(dbus-launch --sh-syntax)\nexport DBUS_SESSION_BUS_ADDRESS\nexec startxfce4\n`,
+  );
+
+  Bun.spawnSync({ cmd: ['chmod', '+x', join(vncDir, 'xstartup')], stdout: 'ignore', stderr: 'ignore' });
+  Bun.spawnSync({ cmd: ['chmod', '600', join(vncDir, 'passwd')], stdout: 'ignore', stderr: 'ignore' });
+  Bun.spawnSync({ cmd: ['chmod', '600', join(vncDir, 'password')], stdout: 'ignore', stderr: 'ignore' });
+
+  console.log(`[vnc] lazy-provisioned VNC environment at ${vncDir}`);
+}
+
+export async function startSession(params: VncStartParams): Promise<{ port: number; display: number }> {
+  // If session already exists and is alive, return it
+  const existing = sessions.get(params.email);
+  if (existing && isProcessAlive(existing.pid)) {
+    return { port: existing.port, display: existing.display };
+  }
+
+  // Clean up stale session
+  if (existing) {
+    sessions.delete(params.email);
+  }
+
+  const shellUsername = toShellUsername(params.username, params.email);
+  const homeDir = getHomeDirForRole(params.email, params.role);
+  const resolution = params.resolution ?? '1920x1080';
+  const display = findFreeDisplay();
+  const port = 5900 + display;
+
+  // Lazy-provision VNC environment if missing
+  await ensureVncEnv(homeDir);
+
+  // Spawn VNC server as the target user
+  const proc = Bun.spawn({
+    cmd: [
+      'sudo',
+      '-u',
+      shellUsername,
+      'vncserver',
+      `:${display}`,
+      '-geometry',
+      resolution,
+      '-depth',
+      '24',
+      '-localhost',
+      'yes',
+    ],
+    env: { ...process.env, HOME: homeDir },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(`vncserver failed (exit ${exitCode}): ${stderr.trim()}`);
+  }
+
+  // Read PID from lock file
+  let pid = 0;
+  const lockFile = `/tmp/.X${display}-lock`;
+  if (existsSync(lockFile)) {
+    const content = await Bun.file(lockFile).text();
+    pid = parseInt(content.trim(), 10) || 0;
+  }
+
+  sessions.set(params.email, { email: params.email, username: params.username, display, port, pid });
+  console.log(`[vnc] started session for ${params.email} on :${display} (port ${port}, pid ${pid})`);
+
+  return { port, display };
+}
+
+export function stopSession(email: string): void {
+  const session = sessions.get(email);
+  if (!session) return;
+
+  const shellUsername = toShellUsername(session.username, email);
+  const homeDir = getHomeDirForRole(email, null);
+
+  Bun.spawnSync({
+    cmd: ['sudo', '-u', shellUsername, 'vncserver', '-kill', `:${session.display}`],
+    env: { ...process.env, HOME: homeDir },
+    stdout: 'ignore',
+    stderr: 'ignore',
+  });
+
+  sessions.delete(email);
+  console.log(`[vnc] stopped session for ${email} on :${session.display}`);
+}
+
+export function getSession(email: string): VncSessionInfo | null {
+  const session = sessions.get(email);
+  if (!session) return null;
+
+  const alive = session.pid > 0 && isProcessAlive(session.pid);
+  if (!alive) {
+    sessions.delete(email);
+    return null;
+  }
+
+  return {
+    email: session.email,
+    display: session.display,
+    port: session.port,
+    pid: session.pid,
+    alive,
+  };
+}
+
+export function stopAll(): void {
+  for (const email of [...sessions.keys()]) {
+    stopSession(email);
+  }
+}