​
Performance Architecture

​
Session Management Models

VibeTunnel supports two distinct session management approaches, each with different performance characteristics:

​
1. Server-Managed Sessions (API-initiated)

Sessions created via POST /api/sessions are spawned directly within the server’s Node.js process. These sessions benefit from:
  • Direct PTY communication: Input and resize commands bypass the command pipe system
  • Reduced latency: No inter-process communication overhead for terminal interactions
  • Immediate responsiveness: Direct memory access to PTY stdout/stdin

​
2. External Sessions (vt-initiated)

Sessions started via the vt command run in a separate Node.js process with:
  • File-based communication: PTY stdout is written to disk files
  • Command pipe interface: Resize and input commands are passed through IPC
  • Additional latency: File I/O and IPC overhead for all terminal operations

​
Server Architecture

​
Session Discovery and Management

The server performs two primary management tasks:
  1. External Session Monitoring
    • Watches control directory for new external sessions
    • Automatically registers discovered sessions with the terminal manager
    • Maintains in-memory buffer cache (cols × rows) for text/buffer API endpoints
  2. Client Connection Handling
    • WebSocket connections trigger file watchers on session stdout files
    • File watchers stream new output to connected clients in real-time
    • Multiple clients can connect to the same session simultaneously

​
Memory Management

  • Buffer caching: Last visible scrollbuffer (terminal dimensions) kept in memory
  • Efficient retrieval: Text and buffer API endpoints serve from memory cache
  • File streaming: WebSocket clients receive updates via file watchers

​
Known Performance Issues

​
Session Creation Blocking

Symptom: All sessions freeze temporarily when creating a new session Cause: Synchronous operations during session creation
  • Session creation endpoint waits for process spawn completion
  • PTY initialization must complete before returning
  • Any synchronous operation blocks the entire Node.js event loop
Impact: All active sessions become unresponsive during new session initialization

​
Potential Solutions

  1. Async session creation: Move blocking operations to worker threads
  2. Pre-spawn PTY pool: Maintain ready PTYs to reduce creation time
  3. Event loop monitoring: Identify and eliminate synchronous operations
  4. Progressive initialization: Return session ID immediately, initialize asynchronously

​
Performance Optimization Strategies

​
For Server-Managed Sessions

  • Minimize synchronous operations in session creation
  • Use Node.js worker threads for CPU-intensive tasks
  • Implement connection pooling for database operations

​
For External Sessions

  • Consider memory-mapped files for stdout communication
  • Implement file change batching to reduce watcher overhead
  • Use efficient file formats (binary vs text) where appropriate

​
General Optimizations

  • Profile event loop blocking with tools like clinic.js
  • Implement request queuing for session creation
  • Add performance metrics and monitoring
  • Consider horizontal scaling with session affinity