🏗️ Architecture: How to enable Vitto to control the user's local machine when...

Date: 2026-02-24
Time: 00:41:29 UTC
Session: gspace1-138.4
Agent: backend
Confidence: 88%
Status: ✅ Documented

📋 Decision Context

Question:

How to enable Vitto to control the user's local machine when running in the cloud?

Task: GAP 3: Vitto Local Bridge

🎯 Decision Made

Chosen:

Two-layer approach: (1) NestJS WebSocket gateway (LocalBridgeGateway, namespace /local-bridge) in backend-vitto-api that receives connections from local agents, stores per-user sockets, and exposes executeTool(userId, toolName, input) returning a Promise. (2) Lightweight Node.js client (apps/vitto-local-bridge/index.js) using socket.io-client that connects to the gateway, listens for tool:execute events, runs them locally, and emits tool:result back.

Options Considered:

• No alternatives documented

💭 Reasoning

The fundamental problem is network topology: cloud Vitto can't reach the user's machine. The only solution is to have the user's machine initiate the connection (WebSocket from local → cloud). Socket.IO over the existing NestJS infrastructure is the simplest path — no new infrastructure, uses the already-installed @nestjs/websockets + socket.io-client packages. The local client is a single JS file (no build step) that any developer can run with Node.js.

📁 Files Involved

• apis/backend-vitto-api/src/app/engine/local-bridge.gateway.ts
• apis/backend-vitto-api/src/app/engine/engine.module.ts
• apis/backend-vitto-api/src/app/engine/vitto.controller.ts
• apps/vitto-local-bridge/index.js
• libs/libs-ai/vitto-hub/src/lib/components/vitto-settings/vitto-settings.component.ts
• libs/libs-ai/vitto-hub/src/lib/components/vitto-settings/vitto-settings.component.html

🔗 Related

• Decision ID: dev_1771893689765_lyhqekr
• Session: 138
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation