Connections & Network
Settings → Connections is where you control the two local servers that let AI agents and your own tooling drive TermFlow: the API server (REST + WebSocket) and the MCP server. This page explains every control on the panel — ports, network exposure, the access token, start/stop, and health status.
What this panel controls
TermFlow runs two long-lived local servers. Everything on this panel configures how they listen and who can reach them.
| Server | What it is | Default port (installed app) |
|---|---|---|
| API server | Axum HTTP REST + WebSocket, on one port | 42031 |
| MCP server | MCP sidecar (streamable HTTP) at /mcp | 42032 |
Both ports are user-overridable in the range 1024–65535. By default both bind to 127.0.0.1 (this machine only). A Refresh status button and a ● Production / ● Dev instance badge sit in the panel header — the badge tells you which build you're running, which matters because a development build listens on 42051 / 42052 instead of the production 42031 / 42032.
REST and the WebSocket share the API port — you'll see both http://localhost:42031 and ws://localhost:42031/ws listed on the API card. The MCP endpoint is separate: http://localhost:42032/mcp.
The panel at a glance
┌─ Connections ─────────────────────────── ● Production [Refresh status] ┐
│ External applications connect to TermFlow using these endpoints. │
│ │
│ ┌ API Server (REST + WebSocket) ─────────────────────────── ● healthy ┐│
│ │ http://localhost:42031 [copy] ││
│ │ ws://localhost:42031/ws [copy] ││
│ │ Port [ 42031 ] ││
│ └─────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌ MCP Server ────────────────────────────────────────────── ● healthy ┐│
│ │ http://localhost:42032/mcp [copy] ││
│ │ Port [ 42032 ] ││
│ └─────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌ Network access ──────────────────────────────────────── [⚠ exposed] ┐│
│ │ [x] Expose on local network ││
│ │ ││
│ │ ── the rows below appear only when the box is checked ── ││
│ │ Reachable on these interfaces (bound 0.0.0.0): ││
│ │ Ethernet Wi-Fi 192.168.1.24 [copy API] [copy MCP] ││
│ │ Access token (app-generated) ││
│ │ •••••••••••••••••••• [👁 reveal] [copy] [Rotate] ││
│ │ Connect an AI agent ⓘ ││
│ └─────────────────────────────────────────────────────────────────────┘│
│ │
│ [ Save & apply (restart) ] [ Stop ▾ ] [ Start ▾ ] │
└──────────────────────────────────────────────────────────────────────────┘
When Expose on local network is off (the default), the Network access box collapses to a single line — Bound to 127.0.0.1 (this machine only). with an inline Connect an AI agent link — and the per-interface IP list and token controls are hidden.
Ports
Each server card has a Port field. Type a value in 1024–65535 and it's flagged as unsaved:
Port [ 42041 ] ⚠ Unsaved — click "Save & apply (restart)" below to apply.
Port and exposure changes only take effect when you press Save & apply (restart) — this restarts the affected server(s) on the new configuration.
The usual reason is a clash with something else already listening on 42031 or 42032. If TermFlow detects that a port is answering but owned by a different process or instance, the card shows a conflict state (see Start, stop & health) and asks you to pick another port.
Expose on local network
By default TermFlow's servers are bound to 127.0.0.1, so only programs on the same machine can reach them. Turning on Expose on local network re-binds them to 0.0.0.0, making them reachable from other devices on your LAN. When enabled, the panel:
- stamps a ⚠ exposed badge on the Network access header,
- lists each network interface with its IP under "Reachable on these interfaces (bound 0.0.0.0)", with one-click copy API / copy MCP URLs per interface,
- reveals the access token controls (see below).
Once bound to 0.0.0.0, any device that can route to your machine can attempt to reach the API and MCP servers. Only enable this when you understand your network, and treat the access token as a secret. Leave it off unless you specifically need remote access (for example, driving TermFlow from another machine).
The access token
The access token (network.authToken) is a 64-hex string generated on first run and stored in TermFlow's config file. In the panel it's shown masked, with buttons to reveal (👁 / 🙈 toggle), copy, and Rotate. These controls live inside the Network access box and appear when exposure is enabled — because the token only matters once you're exposed.
Here is the honest, important part of TermFlow's security model:
The token is checked only when the server is exposed on the LAN. In the default localhost-only mode, every endpoint is unauthenticated — and that's safe because the servers are bound to 127.0.0.1, reachable only from your own machine. The moment you flip on Expose on local network, the token becomes a required bearer credential for every request.
- Bearer header:
Authorization: Bearer <token>on HTTP/MCP requests. - WebSocket: browsers can't set custom headers, so WS auth uses a
?token=<token>query parameter. - Always open:
GET /healthandGET /api/healthare exempt regardless of exposure.
Rotating the token
Rotate generates a new token and immediately invalidates the old one. TermFlow asks you to confirm first, warning that any external tools, agents, or MCP clients still using the old token will lose access until you update them with the new value. Rotation takes effect immediately — the servers keep running, so your in-app terminals and existing UI connections are unaffected. After rotating, copy the new value into your agent configs (or regenerate them from the Connect an AI agent modal).
An honest note: TermFlow also exposes a
POST /api/auth/tokenendpoint that mints a JWT. That JWT is not the credential the auth gate checks — do not use it to authenticate your API or MCP calls. The real, working credential is theauthTokenshown on this panel.
Start, stop & health
The action row at the bottom of the panel manages the running servers:
| Control | What it does |
|---|---|
| Save & apply (restart) | Writes port/exposure changes and restarts the affected server(s) to apply them. |
| Stop ▾ | Split button: Stop all, Stop API, or Stop MCP. |
| Start ▾ | Split button: Start all, Start API, or Start MCP. |
| Refresh status | Re-runs the health check for both cards on demand. |
Each server card carries a health dot that polls continuously. The four states:
| Dot | Tooltip | Meaning |
|---|---|---|
| checking | Checking… | A health poll is in flight (also the initial state on load). |
| healthy | Connected | The server answered on its port. |
| offline | Offline | Not reachable — the server is stopped or hasn't started. |
| conflict | Port in use by another instance | The port answered, but it's owned by a different process or TermFlow instance. |
When a card is in conflict, an inline alert appears beneath it: "⚠ Port 42031 is already in use by another instance. Choose a different port and click Save & apply." Change the port and re-apply to resolve it.
Connect an AI agent
The Connect an AI agent ⓘ link opens a modal that generates paste-ready configuration for connecting a client to the MCP server. It produces first-class, copy-paste configs for Claude Code, Codex CLI, and Gemini CLI (all pointing at http://127.0.0.1:42032/mcp with the server key auto-terminal), and generic guidance for any other MCP client that speaks streamable HTTP.
The modal is the recommended source of truth for agent setup — it already fills in your current MCP port, host, and token. For the full walkthrough of each client, see the pages below.
Next steps
- Connect an Agent — overview — pick your client and paste the generated config.
- Local API & auth — the deeper model behind the localhost-vs-exposed token behavior.