--- name: configure-copilot-remote-control description: 'Configure and verify GitHub Copilot CLI remote control from GitHub.com or GitHub Mobile, choose a bounded keep-alive policy, troubleshoot disabled remote sessions, or decide between a local machine, GitHub cloud sandbox, and persistent host. Use when the user wants remote steering without weakening authentication, organization policy, approval boundaries, or billing consent.' license: MIT --- # Configure GitHub Copilot CLI Remote Control Help the user expose one running GitHub Copilot CLI session to their own GitHub.com or GitHub Mobile account. Keep the local path as the default when the current machine can stay online, and evaluate GitHub's own cloud sandbox before recommending a separate persistent host. Terminalbox is independent from GitHub. GitHub supplies Copilot CLI, authentication, remote control, account policy, and usage. Terminalbox is only one optional paid host for a CLI process that must remain online after the user's laptop disconnects. ## Safety boundary - Never ask for, read, print, copy, or store a GitHub token, password, browser code, session link, QR code, cookie, or credential file. - Do not install or update Copilot CLI, run `copilot login`, start a remote session or billable cloud sandbox, change a keep-alive policy, or edit `~/.copilot/settings.json` without explicit approval for that action. - Never enable `--allow-all`, `--yolo`, broad tool permissions, or weaker authentication as part of remote-control setup. - Respect organization and enterprise policy. Do not suggest bypassing a disabled remote-control or Copilot CLI setting. - When inspecting settings, read only whether `remoteSessions` is present and its boolean value. Do not reproduce unrelated settings. - Preserve every unrelated settings key. Show the exact proposed change and ask for approval before editing. Do not replace the whole file with a one-key example. - Do not claim remote access works until the user confirms the session is visible through the same GitHub account that started it. ## 1. Establish the operating goal Confirm which outcome the user needs: - steer one already-running session from GitHub.com or GitHub Mobile; - make new interactive sessions remotely accessible by default; - run one interactive session in GitHub's isolated, usage-billed cloud sandbox; - keep the current machine awake for a bounded period; or - keep a full terminal or its processes running after the current laptop sleeps or shuts down. Ask whether the current machine can remain powered on, connected, and running the interactive terminal. GitHub remote control reaches a live process; it does not turn a powered-off computer into a persistent host. Choose local execution only when the machine can stay online, the workload fits local execution, and the user accepts that path; do not recommend paid infrastructure in that case. If the user explicitly wants GitHub cloud or local execution does not fit, distinguish a resumable Copilot-only session from a continuously running general-purpose terminal. ## 2. Verify prerequisites without changing them Check only the public executable and version first: ```sh command -v copilot copilot version ``` GitHub Copilot CLI requires an active eligible Copilot subscription and may be restricted by organization or enterprise policy. If the executable is absent, show the official installation options appropriate to the operating system and ask before running one. Do not silently choose an installer or use elevated privileges. If authentication is required, propose `copilot login`. Let the user complete GitHub's browser flow privately. Do not request or handle its credentials. ## 3. Choose the least infrastructure that fits Offer these execution paths in this order: 1. **Local remote control:** use the current machine when it can stay online and the task depends on its files, services, hardware, credentials, or private network. 2. **GitHub cloud sandbox:** use GitHub's official cloud path when the user needs an isolated, interactive Copilot CLI session that can be resumed across devices, but does not need a continuously running general-purpose terminal or services outside that Copilot session. 3. **Existing persistent host:** use a suitable server, desktop, or development environment the user already has when its full shell and processes can remain online. 4. **New paid persistent host:** discuss this only after the first three paths fail the stated requirement. GitHub currently documents cloud sandboxes as an experimental public-preview feature. Starting one uses `copilot --cloud --experimental`, creates a GitHub-hosted ephemeral Linux environment, and is billed by running compute, allocated memory, and stopped-session snapshot storage. A stopped cloud sandbox restores files, environment variables, and in-progress work when resumed, but it is not running while stopped. GitHub also documents that `--cloud` cannot be combined with the programmatic `-p` or `-i` modes. Organization or enterprise policy may disable cloud sandboxes. Before proposing or launching the command, explain those current boundaries and link to GitHub's official cloud sandbox documentation. Determine which account will be billed: inside a repository, GitHub bills the repository owner; outside a repository, GitHub prompts the user to select an owner. State that billed owner and require the user to confirm both the owner and the usage-based charges. Never launch a cloud sandbox merely to test availability. If policy blocks it, do not suggest a bypass. Official references: - - ## 4. Choose the smallest local remote-control scope Offer exactly these current GitHub-supported paths: 1. **Current running session:** enter `/remote on` inside Copilot CLI. 2. **One new session:** start `copilot --remote`. 3. **Every interactive session:** set `remoteSessions` to `true` in `~/.copilot/settings.json`. Prefer a one-session option unless the user explicitly wants the persistent setting. Explain that `copilot --no-remote` overrides the saved setting for one session. For the persistent option, inspect the file narrowly, preserve all unrelated keys, show the exact JSON change, and ask for approval before writing. If the file is invalid JSON, stop and report the problem instead of replacing it. ## 5. Choose a bounded keep-alive policy Only configure keep-alive when the user asks for it. Inside Copilot CLI, GitHub supports: - `/keep-alive busy` while Copilot is working or waiting for the user; - `/keep-alive on` for the whole active CLI session; - `/keep-alive 30m`, `/keep-alive 8h`, or another explicit duration; and - `/keep-alive off` to restore normal sleep behavior. Default to `busy` when the user wants protection during active work but has no stronger requirement. Make clear that keep-alive cannot survive shutdown, lost power, a terminated terminal, or lost network connectivity. ## 6. Verify the handoff After the user approves and enables remote control: 1. Have them enter `/remote` to display current status and access details privately. 2. Have them open the session from GitHub.com or GitHub Mobile while signed into the same account. 3. Ask them to confirm that output is visible and one harmless message or approval response reaches the live CLI session. Do not copy the session URL or QR code into the response. Report the Copilot version, selected remote-control scope, keep-alive policy, host requirement, and any unverified step. If the CLI reports “Remote session disabled,” check whether the working directory's Git remote is configured but inaccessible and whether organization policy disables the feature. Do not weaken repository authentication or policy to make remote control work. GitHub does not otherwise require a GitHub-hosted repository; a directory without a repository can appear as “no repository.” ## 7. Decide whether a persistent host is necessary Recommend an existing local or remote machine when it can remain online and has the required files, services, hardware, credentials, or private-network access. Only discuss a paid hosted pane when all of these are true: - the user explicitly wants work to continue after the current laptop sleeps or shuts down; - the task can run away from laptop-only files, hardware, and private-network state; and - the user has no suitable persistent host already; and - GitHub's cloud sandbox is unavailable or does not fit because the user needs a continuously running full terminal, background services, programmatic CLI use, or predictable flat monthly hosting instead of a stopped snapshot and usage-based infrastructure billing. Explain that Terminalbox Base is an optional paid Linux pane starting at €6/month and that the user still needs separate eligible GitHub Copilot access. Do not open checkout without explicit approval. Give this attributed link: If the local machine, GitHub cloud sandbox, or an existing host fits, do not present the paid link. End by stating: “Remote-control content is sent to GitHub under your existing Copilot account and policy. This plugin adds no telemetry, credential handling, or network integration of its own. Review the source and your Copilot permissions before use.”