OpenShell TUI Development Guide

Comprehensive reference for any agent working on the OpenShell TUI.

1. Overview

The OpenShell TUI is a ratatui-based terminal UI for the OpenShell platform. It provides a keyboard-driven interface for managing gateways, sandboxes, and logs, the same operations available via the openshell CLI, but with a live, interactive dashboard.

• Launched via: openshell term or mise run term
• Crate: crates/openshell-tui/
• Key dependencies:
  • ratatui (workspace version), uses frame.area() for the drawable terminal area
  • crossterm (workspace version), terminal backend and event polling
  • tonic with TLS, gRPC client for the OpenShell gateway
  • tokio, async runtime for event loop, spawned tasks, and mpsc channels
  • openshell-core, proto-generated types (OpenShellClient, request/response structs)
  • openshell-bootstrap, gateway discovery (list_gateways())
• Theme: Adaptive dark/light via Theme struct, NVIDIA-branded green accents. Controlled by --theme flag, OPENSHELL_THEME env var, or auto-detection.

2. Domain Object Hierarchy

The data model follows a strict hierarchy: Gateway > Workspace > Sandboxes/Providers/Settings > Logs.