@companyos/terminal-server

Local WebSocket server that spawns and manages pseudo-terminal (PTY) sessions for AI CLI tools (Claude Code, Codex, Gemini) and interactive shells.

Depends On

• node-pty -- pseudo-terminal spawning
• ws -- WebSocket server
• zod -- env var validation

Key Exports

• SERVER_CONFIG -- resolved server configuration (port, origins, max sessions, idle timeout)
• buildSpawnConfig / SpawnConfig / CreateMessage -- PTY spawn configuration builder
• ServerMessage / ClientMessage -- WebSocket protocol types

Endpoints

| Path | Method | Description | |--------------|--------|--------------------------------------------------| | /health | GET | Server status and active session count | | /status | GET | Claude CLI availability check | | /sessions | GET | Lists Claude Code sessions from ~/.claude/ | | /clis | GET | Detected CLI tools (claude, codex, gemini) | | ws:// | WS | Terminal PTY session (create, input, resize, ping) |

Scripts

| Script | Command | Description | |---------|----------------------|-----------------------------| | dev | npx tsx src/index.ts | Run with ts-node (dev mode) | | build | tsc -b | Compile TypeScript | | start | node dist/index.js | Run compiled server |

Configuration

Environment variables (all optional with defaults):

| Variable | Default | Description | |-----------------------------------|---------|--------------------------------| | TERMINAL_SERVER_PORT | 3002 | HTTP/WS listen port | | ALLOWED_ORIGINS | (list) | Comma-separated allowed origins | | TERMINAL_SERVER_MAX_SESSIONS | 5 | Max concurrent PTY sessions | | TERMINAL_SERVER_IDLE_TIMEOUT_MS | 1800000 | Session idle timeout (30min) | | TERMINAL_SERVER_TOKEN | (none) | Auth token for WS connections | | COMPANYOS_WORKSPACE_ROOT | $HOME | Default working directory |