Skip to main content

Terminal Monitor

Terminal Monitor is a small React web dashboard that lets you watch and drive a running TermFlow instance's terminals from a browser tab — a companion app that talks to TermFlow's local REST + WebSocket API.

Companion app, not part of the installed app

Terminal Monitor is a separate application that lives in the terminal-monitor/ directory of the TermFlow source repository. It is run from source with npm start; it is not bundled into the TermFlow installer and does not ship as a binary. Think of it as an optional, browser-based control surface for people who want to keep an eye on TermFlow's terminals from another window, tab, or machine on their desk.

What it is​

The desktop TermFlow app already runs a local API server (REST + WebSocket) so that agents and your own tooling can drive terminals. Terminal Monitor is a thin web client on top of that same API. Instead of the native window, you get a dark, browser-based dashboard that:

  • lists the live terminals in a running (headless) TermFlow instance,
  • streams each terminal's output in real time over WebSocket,
  • lets you send input and a few special keys, and
  • can create and delete terminals.

It serves its UI on port 42030 and connects to the TermFlow backend's REST + WebSocket API (prod port 42031). It uses no AI of its own — it is purely a viewer and remote control for terminals that already exist in TermFlow.

What it does​

CapabilityDetail
Terminal listA collapsible sidebar of the instance's active terminals; click one to view it.
Live outputReal-time terminal output streamed over WebSocket and rendered with xterm.js.
Send inputType a command and press Enter to send it to the selected terminal.
Special keysA slim touch-keys bar sends Ctrl+C, Ctrl+D, ESC, and TAB.
Grid viewWhen more than one terminal is open, view several terminals side by side.
Create / delete"New Terminal" in the header; delete a terminal from the list.
Periodic refreshThe terminal list is re-polled about every 10 seconds (paused when the tab is hidden), on top of the live WebSocket stream.

Under the hood it is a Create React App / craco project using TypeScript, Redux Toolkit for state, Material-UI for the dark theme, xterm.js for the terminal display, and Axios for REST calls.

How it connects​

The dashboard is just a web front end. All the real work — spawning shells, running commands, capturing output — happens inside the TermFlow backend. The monitor reaches it through the documented REST endpoints and the WebSocket stream. See /api-reference/websocket for the exact frame formats it consumes.

Starting it​

Prerequisites: a running TermFlow instance (its API server must be up), plus Node.js and npm.

  1. Start TermFlow so its API server is listening (the installed app starts it automatically; from source, npm run dev runs the dev build).

  2. In the source repo, from the terminal-monitor/ directory, install dependencies once:

    cd terminal-monitor
    npm install

  3. Start the dashboard:

    npm start

  4. Open your browser to http://localhost:42030.

Point it at the right backend port​

The monitor needs to know which TermFlow backend to talk to. The port depends on whether you are running the installed app or a development build:

You are runningBackend API portHow to start the monitor
Installed TermFlow app (production)42031npm run start:prod (wires the monitor to http://localhost:42031)
tauri dev build (from source)42051npm start (the bundled dev config wires it to http://localhost:42051)

You can also override the target explicitly with the REACT_APP_API_URL and REACT_APP_WS_URL environment variables — see the project's .env.example for every available setting.

The dashboard layout​

+-----------------------------------------------------------------+
| Terminal Monitor          [ New Terminal ]   [ Grid ]   [ user ]|  <- header
+-------------------+---------------------------------------------+
| Terminals         |  terminal-3  (running)                      |
|   terminal-1      |                                             |
|   terminal-2      |    $ npm test                               |
| > terminal-3      |    PASS  src/app.test.ts                    |
|   terminal-4      |                                             |
|                   |                                             |
| [ collapse  <<  ] |                                             |
+-------------------+---------------------------------------------+
| [Ctrl+C] [Ctrl+D] [ESC] [TAB]    type a command...      [ Send ]|  <- touch-keys bar
+-----------------------------------------------------------------+

The left sidebar is the terminal list (collapsible). The main pane is the live viewer for the selected terminal. The bar along the bottom is for native typing plus the four special keys; with more than one terminal open, the header's Grid toggle switches to a multi-terminal view.

Signing in​

On first visit the app redirects to a small login screen titled Terminal Monitor with a single Client ID field (default terminal-monitor) and a Connect button.

In the default localhost setup this is effectively a formality: because the TermFlow API is bound to 127.0.0.1, every endpoint is unauthenticated, so the monitor connects to a backend on the same machine without a real credential. The point of exposure is the network boundary, not the login form.

An honest note: The login screen is legacy scaffolding. It mints a token from a compatibility endpoint that TermFlow's auth gate does not actually check, so it is not what secures your API calls. On localhost you are protected by the loopback binding, not by this form. If you ever run TermFlow with Expose on local network turned on, the real credential the backend enforces is the bearer auth token shown in Settings → Connections — not the monitor's client ID. For the full auth model, read /core-concepts/local-api-and-auth.

Localhost-oriented tool

Terminal Monitor was built and wired for local use, where the backend is open on loopback. Treat it as a convenience for the same machine (or a trusted, locally-tunneled connection). Do not rely on its built-in login as a security boundary. If you need to reach TermFlow across a real network, configure exposure and the auth token deliberately in /settings/connections-and-network.

Next steps​