Connection · MCP · connected-device

Connections

Golden Terminal connects an AI client to the computer that is online right now. The customer runtime is exposed as a live target named connected-device. Golden does not need a permanent machine inventory to make that connection useful: your AI conversation, project instructions or Canon can remember what the machine is for.

LIVEcurrent device, not inventory

MCPworks through the client connection

NO FALLBACKoffline means unavailable

CONTEXTnames live with your project

Quick answer: what am I connecting?

You are connecting your AI to the customer device that currently runs the Golden Terminal agent. In the AI tool layer that device appears as connected-device.

If the customer runtime is offline, Golden should report that it is unavailable. It must not silently run the command on the Golden server or on another machine.

Two separate connections are required: your AI client must have Golden MCP tools available, and your computer must have a running Golden Session or Agent. Golden account sign-in alone does not make either connection.

ChatGPT: add Golden as a custom MCP server

Golden Terminal is a custom MCP connection, not a public-directory app. Use ChatGPT on the web and check that your plan or workspace permits the Golden tools you need.

Open ChatGPT Plugins. Choose + → Add custom MCP server (or Apps → Create in the older interface). Do not search for Golden in the public directory.
Name it Golden Terminal, use https://mcp.goldenterminal.dev/client-mcp as the remote HTTPS MCP endpoint, and choose OAuth sign-in when prompted.
Complete the Golden authorization, create/install the custom plugin, and verify that its tools are discovered and enabled.
Start a new ChatGPT conversation. Select the installed Golden Terminal plugin with @ or the app picker for the message you want to execute. Merely typing its name does not activate missing tools.
Start the Golden runtime on your authorized computer using the Windows/macOS command below. Complete browser pairing and leave the terminal open.
Ask List my Golden Terminal targets. Only after the target is online, ask Check free disk space on connected-device. Do not change anything.

ChatGPT plan limitation: full custom MCP actions, including command execution, depend on ChatGPT plan and workspace permissions. Some individual plans permit only read/fetch tools. Golden cannot override a client that does not expose exec. Use a compatible MCP client with the required action support or an eligible ChatGPT workspace. Check OpenAI's current custom MCP availability.

ChatGPT says Golden's tools are unavailable

Check that the custom plugin is installed, authorized and selected for this message, and that its discovered actions include the tools you intend to use. Reopen a new chat after installation. If the tools are missing, troubleshoot the ChatGPT app connection or permissions before reinstalling your computer Agent.

ChatGPT can call Golden, but the device is offline

If Golden's targets tool responds with AGENT_UNAVAILABLE, the AI connection may be working while the local Session or Agent is not online. Start or reconnect the local runtime, complete pairing, and retry targets. Do not assume the Golden cloud should execute your commands instead.

How the connection works

Your Golden account identifies the connection

Use the public account and connection flow rather than passing server credentials through the chat.

The local agent comes online

The agent runs on the computer you want the AI to reach.

Your AI client connects through MCP

ChatGPT or another MCP-compatible client receives the Golden tool catalog for the live customer runtime.

The AI addresses connected-device

Commands and file operations are sent to the current customer device, inside its real operating-system boundary.

The result returns to the conversation

The model can use the result to continue the task, explain the state or propose the next action.

First connection: add Custom MCP, then connect a computer

Golden Terminal is not listed in the public ChatGPT plugin directory yet. Do not search the catalog. You must add it as a custom MCP server using the official URL.

In ChatGPT on the web, open Plugins → + → Add custom MCP server. Name it Golden Terminal.
For the HTTPS endpoint, paste https://mcp.goldenterminal.dev/client-mcp. Use Golden OAuth sign-in if requested, accept the risk notice, select Create as a plugin and install it.
On the computer you want to use, open its terminal (PowerShell on Windows, Terminal on macOS/Linux), then paste the correct Golden command below.
On Windows/macOS, Golden tries to open your browser. If it fails on Windows or macOS, use the temporary pairing link shown in PowerShell or Terminal; Golden keeps waiting for your confirmation. Sign in with your Golden account to confirm the connection. This is pairing. Keep the terminal window open (a foreground session).
Back in ChatGPT, select @Golden Terminal and try a harmless read-only first task. A successful tool result verifies the connection.

Take a look at connected-device and tell me what you can help with here. Only inspect and report; do not change anything.

Can't find Add custom MCP server? Your ChatGPT plan or workspace permissions may not support this action. Command/write tool availability also depends on the AI client's plan. For a step-by-step guide with copy buttons, visit Golden Terminal's connection setup. Use current commands, not old chat snippets or screenshots.

Never opened a terminal before?

A terminal is an app for typing computer commands. Windows already has PowerShell and macOS already has Terminal. You do not need to install a developer IDE. Open it on the computer you want Golden to access. This may be the same computer where ChatGPT is open.

Windows: open PowerShell

Press the Windows (Win) key on your keyboard, or click the Start button.
Type PowerShell and open Windows PowerShell or PowerShell. Do not choose Run as administrator for the first test.
Copy the Windows Golden command below, click in the PowerShell window, paste with Ctrl + V (or right-click) and press Enter.

macOS: open Terminal

Press ⌘ Command + Space to open Spotlight.
Type Terminal and press Return. Or use Finder → Applications → Utilities → Terminal.
Copy the macOS Golden command below, paste with ⌘ + V and press Return.

Linux desktop: open Terminal

Try Ctrl + Alt + T (available on many Linux desktops) or find Terminal in your Applications / Activities menu.
If you already have Node.js 22+, a user systemd session and a Golden connection code, copy the Linux command below, paste with Ctrl + Shift + V (or right-click) and press Enter.

Copy commands into the local PowerShell or Terminal window, not into ChatGPT. On Windows and macOS, a Golden sign-in page should open in your browser. Leave that terminal window open while your AI works. Headless Linux without a user systemd session is not covered by the current Linux installer.

Exact current installation paths

Golden currently has two different customer runtime models. Windows and macOS use foreground Session Mode for the preferred interactive first connection. Linux uses the separate persistent Agent path.

Platform	Current path	What persists
Windows	One PowerShell/CMD Session Mode command → browser pairing → `connected-device`	No Golden service, no Node.js requirement, session token stays in memory; terminal must remain open.
macOS	One Terminal Session Mode command → browser pairing → `connected-device`	No LaunchAgent in foreground mode, no Node.js requirement; terminal must remain open.
Linux	Official persistent Agent installer → issued Golden connection code → user systemd service → `connected-device`	Agent and connection code are stored for the user service. Node.js 22+ is currently required.

Windows · foreground Session Mode

powershell.exe -NoLogo -NoProfile -Command "irm 'https://mcp.goldenterminal.dev/golden-agent/session.ps1' | iex"

macOS · foreground Session Mode

curl -fsSL https://mcp.goldenterminal.dev/golden-agent/session.sh | sh

Linux · persistent Agent

curl -fsSL https://mcp.goldenterminal.dev/golden-agent/install.sh | sh

The Linux installer requires Node.js 22+ and an issued Golden connection code. Do not run the macOS session.sh on Linux. If you do not have a connection code, do not invent an installation method; use the current Golden account/support path.

What connected-device means

connected-device is a runtime target, not a permanent asset record. It represents the customer computer that is available through the active Golden agent.

Question	Meaning
Is this the Golden server?	No. Customer operations are sent to the connected customer runtime.
Is it permanent machine inventory?	No. The target represents the live runtime and is intentionally ephemeral.
What happens when the agent is offline?	The customer target becomes unavailable. The operation should fail closed instead of falling back elsewhere.
Where should I remember what this machine does?	Use the AI project, conversation context or Canon for durable names, roles and operating notes.

Remembering machines and roles

Golden Terminal does not need to turn every customer machine into a cloud inventory object. Give your AI enough durable context to understand the role of the connected device.

Current device role: office workstation Project: Golden Terminal Main repo: /path/to/golden-terminal Production server alias: amsterdam Rule: use the connected Mac only as the approved bridge; do not modify it unless the task explicitly requires that.

Keep stable project facts in Canon or project instructions. Keep temporary state, one-off logs and current incident details in the active conversation or a handoff note.

Do not put raw passwords, private keys or long-lived API tokens into Canon. See Golden Secrets / Secure Input.

Useful first prompts

Safe first tasks · read only

Check how much free disk space is available on connected-device. Do not change anything.

Show me the basic system information and hardware details for connected-device. Do not change anything.

Check which services are currently running on connected-device. Do not start or stop anything.

Find the largest files in my Downloads folder. Do not delete or move anything.

Check Docker status and summarize what is running. Do not start, stop or remove anything.

Inspect the current network state and tell me if you see obvious problems. Do not change anything.

When you are ready to change something

Inspect the problem first. Explain the smallest change you recommend and how you will verify it. Do not make the change until I confirm.

Use the existing SSH profile named production. Check service status only. Do not print private keys, tokens or credential files.

Read-only tasks are the best first proof that Golden is connected to the machine you intended. State-changing work should have a clear task boundary and a verification step.

Reconnect and offline states

If Golden reports the customer runtime as unavailable, diagnose the connection layer before repeating the work.

Confirm the intended computer is powered on and online.
Confirm the Golden agent is running on that computer.
If your AI says it has no Golden tools, check the ChatGPT Custom MCP plugin setup above; it is a client/tool-selection issue.
If a Golden tool returns AGENT_UNAVAILABLE, check the local Session or Agent and its browser pairing.
Confirm your AI client still has valid Golden OAuth and that the plugin is selected for this message.
Reconnect through the current account guide if authorization expired.
Run a harmless discovery call before retrying a state-changing command.

Do not assume a timed-out or disconnected state-changing operation failed. If the outcome is uncertain, inspect the target state before replaying the command.

FAQ

Does Golden remember every computer I have used?

The customer runtime is intentionally exposed as a live connected-device target rather than a permanent cloud machine inventory. Use project context or Canon to remember roles and names.

Can Golden run on the server if my computer is offline?

Customer operations must not silently fall back to the Golden server. An unavailable customer agent should be reported as unavailable.

Can I give the same machine a human name?

Yes. Put the human role in your project context: for example “office Mac”, “home workstation” or “build PC”. The AI can map that role to the current connected runtime.

Why does ChatGPT say it cannot call Golden after I typed @Golden?

Confirm you added Golden under Custom MCP, completed OAuth, installed the plugin and enabled its actions. Then select the app for your message. Client plan and workspace permissions may still restrict command execution.

Where are the current installation steps?

Use the public connection guide linked from this page. It should be treated as the current source instead of an old command copied from chat history.

Ready to continue?

Use the current connection guide, then return to Help whenever you need the next layer.

Connect Golden Back to Help Verified cases Articles