ChatGPT Remote Commander

Cross-platform Windows + Linux MCP server for controlled remote project and machine access from ChatGPT through OpenAI Secure MCP Tunnel.

Giving this repository to ChatGPT for installation? Start with START_HERE.md. It is the single current source of truth for Standard/Full mode selection, install/update, Secure MCP Tunnel, persistent enrollment, ChatGPT custom app creation, Plugin packaging/install, icon use, real tool testing, autostart, stop/start, and FINAL PASS. For ChatGPT Work/Codex orchestration, also use WORK_SETUP.md.

Setup guides in 10 languages: English · فارسی · العربية · Türkçe · Español · Français · Deutsch · Русский · 简体中文 · 日本語

Documentation index · Current release: v0.9.12 · Project status · Development roadmap

Persistent startup

Three deployment patterns are supported: one ChatGPT account -> multiple computers, multiple ChatGPT accounts -> one computer, and multiple concurrent chats -> the same computer. Each computer runs its own MCP server; each account uses its own Secure MCP Tunnel profile; concurrent chat mutations on the same path are serialized to reduce write races.

After the one-time tunnel enrollment, you do not need to re-enter the Tunnel ID, local MCP address, health port, or Runtime API key after each login.

Windows persistent startup

.\enable-autostart.ps1 -Profile chatgpt-remote-commander

For an existing profile, this only asks for the Runtime API key once. It is stored with Windows DPAPI for the current user. An HKCU logon supervisor then starts/restarts the MCP server and every enrolled tunnel profile automatically.

Linux persistent startup

./enable-autostart-linux.sh --profile "$(hostname)"

The Linux helper registers a systemd user service when available, otherwise falls back to crontab. Runtime keys are stored outside the repository in a user-only chmod 600 credential file.

Related MCP server: MCP ChatGPT Full PC Dev

One-command Windows install

Paste this into PowerShell for a standard safe-by-default install (it installs missing Git/Node.js/PowerShell 7 with winget, downloads and verifies the official OpenAI tunnel client, runs tests/audit, and starts the local MCP server):

& ([scriptblock]::Create((irm 'https://github.com/GOD13emad/ChatGPTRemoteCommander/releases/latest/download/install.ps1'))) -InstallPrerequisites -StartServer

For trusted machines that need full filesystem/shell/process control, add -PowerMode:

& ([scriptblock]::Create((irm 'https://github.com/GOD13emad/ChatGPTRemoteCommander/releases/latest/download/install.ps1'))) -InstallPrerequisites -PowerMode -StartServer

The same command is also the update command. On Windows v0.3.4+, the installer first detects an already-active installation from the registered supervisor and updates that Git checkout in place. Otherwise, new source code is installed under %LOCALAPPDATA%\\ChatGPTRemoteCommander\\app, while persistent state such as credentials/ and downloads/ stays one level above. -StartServer upgrades a running v0.3 MCP to the newly installed version when needed. The installer never embeds your OpenAI Runtime API key. After creating a Secure MCP Tunnel, run enable-autostart.ps1 once to enroll the account and enable zero-reentry startup.

One-command Linux install

curl -fsSL --connect-timeout 15 --max-time 180 https://github.com/GOD13emad/ChatGPTRemoteCommander/releases/latest/download/install.sh | bash -s -- --install-prerequisites --start-server

For Power Mode, add --power-mode. Linux amd64 and arm64 are supported by the installer when an official OpenAI tunnel-client artifact is available.

Features

From v0.9.11, Remote Commander is ChatGPT-first and no longer provisions or launches Codex. Full Power does not grant model-delegation authority. Legacy provider=codex runner configuration is migrated fail-closed, the Commander-private Codex CLI is retired when safe, and direct or script-mediated Codex launches through Commander are blocked. If ChatGPT believes Work/Codex would materially help, it must first ask the user to choose between Move to Work/Codex and Continue in this chat with Remote Commander; continuing in chat is the default. A Work/Codex choice is an external handoff, not a Commander-side Codex launch. In v0.8.35, durable input requests let an enrolled project ask for a decision and resume from an explicit answer without resetting its budgets or changing its acceptance criteria.

The opt-in project execution engine, introduced in v0.8.34, adds bounded planner proposals, journaled execution, durable budgets, pause/cancel controls, fresh observations after restart and independent evidence-bound finalization. It is disabled unless explicitly configured and does not automatically enroll existing workflows. See the development roadmap for remaining capabilities and comparative qualification.

Optional adaptive planning and proposal teams add journaled prerequisite insertion, parallel worker advice, one coordinating executor and persistent provider-call budgets. v0.8.36 adds opt-in bounded artifact workers whose receipt-bound output can enter the project only through the normal journaled coordinator path. Acceptance criteria and execution authority remain immutable within a run. v0.8.37 hardens that boundary with exact delegated-step binding, canonical contained imports, end-to-end bounded 64 KiB artifact envelopes, and qualified fail-closed Codex CLI 0.156.1 diagnostics.

• Loopback-only MCP server by default (127.0.0.1:47831)

• Configurable allowed filesystem roots

• Directory listing and UTF-8 text reads

• Text writes with automatic backup and optional SHA-256 precondition

• Allowlisted direct executable execution without a shell wrapper

• Cross-platform Power Mode shell: PowerShell 7 on Windows, Bash-compatible shell on Linux

• JSONL audit log and recoverable file mutation backups

• Multi-account / multi-device Secure MCP Tunnel workflow

• Concurrent-chat path locking for mutating operations

• Windows and Linux persistent supervisors

Background browser — zero-interference web automation

v0.9.3 carries the hardened background-browser and durable-command layers forward with transport-deadline/response-budget hardening. Windows and Linux hosts with Chromium/Chrome use owned headless Chromium over CDP; Linux hosts without Chromium can use an existing Firefox + geckodriver WebDriver backend. Both paths use Commander-owned persistent or isolated profiles and remain background-first. It does not move the user's mouse, change foreground focus, type into the user's browser window, reuse the user's normal browser profile, or expose cookies/password-store contents.

Long-running command work is also background-first: operation_start returns a durable operation ID quickly, operation_status polls bounded state, operation_result returns bounded tails plus evidence metadata, and operation_cancel stops only the exact Commander-owned operation. Stable request IDs make lost acknowledgements idempotent and uncertain effects are never blindly replayed.\n\nThe intended order for web work is: background first → approval only when genuinely required → temporary same-profile foreground interaction → return to background. If the background page encounters MFA, WebAuthn, CAPTCHA, or a site that rejects background operation, browser_foreground_requirement returns an explicit approval boundary instead of seizing the desktop. After approval, browser_foreground_begin temporarily exposes the same Commander-owned profile visibly; after the minimum GUI step, browser_foreground_end returns that same session to headless background operation. Existing user-browser saved passwords are never extracted or copied. See Background browser and foreground approval.

This path is deterministic local browser automation and does not require Codex. From v0.9.11, Codex is not a Commander Project Engine provider and Commander never launches it.

GUI Control — Windows and GNOME/Wayland Linux

Remote Commander exposes built-in GUI Control on Windows and, from v0.8.21, GNOME/Wayland Linux. The MCP returns screenshots as image content and exposes bounded mouse, keyboard, window-focus and coordination tools. Zero-interference is invariant: observe-only is the default, and foreground mutation requires an explicit current user request plus a fresh single-use frame.

Safe visual-control loop:

gui_status
→ gui_session_begin
→ gui_screenshot(lease)
→ one gui_* action(lease + single-use frame)
→ gui_screenshot(lease)
→ verify visible result
→ gui_session_end

A frame is short-lived and single-use. A second chat cannot take the active desktop lease. GUI actions are never considered successful merely because input was submitted; a fresh screenshot must verify the visible result.

On Windows, enable it on a trusted checkout with:

.\install.ps1 -PowerMode -GuiControl -StartServer -SkipTunnelClient

After enabling, refresh/re-scan the ChatGPT custom app tools. The owner can stop GUI input locally at any time by holding Escape or creating var\GUI_STOP; the assistant must not remove that stop file remotely.

Limits remain explicit: Windows Secure Desktop/UAC prompts, the lock screen, anti-cheat/protected-input paths, software that rejects synthetic input, and high-speed real-time gameplay are not bypassed. Different trust levels also require separate OS sessions/authorization; multiple tunnel profiles alone are not security isolation.

Requirements

• Windows 10/11 with PowerShell 7, or a modern Linux distribution

• Node.js 22+

• Git

• OpenAI Secure MCP Tunnel client and a configured ChatGPT custom plugin/app

Manual/developer start (optional)

Normal users should follow START_HERE.md and the latest Release installer. For source-level development only:

1. Clone the repository.

2. Review config.json; %USERPROFILE% is expanded at runtime.

3. Run npm run check.

4. Run npm test; expected result: SMOKE_PASS.

5. Start the MCP server with npm start.

6. Verify http://127.0.0.1:47831/health.

The MCP endpoint is http://127.0.0.1:47831/mcp.

Connect ChatGPT

Follow START_HERE.md for the current end-to-end flow. Create an OpenAI Secure MCP Tunnel and Runtime API key, then run the persistent enrollment entry point:

pwsh.exe -NoProfile -File .\connect-chatgpt.ps1

On Windows v0.5.0+, connect-chatgpt.ps1 is the persistent enrollment entry point: it reuses an existing DPAPI-protected credential when available and leaves the background supervisor as the single owner of managed tunnel profiles.

In ChatGPT, create a custom MCP app with Connection = Tunnel, select the tunnel, use None / No authentication for this server, run Scan Tools, review permissions, and create the app. See START_HERE.md for the plan/workspace requirements and FINAL PASS checklist.

For Plugin packaging, icons, app binding, and private/workspace distribution, see docs/PLUGIN_SETUP.md and plugin-template. For ChatGPT Work/Codex, WORK_SETUP.md includes @plugin-creator plus self-contained latest-Release one-command app-bound installers for Windows/Linux. They accept either the underlying App ID or the plugin_... technical identifier shown by ChatGPT and automatically fetch the Release Plugin template when no checkout is present.

Tools

Legacy-safe tools: system_status, list_directory, read_text, write_text, run_project_command. Power Mode can also expose the direct-session background browser tools (browser_status, session begin/renew/end, navigate, snapshot, screenshot, fill, click, wait, foreground-requirement coordination, and explicit same-profile foreground begin/end). These browser tools are not part of autonomous workflow execution. Power Mode adds power_status, file_info, read_file, write_file, create_directory, copy_path, move_path, delete_path, search_files, run_shell, system_info, list_processes, kill_process, and persistent terminal tools (start_terminal, read_terminal, send_terminal, stop_terminal).

Security

Filesystem containment is enforced, but command execution is not an OS sandbox. An allowlisted executable or project script may itself access resources beyond the configured roots. Treat command execution as privileged. See SECURITY.md and the point-in-time SECURITY_AUDIT.md.

Validation

v0.8.24 hardens the Linux GNOME/Wayland GUI lifecycle: unchanged extension bytes are not replaced, changed active extensions are orderly disabled before atomic replacement and re-enabled afterward, and enabled-but-inactive state gets a bounded same-session recovery attempt. Runtime /var/ files are ignored so operational logs/state do not make the control checkout appear dirty.

v0.8.23 fixes stable-channel release discovery: both platforms now prefer GitHub's published releases/latest redirect and use the Releases API only as fallback. Raw Git tags are never treated as stable releases, so tagged-but-unpublished candidates cannot be auto-promoted.

v0.8.22 hardens the zero-downtime route invariant: an unresolved previous generation must be safely retired before any new cutover, and the router switch itself refuses to overwrite route.previous. Windows deferred maintenance also checks persistent terminals before every old-backend stop path. v0.8.21 adds guarded GNOME/Wayland GUI control on Linux and makes the zero-interference rule machine-readable across config, capability migration and runtime status. Linux install/update synchronizes the per-user GNOME extension without forcing logout/reboot; on GNOME 46 a newly introduced extension may remain unavailable until the next normal desktop session, and that limitation is reported rather than bypassed. Published stable-version discovery now uses GitHub Release authority, and scheduler status distinguishes automatic recovery/readiness from the intentionally absent model/agent execution runner.

v0.8.20 prevents updates from orphaning persistent terminal control: automatic promotion is deferred before route cutover when the active backend owns a Remote Commander interactive terminal, and any already-draining previous backend is also protected before every stop path on Windows and Linux. This follows the same general design principle as persistent/reconnectable terminal managers and graceful endpoint draining: preserve the live session owner until it can be safely retired. v0.8.19 closes a maintenance-loop failure found by the GUI/chess stress test. Release cleanup is now decoupled from supervisor restart: locked superseded releases produce explicit cleanup-pending evidence while the healthy supervisor/tunnel remain untouched. Behavioral Windows regressions cover both successful cleanup and an intentionally locked release, and platform contracts require cleanup-only paths on Windows and Linux to contain no supervisor recycle.

v0.8.18 closes the Windows drain-lifecycle failure found during live v0.8.15 promotion. Long-lived staged backends no longer inherit the updater's piped MCP stdio handles; stale drain recovery is evidence-based rather than version-based; persistent terminals block automatic retirement; successful drains atomically clear route.previous; and runtime server version is required to match package/plugin release metadata. Behavioral Windows regressions cover stdio detach, stale-drain policy and route retirement.

v0.8.17 fixes a live Linux auto-update lock inheritance defect: the promoted backend and stable router now close the updater lock descriptor before becoming long-lived processes, preventing a completed update from permanently blocking future updates with AUTO_UPDATE_ALREADY_RUNNING.\n\nv0.8.16 hardens Linux lifecycle and release packaging: the supervisor now boots the installer-managed portable Node runtime under systemd/crontab, Linux scripts are Git-tracked executable, disable cleanup covers routed backend/router ownership, and tunnel-client downloads use bounded timeouts. This closes the live Ubuntu auto-update stall and the earlier mode-only control tracked dirty installer failure.\n\nv0.8.15 fixes a release-test harness flake discovered by exercising the packaged Full Power installer from an exact tag. Stable-router tests no longer send loopback test traffic through Node Fetch, whose browser-compatible blocked-port list can reject otherwise valid OS-assigned free ports such as 5060. The tests now use node:http, the same local transport family being exercised. Router/product runtime behavior is unchanged. The corrected suite passed 10 consecutive focused runs before full release validation.

v0.8.14 closes candidate-validation lifecycle gaps found while installing the immutable v0.8.12 release. Candidate processes are ownership-tracked immediately after spawn and cleaned on pre-cutover failure, preventing orphan listeners and locked workflow-shadow stores. Unattended Windows update validation no longer calls the shared interactive gui_status helper; it uses the existing native no-input self-test plus candidate system_status GUI backend/policy evidence, so update checks do not contend for or seize the user's desktop. v0.8.14 keeps all v0.8.13 supervisor continuity protections and adds a checksum-manifested installer bundle.

v0.8.13 adds fail-closed supervisor liveness and canonical-listener continuity on top of v0.8.12 monotonic updates, v0.8.11 drain-accounting and v0.8.10 zero-interference desktop authority. A routed backend cannot be force-recycled after one transient health miss: recovery requires three consecutive misses, readable router activity, zero in-flight work, and a final health/activity re-check. A healthy canonical router is also retained when only its loaded source hash is stale, avoiding an intentional update-time listener gap.

v0.8.12 makes stable automatic updates monotonic on both Windows and Linux: an unattended updater will not replace a running newer build with an older GitHub Latest release. Explicit forced/exact-ref operations remain available for deliberate testing or rollback. This closes the live sequencing failure observed while an unpublished v0.8.10/v0.8.11 candidate was newer than the public stable release.

v0.8.11 fixes a stable-router lifecycle edge case observed during the v0.8.10 blue/green cutover: when an MCP client disconnected while the backend response still existed, the proxy could leave the old backend permanently counted as in-flight even after the tool action had completed. The router now unpipes a closed downstream response and drains the upstream response to its real completion without cancelling or replaying the operation. A production-shaped regression failed before the fix and passes afterward.

v0.8.10 adds a zero-interference desktop contract: GUI sessions are observe-only by default, and every mouse/keyboard/scroll/focus mutation requires a separate takeover lease carrying an explicit-current-user authorization basis. Full Power no longer implies permission to seize the foreground desktop. Headless/filesystem/shell/API paths remain preferred when the user has not explicitly requested interactive desktop control. The server enforces the session mode before native input, while the Plugin/Work contracts forbid inferring takeover permission from history, workflow memory, or screen content. Durable workflow execution also refuses takeover acquisition and GUI mutations, so resumed/background project state cannot become desktop-input authority.

v0.8.9 retains the v0.8.8 router source-activation hardening and the v0.8.7 persistent GUI performance/deferred-drain work. Unattended Windows updates no longer run the interactive focus/click/type GUI E2E, because Windows intentionally restricts background SetForegroundWindow requests and an updater must not steal the user's desktop. Automatic candidates instead run the native no-input self-test and then prove the candidate GUI backend with the candidate MCP hardware self-test; the full interactive GUI E2E remains mandatory on the exact clean release commit. Explicit Full Power remains an all-on authority class, durable workflows remain crash/restart/update-resumable, and unknown or mutating work is never blindly replayed or force-killed.

Each isolated account can use a distinct loopback MCP port, config, audit log, runtime marker and private workflow database; secondary profiles default to Standard Mode with GUI/shell/full-filesystem disabled. Workflow actions use intent-before-effect journaling, evidence checkpoints and explicit uncertain-outcome reconciliation with no automatic replay. Use configure-durable-workflows.ps1 for the primary profile and configure-profile-instance.ps1 -Profile <name> (or connect-chatgpt-account.ps1 -Profile <name> -Isolate) for additional accounts. This is a local application boundary, not an OS sandbox: use separate Windows users/VMs for principals with different OS-level trust. See docs/DURABLE_WORKFLOWS_R1.md and docs/PROFILE_ISOLATION_R1.md.

v0.6.5 is an integrity hotfix over v0.6.4: SHA-256 write preconditions now fail closed when the target is missing or malformed, and interrupted moves preserve the only complete promoted copy plus explicit recovery evidence instead of risking data loss. v0.6.4 retained the v0.6.3 diagnostics/test-isolation and v0.6.2 Power Mode/GUI/runtime hardening, and added bounded Linux network operations so external-download failures cannot hang indefinitely. Legacy 2025 clients remain supported, while MCP 2026-07-28 clients receive stateless discovery/routing, required tools/list cache hints, strict protocol-header validation, closed-schema tool inputs, and tool-level isError failures for known-tool validation/runtime errors. The release gate includes a dependency-free real-server conformance test and was additionally exercised against the official @modelcontextprotocol/client@2.0.0 in legacy, modern-auto, and modern-pinned modes. Linux installer and Plugin downloads use explicit connection/total deadlines; failures return nonzero instead of waiting without a bound. Persistent audit logs are serialized and bounded/rotated by default. npm run doctor -- --expected-device <name> performs a loopback-only read-only health/version/device/tool-catalog drift check against the active server. Use npm run check, npm test, npm run audit, and on Windows npm run test:gui-native before releases.

License

MIT — see LICENSE.

Power Mode security model

Power Mode is an explicit Full-Control mode for trusted machines. The runtime automatically prefers config.local.json when present; this file is gitignored. The public config.json remains safe-by-default with Power Mode disabled.

On this machine, Power Mode can enable full filesystem access, direct PowerShell execution, process control, binary file I/O, recursive search, recoverable delete, and persistent terminal sessions. Existing files are backed up before Power Mode overwrite/move/delete operations. In explicit Full Power, permanent delete is enabled unless filesystem.permanent_delete is explicitly disabled in the persisted capability profile.

Explicit Full Power does not retain a hidden Commander shell-pattern denylist: shell capability is unrestricted unless shell.unrestricted or shell.execute is explicitly opted out. Runtime ownership checks, protected-process checks, operation journaling and OS permissions still apply. Full Power is intentionally privileged and is not an OS sandbox; expose it only to trusted accounts.

FORBIDDEN: This conversation does not support developer MCPs is a ChatGPT conversation-surface gate that occurs before requests reach this server; server code cannot bypass it. Use a fresh MCP-capable chat when that platform gate appears.

Local private configuration

Copy the public configuration to config.local.json, enable only the Power Mode capabilities you want, and keep that file private. config.local.json, audit logs, backups, Runtime API keys, and tunnel credentials must never be committed.

Multiple ChatGPT accounts on one PC

One MCP server can serve multiple authorized ChatGPT accounts. Each account gets its own Secure MCP Tunnel profile. Health ports are auto-selected; no manual IP/port management is required.

Enroll another Windows account once:

.\enable-autostart.ps1 -Profile friend-pro

Enroll another Linux account once:

./enable-autostart-linux.sh --profile friend-pro

Each account must use its own tunnel and Runtime API key. The supervisor automatically starts every enrolled profile that points to this local MCP. For one account controlling multiple computers, repeat the installation/enrollment on each computer with a distinct tunnel so each device appears separately in ChatGPT.

v0.8.25 fixes Windows multi-account update isolation: a drain or persistent terminal owned by one ChatGPT profile defers only that profile, while independently healthy profiles can promote without terminating the blocked profile's workload.

v0.8.26 adds Windows terminal-keeper lifecycle handling: long-running persistent-terminal workloads can survive successive zero-downtime upgrades without occupying the single route previous slot forever, while cleanup and reaping remain evidence-gated.

v0.8.27 closes the stale-router-accounting edge case: when a previous Windows backend has a live persistent terminal but reports zero active/queued operations, idle/unleased GUI state, no unexpected socket owners, and no non-terminal descendant workload, the updater may detach that backend from route.previous while keeping the terminal subtree alive in the retained-backend registry.

v0.8.31 keeps isolated/custom Windows installer validation from mutating live routing when -NoStartServer is used. Canonical live installs retain candidate-first delegation, while custom existing checkouts update in place only.