open-terminal

Executes shell commands asynchronously via POST /execute endpoint and streams output to JSONL log files, tracking process state in an in-memory registry. Uses FastAPI background tasks to decouple command submission from execution, enabling agents to poll status or stream results without blocking. Each BackgroundProcess instance maintains PID, original command, ProcessRunner reference, and async log task that captures stdout/stderr separately or merged.

Creates and manages interactive pseudo-terminal (PTY) sessions via WebSocket at /api/terminals/* endpoints, enabling real-time bidirectional communication between agents and shell environments. Each terminal session maintains its own process state, environment variables, and working directory. Uses WebSocket handlers to forward stdin/stdout/stderr in real-time, supporting interactive tools like editors, REPLs, and shell prompts that require immediate feedback.

Supports multi-user deployments via X-User-Id header that scopes all operations (file access, process execution, terminal sessions) to individual users. Each user gets isolated filesystem views, separate background process registries, and independent terminal sessions. User isolation is enforced at the FastAPI dependency layer (get_filesystem() dependency) and propagated through all subsystems (ProcessRunner, TerminalSession, NotebookSession).

Exposes GET /health endpoint that returns service health status and readiness information, enabling load balancers and orchestration systems to detect when Open Terminal is ready to accept requests. Health check is lightweight and does not require authentication, making it suitable for frequent polling by infrastructure monitoring systems.

Provides multi-user file system isolation via UserFS abstraction layer that scopes all file operations to a user-specific directory based on X-User-Id header. Implemented as a dependency injection in FastAPI (get_filesystem() dependency), it intercepts all file reads/writes and enforces path normalization to prevent directory traversal attacks. Each user sees a sandboxed view of the filesystem rooted at their user directory.

Exposes comprehensive file operations via /files/* REST endpoints including read, write, list, delete, and archive (tar/zip) operations. Implements atomic writes with temporary files to prevent corruption, supports streaming large file downloads, and provides directory listing with metadata (size, modification time, permissions). Archive operations support both creation and extraction with configurable compression formats.

Executes Jupyter notebooks via /notebooks/* endpoints with per-cell execution tracking and output capture. Maintains notebook session state across multiple cell executions, enabling agents to run data analysis workflows. Each cell execution is tracked separately with input/output/error metadata, and the kernel state persists across requests, allowing subsequent cells to reference variables from previous cells.

Detects open ports on the host via /ports endpoint and provides HTTP proxying via /proxy/* to forward requests to services running on those ports. Enables agents to discover and interact with services (web servers, APIs, databases) running locally without direct network access. Proxying handles request/response forwarding with header manipulation and connection pooling.

Implements Bearer token authentication via verify_api_key() FastAPI dependency that validates API keys using constant-time comparison (hmac.compare_digest()) to prevent timing attacks. All endpoints except /health and /system require valid API key in Authorization header. Authentication is enforced at the dependency injection layer, making it transparent to endpoint handlers.

Exposes GET /api/config endpoint that returns feature flags and capability metadata, enabling clients to discover which features are enabled (e.g., notebook execution, multi-user mode, MCP server). Returns JSON with boolean flags for each feature, allowing agents to conditionally use capabilities based on server configuration without hardcoding assumptions.

Exposes GET /system endpoint that returns a system prompt describing Open Terminal's capabilities, API endpoints, and usage patterns. Designed for LLM context injection, the prompt includes endpoint descriptions, authentication requirements, and examples of common workflows. Enables LLMs to understand how to use Open Terminal without requiring external documentation.

Implements a Model Context Protocol (MCP) server at open_terminal/mcp_server.py that exposes Open Terminal capabilities as MCP tools, enabling Claude and other MCP-compatible LLMs to call Open Terminal functions directly. The MCP server wraps REST endpoints as tool definitions with JSON schemas, allowing LLMs to invoke commands, file operations, and terminal sessions through the MCP protocol without manual HTTP calls.