Skip to main content

Troubleshooting

Concrete fixes for the problems you are most likely to hit in TermFlow 0.1.0 (Early access · pre-release) — port conflicts, agents that won't connect, LAN exposure, tmux, and where your files live. Each entry follows a problem → cause → fix shape.

First stop: the health dot

Almost every connection problem shows up first as the health status dot in Settings → Connections. Open it before anything else — the dot tells you whether the API and MCP servers are actually running.

The health status dot​

The dot next to your ports in Settings → Connections has four states:

DotMeaning
CheckingTermFlow is probing the port right now.
HealthyThe server is up and answering on that port.
OfflineNothing is answering — the server is stopped or failed to start.
ConflictThe port is already owned by another process (often a second TermFlow instance).

The two health endpoints, GET /health and GET /api/health, are always open (never gated), so you can use them to confirm reachability even after enabling LAN exposure.

Problem: a port is in use ("conflict")​

Symptom. The health dot reads conflict, or the server won't start on 42031 (API) / 42032 (MCP).

Cause. Another process already holds that port — most commonly a second copy of TermFlow, a tauri dev session using the dev ports (42051/42052), or an unrelated service that grabbed the number.

Fix.

  1. Open Settings → Connections.
  2. Change the API port and/or MCP port to a free value. Any port in the range 1024–65535 is allowed.
  3. Click Save & apply (restart). The servers relaunch on the new ports.
  4. Confirm the dot flips to healthy.
If you change the MCP port, update your agent

Your agent config points at a specific MCP URL (default http://127.0.0.1:42032/mcp). If you move the MCP port, regenerate the config from the in-app Connect an AI agent modal so the URL matches — see the next section.

Problem: an agent won't connect to the MCP server​

Symptom. Your MCP client (Claude Code, Codex CLI, Gemini CLI, or another) reports the auto-terminal server as unreachable, times out, or shows fewer tools than expected.

Work through the causes in order:

Cause 1 — the MCP server isn't running. Check the health dot (above). If it's offline, use Stop/Start in Settings → Connections to start the MCP server, or Save & apply (restart).

Cause 2 — the URL is wrong. The MCP endpoint is a streamable-HTTP server and the /mcp path is required. The default is:

http://127.0.0.1:42032/mcp

A missing /mcp suffix, the wrong port, or localhost vs 127.0.0.1 mismatches all fail silently in some clients.

Cause 3 — you copied a stale tk init config. The tk CLI scaffolds a .mcp.json, but that generated file is stale: it uses a placeholder stdio path, the wrong server key (open-terminal instead of auto-terminal), and lists only five tools instead of the full set. Use tk init for the .agent-comms/ scaffolding only — not for MCP configuration.

An honest note: The single source of truth for agent config is the in-app Connect modal (Settings → Connections → "Connect an AI agent"). It generates paste-ready config for Claude Code, Codex CLI, and Gemini CLI with the correct server key, URL, and headers for your current ports. Always prefer it over hand-written or tk-generated config.

Cause 4 — the client isn't fully MCP-capable. Claude Code, Codex CLI, and Gemini CLI get first-class, copy-paste configs. Other MCP clients (for example Cursor, Goose, or aider) work too because they speak MCP — point them at the same http://127.0.0.1:42032/mcp endpoint as a generic streamable-HTTP server. aider additionally needs an MCP wrapper.

See Connect an agent → Overview for the per-client walkthroughs.

Problem: requests are rejected after enabling "Expose on network"​

Symptom. Everything worked on localhost, but as soon as you turn on Expose on local network your agent or scripts start getting 401 Unauthorized.

Cause. This is by design. In the default localhost-only mode, the servers bind to 127.0.0.1 and every endpoint is unauthenticated — that's safe precisely because nothing off your machine can reach it. The moment you expose on the LAN, TermFlow binds to 0.0.0.0 and enforces the bearer token on every request.

Fix.

  1. Open Settings → Connections and reveal/copy the auth token (a 64-hex value generated on first run).

  2. Send it as an Authorization: Bearer <token> header on every HTTP/MCP request. In the Connect modal's generated config, this is the Authorization header — it is only required in exposed mode.

  3. For WebSocket connections, browsers can't set headers, so pass the token as a query parameter instead:

    ws://<host>:42031/ws?token=<token>

  4. If you suspect the token leaked, click Rotate in Settings → Connections. Rotation takes effect immediately with no server restart, and existing in-app connections survive.

The auth token is the real credential

The token shown in Settings → Connections is the credential the gate actually checks. It is the value to put in your headers — read more in Local API and auth.1

Problem: tmux features aren't available​

Symptom. Content doesn't reflow when you resize a tmux-backed terminal, or tmux-aware behavior seems disabled.

Cause. The tmux backend (used for content reflow on resize) requires tmux to be installed and discoverable on the host. On Windows this generally means running inside WSL, where tmux is available.

Fix.

  1. Confirm availability. TermFlow reports it at:

    GET http://127.0.0.1:42031/api/system/tmux-status

  2. If tmux is missing, install it in your environment (on Windows, install it inside your WSL distribution). TermFlow falls back gracefully when tmux isn't present, so terminals still work — they just don't get tmux-driven reflow.

See tmux backend for what the backend does and when it's used.

Where config, data, and the auth token live​

TermFlow keeps its files in your operating system's standard application folders. The config (including your auth token, ports, and preferences) lives in the OS app-config directory; the command-history database lives in the OS app-data directory:

OSConfig base directoryData base directory
Windows%APPDATA%%APPDATA%
macOS~/Library/Application Support~/Library/Application Support
Linux~/.config~/.local/share

TermFlow stores its files in an application subfolder under these base directories. On first run it generates the auth token and writes default settings there.

Rendering glitches

For font, WebGL, or drawing artifacts inside a terminal, right-click the pane and use Reset Rendering, toggle WebGL, or open Diagnostics from the context menu before digging into config.

An honest note: TermFlow is early-access software (0.1.0). If a problem isn't covered here, the most reliable recovery steps are: restart the servers via Save & apply (restart) in Settings → Connections, and re-generate your agent config from the in-app Connect modal so the URL, port, and token all match. Download builds and release notes live at termflow.app/download and termflow.app/changelog.

Next steps​

Footnotes​

  1. TermFlow also exposes a POST /api/auth/token route that mints a JWT, but the auth gate does not check that JWT — it is legacy monitor-compat scaffolding. Do not use it to authenticate API calls; use the config auth token above. ↩