Human interface¶
The HTTP server includes a browser interface for managing the local server and enrolled remote workers. An optional OpenTUI client provides the same main areas in a terminal.
Start the browser interface¶
Run the HTTP server:
Open:
When the service is exposed through a public hostname, use the corresponding public /ui URL and sign in through OAuth. Do not expose an unauthenticated HTTP service to a shared or public network.
The UI path and enablement can be changed through LOCAL_SHELL_MCP_UI_PATH and LOCAL_SHELL_MCP_UI_ENABLED. See Configuration.
Start OpenTUI¶
Keep the HTTP server running, then start the terminal client in another terminal:
By default it connects to the loopback Human UI API on the configured server port. Use --api-base only when the local API is listening at another loopback URL.
OpenTUI availability depends on the installation and platform. If the native client is unavailable, use the browser interface or install a supported platform build; see Install options. Source contributors should use Development and Native artifact provenance.
Browser OpenTUI Console¶
When an OpenTUI runtime is available, the browser UI can also show an OpenTUI Console. It launches a separate terminal UI inside the browser; closing that console stops only the console client, not the HTTP server or existing persistent shells.
Main areas¶
Dashboard¶
View health, resource usage, recent activity, and alerts for the selected local or remote machine. Missing metrics are shown as unavailable rather than guessed.
Remotes¶
Create an invite, see whether workers are online, copy a reconnect command, and revoke workers. Enrollment and service management are covered in Remote workers.
Terminals¶
Create, attach to, resize, and close persistent terminals. A persistent shell continues after the browser tab or OpenTUI client disconnects. Closing a client view does not necessarily terminate the underlying shell; use the explicit terminate action when you are finished.
Interactive terminal support depends on the selected machine. When a full interactive stream is unavailable, the UI falls back to a compatible snapshot view.
Files¶
Browse the selected workspace, preview supported files, edit bounded UTF-8 text files, create files, and perform the operations offered by the selected machine. The UI refuses unsafe partial edits and reports when a file changed concurrently.
Some remote file operations may be unavailable. The UI shows the available actions instead of emulating missing operations with shell commands. Use session_copy through an MCP client for cross-workspace transfers.
Todos¶
View and update the Todo list associated with a local or remote workspace session. If another client changes the same list, reload the latest version instead of overwriting it.
Audit¶
Filter recent activity and inspect details allowed by the current OAuth scopes. Audit entries may contain project text and command output; treat them as sensitive. See Audit log.
Authentication and sessions¶
The browser uses the server's OAuth flow and the configured admin PIN for
approval. Sign out from the UI when using a shared browser. A 401 normally
means the session must authenticate again; a 403 means the current session is
valid but lacks a required scope.
The native OpenTUI client connects only through the trusted loopback Human UI API. Do not place credentials in --api-base or expose that private local API as a public endpoint.
Common problems¶
/uireturns 404: confirm the server is in supportedmcporhttpmode and the UI is enabled. The reservedbothmode does not start a server.- OpenTUI cannot start: use the browser UI, then confirm that your installation contains a platform-native runtime.
- A remote panel is unavailable: verify that the worker is online and supports the requested operation.
- A terminal looks disconnected: reattach to the persistent shell or use its snapshot view.
- An action is forbidden: sign in again with the scopes required for that operation.
See Troubleshooting for server-wide diagnostics and Security for the trust model.