Architecture: How should VM sessions be managed per user — persistent alwa...

Documentation for Sessions

🏗️ Architecture: How should VM sessions be managed per user — persistent alwa...

Date: 2026-03-20
Time: 17:40:06 UTC
Session: gspace1-240.3
Agent: backend
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How should VM sessions be managed per user — persistent always-on VMs vs snapshot-based restore?

Task: S240: VM per-user session lifecycle

🎯 Decision Made

Chosen:

Snapshot-based per-user sessions via VmSessionManagerService. Each user gets a 2GB micro-space that is snapshotted when idle and restored in ~500ms on demand. Credentials, deploy keys, and environment are persisted in the snapshot — not re-injected on every boot. VmCredentialInjectorService handles first-time setup only.

Options Considered:

Always-on persistent 2GB VMs per user (original design)
Snapshot-based restore on demand (~500ms, credentials in snapshot)
Ephemeral VMs from warm pool (no persistence, re-setup each time)

💭 Reasoning

Original design (pre-S240) intended always-on 2GB micro-spaces per user. Analysis showed this wastes resources when users are idle (most of the day). Firecracker snapshot/restore is ~500ms vs 10s cold boot — nearly indistinguishable from always-on for the user. Snapshot preserves full filesystem state including credentials, SSH keys, git config, installed packages. Cost: 2GB RAM only while active vs 2GB 24/7. With 100 users, that's 200GB always-on vs ~20GB peak. 10x cost reduction. The SelfHostedProvider already has snapshotAndSuspend/restoreFromSnapshot — infrastructure exists, just needed session-level lifecycle management.

📁 Files Involved

APIs/backend-vitto-api/src/app/engine/vm-session-manager.service.ts
APIs/backend-vitto-api/src/app/engine/vm-credential-injector.service.ts
APIs/backend-vitto-api/src/app/engine/vm-api-client.service.ts

🔗 Related

Decision ID: dev_1774028406609_8b11um0
Session: 240
Workspace: gspace1

Auto-generated by MCP Smart Consolidation