​

VibeTunnel Socket Protocol

​

Overview

​

Architecture

​

Components

1. PTY Manager (Server)
   • Creates Unix domain socket at {session_dir}/ipc.sock
   • Handles multiple client connections
   • Manages PTY process I/O
   • Tracks session state and Claude status
2. Socket Client (fwd.ts and other clients)
   • Connects to session’s Unix socket
   • Sends stdin data and control commands
   • Receives status updates and errors
   • Supports auto-reconnection

​

Socket Path

• Location: {control_dir}/{session_id}/ipc.sock
• Example: /tmp/vt-1234567890/a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6/ipc.sock

​

Message Format

​

Frame Structure

+--------+--------+--------+--------+--------+----------------+
| Type   | Length                           | Payload        |
| 1 byte | 4 bytes (big-endian uint32)      | Length bytes   |
+--------+--------+--------+--------+--------+----------------+

• Type: Single byte indicating message type
• Length: 32-bit unsigned integer in big-endian format
• Payload: Variable-length data (format depends on message type)

​

Message Types

​

Message Payloads

​

STDIN_DATA (0x01)

• Payload: UTF-8 encoded string
• Example: "ls -la\n"

​

CONTROL_CMD (0x02)

• Payload: JSON object
• Commands:
  Copy

  // Resize terminal
  { "cmd": "resize", "cols": 120, "rows": 40 }
  
  // Kill process
  { "cmd": "kill", "signal": "SIGTERM" }
  
  // Reset terminal size
  { "cmd": "reset-size" }
  

​

STATUS_UPDATE (0x03)

• Payload: JSON object
• Format:
  Copy

  {
    "app": "claude",
    "status": "✻ Thinking (5s, ↑2.5k tokens)",
    // Optional extra fields
    "tokens": 2500,
    "duration": 5000
  }
  

• Broadcast: Server broadcasts status updates to all connected clients

​

HEARTBEAT (0x04)

• Payload: Empty (0 bytes)
• Behavior:
  • Clients can send periodic heartbeats
  • Server echoes heartbeats back
  • Used to detect connection health

​

ERROR (0x05)

• Payload: JSON object
• Format:
  Copy

  {
    "code": "SESSION_NOT_FOUND",
    "message": "Session does not exist",
    "details": { /* optional */ }
  }
  

​

Error Codes

{
  "code": "MESSAGE_PROCESSING_ERROR",
  "message": "Failed to parse control command",
  "details": {
    "error": "Unexpected token } in JSON at position 42",
    "messageType": 2
  }
}

​

Client Implementation

​

Connection Flow

1. Connect to Unix socket at {session_dir}/ipc.sock
2. Receive any initial status updates from server
3. Send messages as needed
4. Handle incoming messages asynchronously
5. Reconnect automatically on disconnection (optional)

​

Example Usage

import { VibeTunnelSocketClient } from './socket-client.js';

// Connect to session
const client = new VibeTunnelSocketClient('/path/to/session/ipc.sock', {
  autoReconnect: true,
  heartbeatInterval: 30000 // 30 seconds
});

// Listen for events
client.on('connect', () => console.log('Connected'));
client.on('status', (status) => console.log('Status:', status));
client.on('error', (err) => console.error('Error:', err));

// Connect and use
await client.connect();

// Send terminal input
client.sendStdin('echo "Hello, World!"\n');

// Resize terminal
client.resize(120, 40);

// Send Claude status
client.sendStatus('claude', '✻ Thinking', { tokens: 1000 });

// Disconnect when done
client.disconnect();

​

Server Implementation

​

Socket Server Setup

// Create socket server
const server = net.createServer((client) => {
  const parser = new MessageParser();
  
  // Send initial status if available
  if (claudeStatus) {
    client.write(frameMessage(MessageType.STATUS_UPDATE, claudeStatus));
  }
  
  // Handle incoming messages
  client.on('data', (chunk) => {
    parser.addData(chunk);
    
    for (const { type, payload } of parser.parseMessages()) {
      handleMessage(type, payload, client);
    }
  });
});

// Listen on socket
server.listen(socketPath);

​

Message Handling

• STDIN_DATA: Write to PTY process
• CONTROL_CMD: Handle resize/kill commands
• STATUS_UPDATE: Store status and broadcast to other clients
• HEARTBEAT: Echo back to sender

​

Protocol Features

​

Message Framing

• Partial messages: TCP may split messages across packets
• Multiple messages: TCP may combine messages in one packet
• Large payloads: No practical size limit (up to 4GB per message)
• Binary safety: Handles null bytes and non-UTF8 data

​

Connection Management

• Multiple clients: Server supports multiple simultaneous connections
• Auto-reconnection: Clients can automatically reconnect on failure
• Heartbeats: Optional periodic heartbeats for connection health
• Graceful shutdown: Proper cleanup of resources

​

Status Broadcasting

1. Server stores the status in memory
2. Server broadcasts to all other connected clients
3. New clients receive current status on connection

​

Migration from File-Based IPC

​

Previous System

• Control commands via {session_dir}/control-pipe file
• Activity updates via {session_dir}/activity.json file
• Required file watching and polling

​

New System

• All communication through single Unix socket
• Real-time bidirectional messaging
• No file watching or polling needed
• Better performance and cleaner architecture

​

Error Handling

​

Connection Errors

• ENOENT: Socket file doesn’t exist (session not found)
• ECONNREFUSED: Server not listening (session crashed)
• EINVAL: Socket path too long (macOS limit)

​

Protocol Errors

• Malformed messages are logged and ignored
• Server sends ERROR message for processing failures
• Clients should handle disconnections gracefully

​

Performance Considerations

1. Message Size: Keep messages reasonably sized (< 1MB)
2. Heartbeat Interval: 30-60 seconds is typical
3. Reconnect Delay: 1-5 seconds between attempts
4. Socket Backlog: Default is sufficient for typical usage

​

Security Notes

• Sockets are created with 0666 permissions (world-writable)
• Rely on directory permissions for access control
• No authentication or encryption (local use only)
• Validate all JSON payloads before processing

​

Implementation Files

• Protocol: src/server/pty/socket-protocol.ts
• Client: src/server/pty/socket-client.ts
• Server: src/server/pty/pty-manager.ts (setupIPCSocket method)
• Tests: src/test/unit/socket-*.test.ts, src/test/integration/socket-*.test.ts

​

Future Enhancements

• Message compression for large payloads
• Authentication for multi-user systems
• Encryption for sensitive data
• Request/response correlation IDs
• Batch message support