Пользовательский интерфейс¶

local-shell-mcp предоставляет два совместимых пользовательских интерфейса поверх одного service API, workspace, реестра persistent terminals, реестра remote workers и MCP audit log:

Web UI — нативная браузерная панель, оптимизированная для быстрой операционной проверки.
OpenTUI — полнофункциональное терминальное приложение, доступное как внутри браузера, так и в виде нативной терминальной команды.

Ни один режим не создаёт отдельный control plane. Переключение интерфейса не изменяет подключённые машины, Sessions, jobs, разрешения или audit data.

Запуск сервиса¶

Запустите local-shell-mcp обычным способом:

local-shell-mcp --mode mcp

ChatGPT Live Workspace¶

Когда ChatGPT отображает MCP Apps, workspace_open(session_id=...) открывает плавающее совместное представление явно выбранной Logical Session. Session хранит долговечное состояние задачи — objective, progress, Plan и Activity, — а Live Workspace только показывает это состояние, текущую активность и элементы управления для человека. Он никогда не выводит идентичность задачи из MCP transport.

Типичная явная передача работы выглядит так:

session_manage(action="start", objective=...)
        -> session_id
... вызовы инструментов с logical_session_id=session_id
... session_manage(action="report", session_id=...) ...
новый разговор ChatGPT
пользователь передаёт прежний session_id
session_manage(action="resume", session_id=...)
        -> существующие progress, Plan и недавняя Activity
workspace_open(session_id=...)
        -> представление той же Session

session_id — единственная долговечная идентичность задачи. Agent не должен перечислять, угадывать или автоматически выбирать Session из другого разговора. Чтобы продолжить работу в новом разговоре, пользователь явно передаёт существующий session_id. Agent должен сообщать активный session_id после start/resume, на значимых checkpoints прогресса и перед завершением turn, чтобы его можно было передать вручную. Sessions не привязаны к machine или working directory; обычные параметры инструментов по-прежнему выбирают local/remote targets и paths.

Необязательный Plan plan_manage включает Goal mode для Session. Если Plan active и в течение 15 минут нет agent activity, связанный Live Workspace может попросить ChatGPT продолжить работу. Continuation возобновляет тот же явный session_id и ограничена 10 попытками, независимо от принятия или отказа. Plans со статусом blocked, completed или cancelled не продолжаются автоматически; active Plan, у которого все steps completed или skipped, остаётся доступен для завершающей continuation, чтобы возобновлённый agent мог закончить Plan. Человеческие элементы pause/resume/cancel изменяют Plan, принадлежащий Session, а не временное состояние Live Workspace.

Браузерный интерфейс¶

Откройте:

http://127.0.0.1:8765/ui

Для публичного развёртывания используйте настроенный HTTPS origin:

https://your-public-host.example.com/ui

Браузерный интерфейс использует тот же OAuth-сервер и те же scopes, что и MCP. Оболочка страницы и статические ресурсы публичны, чтобы могла загрузиться форма входа, но /api/ui/* и терминальный WebSocket OpenTUI остаются защищёнными. Токены доступа хранятся только в session storage браузера.

Выбор интерфейса¶

Экран OAuth предлагает две точки входа:

Open Web UI выполняет авторизацию и открывает нативную панель.
Continue to OpenTUI выполняет авторизацию и открывает терминальный интерфейс, сохраняя прежнее поведение браузера.

После авторизации переключатель в боковой панели позволяет переходить между Web UI и OpenTUI без повторного входа. Текущая нативная страница запоминается при временном переходе в OpenTUI.

Маршруты можно добавлять в закладки:

/ui/#/overview
/ui/#/machines
/ui/#/workloads
/ui/#/activity
/ui/#/console

#/web и #/dashboard — алиасы Overview. #/tui и #/opentui — алиасы Console.

Нативный Web UI¶

Нативный Web UI опрашивает существующий API пользовательского интерфейса каждые пять секунд и отображает браузерные элементы управления вместо терминальных ячеек. PTY не запускается до выбора OpenTUI.

Overview¶

Overview в первую очередь показывает наиболее важную операционную информацию:

Состояние controller и текущую версию LSM.
Количество онлайн- и офлайн-машин.
Активные tracked jobs и постоянные терминальные сессии.
CPU, память, диск workspace, load, сетевую пропускную способность и uptime.
Оповещения, сформированные по состоянию workers, порогам ресурсов, неудачным jobs и неудачным вызовам MCP.
Недавнюю MCP-активность, инициированную моделью.

Machines¶

Machines показывает локальный controller и подключённых удалённых workers с их состоянием, платформой, версией, рабочим каталогом, возможностями и информацией last-seen.

Workloads¶

Workloads объединяет активные tracked jobs и отдельные постоянные shell-сессии. В Web UI эти записи доступны только для чтения; для интерактивного управления сессиями используйте OpenTUI.

Activity¶

Activity объединяет текущие оповещения с недавней MCP-аудит активностью. Команды и файловые операции, введённые человеком, не включаются в журнал аудита MCP.

OpenTUI в браузере¶

При выборе OpenTUI лениво запускается то же приложение OpenTUI, что используется нативным терминальным launcher. Браузерная console сохраняет:

Аутентифицированный бинарный PTY-транспорт по WebSocket.
Автоматическое изменение размера терминала и backoff переподключения.
Взаимодействие мышью с элементами OpenTUI.
Полноэкранный режим и безопасные для браузера сочетания клавиш.
Мобильные быстрые клавиши и явное управление экранной клавиатурой.
Поддержку SIXEL и inline image через xterm.js.

Пока пользователь остаётся в нативном режиме Web UI, браузер не создаёт OpenTUI PTY.

Нативный OpenTUI¶

Автономные release-исполняемые файлы включают платформенный runtime OpenTUI. Оставьте только основной исполняемый файл, запустите сервис, затем выполните:

local-shell-mcp tui

Нативный TUI не требует входа от человека-оператора. Launcher прозрачно передаёт сгенерированную локальную учётную запись loopback API. Она хранится в настроенном state directory с правами только владельца; reverse proxy, подключающийся через loopback, этот bypass не получает.

Source checkout также может запускать TUI после установки зависимостей Bun:

cd ui
bun install --frozen-lockfile
bun run build
cd ..
local-shell-mcp tui

Используйте --api-base только если локальный сервис работает на нестандартном порту:

local-shell-mcp tui --api-base http://127.0.0.1:9876/api/ui

Экраны OpenTUI¶

Dashboard¶

Dashboard — операционный обзор OpenTUI. На широких терминалах отдельно показываются области node, workload, alert, activity, системная информация и trends; на узких они сворачиваются в компактные сводки без горизонтальной прокрутки.

Files¶

Files — нативный трёхпанельный файловый менеджер LSM для локальных и удалённых машин. Он поддерживает создание, редактирование, переименование, копирование, перемещение, вставку, удаление, переключение скрытых файлов, обновление, просмотр текста, просмотр бинарных данных и ограниченные миниатюры изображений.

Terminals¶

Terminals управляет постоянными shell-сессиями на локальных и удалённых машинах. Поддерживаются ввод полных команд, raw-интерактивный ввод, переключение сессий, создание и завершение сессий, недавний вывод и сворачиваемая MCP-аудит панель.

Audit¶

Audit читает ограниченный JSONL-журнал аудита и поддерживает фильтры node, operation, event, session, search, time-range и sort, а также просмотр деталей записей.

Remotes¶

Remotes показывает онлайн- и офлайн-удалённых workers, их возможности, рабочие каталоги и системные метаданные. Здесь можно создать одноразовую join invite, переименовать node или отозвать его постоянную identity.

Навигация OpenTUI¶

Верхняя панель категорий и контекстные действия footer доступны по щелчку мыши как в нативных терминалах, так и в браузерной console.

Клавиши	Действие
`Alt+1` … `Alt+5`	Открывает Dashboard, Files, Terminals, Remotes или Audit.
`F2` … `F6`	Альтернативные shortcuts категорий.
`F1`	Открыть руководство по клавиатуре.
`F9`	Обновить список машин.
`Alt+Q`	Завершить нативный процесс OpenTUI, не вызывая зарезервированное браузером Ctrl-сочетание.

Terminals использует Alt+N для новой сессии, Alt+W для завершения выбранной сессии, Alt+A для переключения панели аудита, Alt+R для обновления и Alt+Left/Right для переключения между сессиями. Браузерная console перехватывает эти сочетания до обработки навигации или меню браузером.

Конфигурация¶

Ключ YAML	Переменная окружения	По умолчанию	Назначение
`ui_enabled`	`LOCAL_SHELL_MCP_UI_ENABLED`	`true`	Подключить или отключить пользовательские интерфейсы.
`ui_path`	`LOCAL_SHELL_MCP_UI_PATH`	`/ui`	Путь монтирования браузерного интерфейса на сервисе MCP.
`ui_tui_command`	`LOCAL_SHELL_MCP_UI_TUI_COMMAND`	auto	Переопределить поиск нативного исполняемого файла OpenTUI.
`ui_wallpaper`	`LOCAL_SHELL_MCP_UI_WALLPAPER`	`bing`	Настройка обоев для развёртываний браузерной console OpenTUI.
`ui_terminal_idle_timeout_s`	`LOCAL_SHELL_MCP_UI_TERMINAL_IDLE_TIMEOUT_S`	`3600`	Закрыть неактивный браузерный OpenTUI PTY через указанное число секунд; `0` отключает timeout.
`ui_terminal_max_sessions`	`LOCAL_SHELL_MCP_UI_TERMINAL_MAX_SESSIONS`	`8`	Максимальное число одновременных браузерных OpenTUI PTY-сессий.

Примечания по упаковке¶

Docker-образы включают ресурсы Web UI и нативный runtime OpenTUI.
Автономные исполняемые файлы включают ресурсы Web UI и сжатый платформенный runtime OpenTUI.
Python wheels включают браузерные ресурсы; для нативного OpenTUI требуется release-исполняемый файл или source checkout с установленными зависимостями Bun.
Оба интерфейса обслуживаются тем же процессом и портом, что и MCP; дополнительный веб-сервис не требуется.