What the local service is
The TerminaLink local service is a small Node.js background process responsible for local MCP startup, device authentication, outbound connectivity, local security enforcement, and process/session lifecycle.
There is no need to run a second language model on the development machine. ChatGPT remains the reasoning surface; the local service is the execution bridge.
The local service boot sequence
- Load device configuration. Read the paired device identity and relay address from the per-user TerminaLink data directory.
- Start local MCP. Bind a Streamable HTTP MCP endpoint to
127.0.0.1and generate an ephemeral bearer token for that local process. - Connect outward. Open the authenticated device connection to the configured relay. An HTTPS relay results in secure WebSocket transport.
- Advertise readiness. The relay knows the paired device is online and can route MCP requests for the authenticated user.
- Enforce the local policy. Requests pass through local MCP and the security runtime. Protected project operations require the selected workspace and native sandbox; structured observation and explicit full system access use separate paths.
Why the local MCP server still exists
It might seem simpler for the remote relay to talk directly to a shell function inside the WebSocket handler. Keeping a real local MCP boundary has advantages: the tool contract stays explicit, local authentication remains independent from device authentication, and the terminal runtime can be exercised and tested as an MCP server rather than as a custom hidden protocol.
The loopback endpoint is an internal composition boundary, not a LAN service. That makes it easier to keep the remote transport narrow.
One-shot commands and long-running terminal sessions
A useful remote terminal needs more than “run this command and wait.” Development processes can stay alive for minutes or hours: a dev server, test watcher, build, package install, database migration, or log stream.
TerminaLink therefore separates one-shot execution from process sessions. terminal_start creates a session, terminal_read reads incremental output, terminal_write can send input to the process, and terminal_stop terminates it. Session output/history is bounded rather than allowed to grow forever.
This design also lets a client poll or stream progress without pretending every command is a synchronous request.
How the local service stays available on Windows, macOS, and Linux
TerminaLink installs as a user-level background service rather than a system-wide privileged daemon. The mechanism is platform-specific:
systemd --user serviceUser-level startup keeps the local service in the account of the person who paired the machine. The local policy adds workspace sandboxing for normal commands. full system access uses that account's permissions only after explicit approval.
What happens when something goes offline
The architecture has several independent failure points: ChatGPT-to-relay authorization, relay availability, device connectivity, the local MCP process, and the child shell process. Treating them separately makes troubleshooting much faster.
If the development machine sleeps or the local service is stopped, the relay cannot manufacture a terminal session; the machine is offline. If the outbound connection drops, the local service reconnects rather than opening an inbound listener. If a long-running process exits, its session state should report that independently from the local service’s own connectivity.
For a layer-by-layer diagnostic flow, use the remote MCP setup and troubleshooting guide.
Where the local-service pattern fits
The pattern is useful whenever the machine you want to control is private, behind NAT, or simply not something you want to publish as a general-purpose server. A mini PC, workstation, build box, home-lab server, or dedicated development machine can all use the same topology.
The tradeoff is that the relay becomes part of the trusted path and the local machine must stay online. For some organizations a conventional VPN or SSH bastion may be the right answer. For a ChatGPT-native tool workflow, an authenticated MCP bridge can be simpler because the AI client sees typed tools instead of an unconstrained network tunnel.