The five layers to check
Checking in this order prevents a shell quoting bug from being confused with an OAuth problem - and vice versa.
Installation prerequisites
TerminaLink’s current local service is distributed as a Node.js package and requires Node.js 22 or newer. Setup installs the runtime into a per-user TerminaLink directory and configures a user-level startup mechanism for the host OS.
The machine needs outbound HTTPS/WebSocket connectivity to the configured relay. It does not need an inbound port forwarded from your router.
Pairing problems
Pairing has two sides: the local machine creates the request and the browser approval flow authorizes it. Verify that the device name/platform shown in the browser matches the machine you intended to pair. A pairing code that expires or never gets approved should be restarted instead of being worked around manually.
If the browser approval succeeds but the local service remains unpaired, check whether the local process can reach the relay’s pairing-status endpoint and whether local clock/network middleware is interfering with authentication.
401/403: distinguish user auth from device auth
A 401 from the public MCP endpoint means a different thing from a rejected device WebSocket. The first is about the ChatGPT/client-side access token; the second is about the paired machine credential.
For public MCP authorization, check issuer/audience/resource configuration and token expiry. For a device rejection, revoke/re-pair if necessary rather than copying old credentials between machines. The two credentials serve different trust relationships.
“Device offline”
If the relay says the device is offline, start locally. Is the machine awake? Is the TerminaLink user-level service running? Can the local service resolve and reach the relay? Does the local health endpoint respond on loopback? Has the device been revoked?
On Windows, inspect the user Startup launcher and local service log. On macOS, inspect the user LaunchAgent. On Linux, inspect the systemd --user unit and journal. Avoid fixing an offline local service by opening an inbound firewall port - the architecture is designed not to require one.
Commands that hang, time out, or produce too much output
Some commands are naturally long-running. Use a session-style start/read workflow instead of forcing them into a one-shot execution call. Interactive commands may also be waiting for stdin; a terminal session can receive input when the client explicitly sends it.
TerminaLink bounds individual command output and session history. Those limits do not prove complete protection from resource exhaustion. If the sandbox or selected network mode is unavailable, the operation is rejected. Check the dashboard security state and platform status before retrying.
Shell quoting differs across operating systems
Windows and POSIX shells do not parse quoting, environment variables, chaining, and paths the same way. A command copied from Bash may fail in PowerShell or cmd.exe; a Windows path can be interpreted as escape syntax in a Unix-style command.
When transport is healthy but a command fails, first check the selected workspace, sandbox capability, network policy, working directory, and shell. Avoid dumping environment variables, which can contain secrets. A sandbox rejection is not a reason to silently switch to full system access.
Fast diagnostic checklist
- Confirm Node.js version meets the local service requirement.
- Confirm the machine is paired to the intended relay.
- Confirm the local TerminaLink status/doctor command sees the device configuration.
- Confirm local MCP health on loopback.
- Confirm the local service has an active outbound relay connection.
- Confirm ChatGPT can authorize to the remote MCP endpoint.
- Run a harmless shell command such as printing the working directory.
- Only then debug project-specific commands, permissions, or quoting.
For architecture context, read how the local service works. For authorization reasoning, use the MCP security pillar.