Loop 0.5.0 · 2026-10-31
文档对应最新 npm 发布版本，保留英文原文。
Remote Connection Settings
Settings → Remote access controls an experimental private Microsoft Dev Tunnel hosted by the computer's Web process. The section is available in English and Chinese. Other settings and the local chat interface remain usable while connecting.
Usage
Follow the four compact vertical steps. Each step has a small empty circle until complete, then a green check; thicker vertical separators leave a gap before and after each circle. Action icons sit immediately to the left of the step title. Hover shows the full action label even when the button is disabled, and each button has the same accessible name. Disabled actions remain unavailable. Actions unlock as their prerequisites complete:
- Install Dev Tunnels CLI downloads and verifies the official CLI or verifies the existing installation.
- Sign in opens Microsoft sign-in in the computer's system browser. A system credential prompt can appear first; the progress track tooltip and accessible status ask for that approval before browser sign-in.
- Connect Tunnel starts hosting using the CLI account authorized through Sign in. Step 3 keeps one plug button: Connect Tunnel uses diagonal, rounded plug halves with visible prongs and a gap. After connection, the title and button change to Disconnect Tunnel with the halves joined along a diagonal seam. Both icons use the current theme color and contain no embedded text. The plug button is disabled while connecting or disconnecting; no extra Stop / cancel button appears. A host authorization failure is reported for an explicit retry.
- Paired devices displays the pairing QR code automatically after connection, then shows desktop approval requests and paired-device revocation.
Uninstall Dev Tunnels CLI replaces the first step title and its action tooltip after installation. The uninstall icon sits to the left of the title. The title stays Uninstall during removal and returns to Install Dev Tunnels CLI only after removal succeeds. Clicking Uninstall immediately shows the same full shimmering progress track to the right of its title and a loading ring in Step 1, continuing while the backend removes the CLI. No percentage, Pause, Stop or separate status caption appears; localized uninstall guidance stays in the tooltip and accessible status. Completion, removal failure or an unconfirmed request removes the track. The track follows the shared theme, forced-color and reduced-motion behavior. It is disabled during status checks, downloads (including paused downloads), sign-in, uninstalling and hosting. Uninstall removes only the currently managed executable, preserves Microsoft credentials and other CLI installations, resets the completion checks and restores Install. Removal failures retain the installed state and allow retry; starting uninstall clears the remembered sign-in even if removal later fails.
Every entry into this section checks installation and reads the remembered sign-in and current host state, even when a previous status is cached. During this check, step markers show loading rings instead of completion checks. An active action similarly replaces its step marker with a loading ring, without a check or cross. The rings follow the current theme and respect reduced motion. Previously completed steps show a red cross when a later check or operation fails; untouched incomplete steps keep an empty circle. A failed status request marks cached completed steps as check failures, without claiming which underlying service failed. Retry shows loading rings instead of crosses; a successful check restores confirmed completion marks. Installation failures, explicit reauthorization failures and unexpected exit of a connected tunnel retain their step failure in the current backend process until recovery. Intentional Stop, Sign out and Uninstall reset the affected steps without adding crosses. Setup actions are disabled until the entry check succeeds; failed checks offer Retry. Checking never installs the CLI, opens sign-in or starts/stops hosting.
No application IDs, scopes or terminal commands are required. Unsupported operating systems or CPU architectures show an explanation and disable setup actions. Hover over the heading's info button to see Microsoft's license terms and privacy statement links. The tooltip opens to the right of the button, or above it when horizontal space is limited, keeping the steps below clear. Keyboard focus or clicking the button also opens this tooltip; Tab reaches its links and Escape dismisses it.
Independent row sizing and 12px gaps keep step spacing compact. Warnings and errors appear to the right of the action icon and title on the same row; wrapped messages expand only their own step. Empty detail areas are hidden, and vertical separators retain clear gaps around the circles. Starting, finishing or canceling a download keeps the following steps in place. Installing reveals a compact progress bar immediately to the right of Install Dev Tunnels CLI on the same line. The row reads: installation label, progress track, percentage, Pause / Resume, then Stop and delete download. No download size or status caption appears below the track. The track shrinks to fit the available space and long step labels truncate with their full text available on hover. Pausing preserves the partial file and percentage, stops progress animations and releases the download request. Resume requests the remaining bytes; if the source does not support ranges, it restarts from zero. Stop deletes the unfinished file; the next installation starts fresh. Pause survives switching Settings sections within the running Web process, but does not resume across process restarts. Known download totals drive its filled length and percentage; the remaining track stays hollow. A highlight sweeps left to right within the filled portion. Before the total is known, an indeterminate segment shows activity without inventing a percentage. The colors follow Light, Dark and System themes, and reduced-motion preferences disable the sweep and transitions. Unknown totals show an em dash in the percentage slot rather than an invented percentage. Download, pause and installation details remain available in the track tooltip and accessible status. Once the transfer finishes, the tooltip and accessible status change to Verifying and installing… (localized in Chinese); Pause / Resume disappears, the percentage slot shows an em dash and the full track keeps shimmering while verification and installation run. The empty Pause / Resume slot stays reserved to the right of the percentage so the track and Stop button do not shift. Stop / cancel remains on the right. The first marker keeps loading until verification and installation succeed; only then does it show a green check and unlock Sign in. No extra step is added. The bar disappears after completion, cancellation or failure. Sign-in and connection checks keep their own step active while verifying an installed CLI, without displaying progress in the installation step. If that check discovers a missing or invalid executable, automatic reinstallation displays the bar in the first step. Sign-in shows the same progress track inline beside its label, filled to full width with the shared shimmer animation. It shows no visible guidance, percentage, Pause or Stop controls; the full fill indicates activity, not completed authorization, so no numeric percentage is reported to assistive technology. The credential/browser guidance stays available in its tooltip and accessible status. Theme, forced-color and reduced-motion behavior match installation, and the track disappears on success, failure or timeout. Connecting shows the same full shimmering track immediately to the right of Connect Tunnel, starting when the action is requested and continuing while the backend is connecting. It replaces the visible Connecting… caption, shows no percentage or cancellation controls, and retains the localized status in its tooltip and screen-reader announcement. The track disappears on connection, failure or cancellation. Other progress appears within its corresponding step. The sign-in step has no Stop / cancel icon while authorization is in progress; it waits for success, failure or the three-minute deadline. Download cancellation remains available; tunnel connection and disconnection use only the plug button.
Connected status is shown by the completed Step 3 marker and Disconnect Tunnel title and action. The settings screen hides the service's HTTPS address and the redundant Tunnel connected caption. Remote clients must complete device pairing before accessing chats; desktop configuration remains local. PWA installation is not yet implemented.
Disconnect Tunnel closes hosting and clears the connection check while keeping completed installation and sign-in checks. During shutdown, Step 3 shows its loading ring, disabled Disconnect Tunnel action and the same full shimmering progress track to the right of the title. The track appears as soon as disconnect is requested and stays visible while the backend is stopping, without a visible Stopping… caption, percentage or extra controls. Localized shutdown guidance remains in the track tooltip and screen-reader status. Completion or failure removes the track. The same presentation applies when Sign out first disconnects the tunnel; only after shutdown succeeds does progress move to the account step. Sign out replaces the Step 2 title and action tooltip after successful sign-in and is also available while connected. The title and disabled action remain Sign out during tunnel shutdown and account sign-out, then return to Sign in when sign-out finishes. It first stops the tunnel with only Step 3 loading; Step 2 keeps its completed marker until stopping succeeds. Then Step 3 becomes incomplete and Step 2 shows a loading ring and the full shimmering account progress track while signing out. When the tunnel is already disconnected, Step 2 shows its loading ring and Sign out progress track immediately on click, including while waiting for the command response. Account sign-out uses the same full shimmering track beside the label, without a percentage or extra controls; localized guidance stays in the tooltip and accessible status. Completion, account failure or an unconfirmed request removes the account track. A stop failure stays in Step 3 and preserves sign-in without invoking logout; an account-stage failure appears in Step 2. Sign out clears the sign-in step and uses the official CLI's shared account store for the current OS user, so it can sign other Dev Tunnels CLI uses out too. It does not sign the Microsoft browser session out. After a successful connection, Loop also remembers that the tunnel should stay enabled. A backend restart starts a fresh connection with the Step 3 loading ring and progress track, then shows Disconnect Tunnel after CLI readiness and stable cloud connection verification. During connection or automatic recovery, Disconnect Tunnel remains available to cancel hosting. It reuses the saved persistent tunnel and port so the address remains stable; occupied ports or missing cloud resources report failure instead of silently changing it. The initial migration from temporary hosting creates a new address and requires pairing once there. A tunnel can expire after thirty days without activity; service activity extends that window. Disconnect, sign-out, reauthorization, uninstall or a missing/invalid CLI clears this preference; normal shutdown preserves it. Startup reconnect requires the verified CLI and remembered sign-in, never downloads or launches browser login, and can require system credential-store approval. Initial restore failure appears in the responsible step for manual retry without claiming success. After an established host exits or cloud checks twice confirm disconnection, Loop shows Step 3 connection progress and retries the same tunnel up to six times with bounded backoff. Cloud API errors alone preserve a working host. Stop or sign-out cancels recovery; exhausted retries report the connection error for manual retry. The last successful Sign in survives backend restarts, so Connect becomes available after the installation check. Loop stores only a versioned boolean at <dataRoot>/web-ui/remote-access/sign-in.json; credentials remain in the CLI account store. A separate versioned enabled boolean at <dataRoot>/web-ui/remote-access/connection.json stores only the reconnect preference, without credentials or addresses. Failed preference writes appear in Step 3; disconnect still closes hosting, but the preference must be cleared by retrying after storage permissions are fixed. The marker is cleared before reauthorization, sign-out or uninstall, and when the managed executable is missing or invalid. Missing, unreadable or invalid state starts unconfirmed. If the marker cannot be saved, the operation shows a translated error and does not complete. Failed reauthorization or cancellation before CLI success leaves it unconfirmed. Stop, shutdown and ordinary tunnel failures preserve the remembered sign-in. This is a remembered result, not proof that credentials are still valid: external CLI logout, Keychain changes or revoked service access are not detected by opening Settings. If connection reports an authorization problem, use Sign out and Sign in to reauthorize. The CLI can reuse its own saved credentials. The saved tunnel identity and ingress port keep the address stable across reconnects.
State and Errors
The frontend uses the local control API, requests a fresh check on mount, and polls the in-memory state every 1.5 seconds afterward without restarting checks or flashing loading rings. A failed status request stops automatic polling until a manual Retry succeeds; window focus and network reconnection do not retry failed status checks. During active installation, sign-in, sign-out, connection or stopping, entry checks use the operation's current state without competing with the CLI. Query cancellation prevents an old status response from replacing a command response. The remembered sign-in result is not an independent check of credentials or current service authorization; host status reflects CLI readiness and exit notifications, not an independent network health probe.
Status distinguishes off, preparing/downloading, verifying and installing, uninstalling, browser sign-in, sign-out, connecting, connected, stopping and failure. Displayed errors use translated fixed codes, never raw CLI or identity responses. Download/save failures omit the explanatory alert and leave the install action available for retry; integrity failures retain their alert. Installation, uninstall, sign-in and connection errors appear to the right of their own step’s action icon and title, with a red warning icon followed by translated text. Wrapped lines retain the same message alignment. In-progress messages below the heading align with the step title. Unsupported-platform guidance appears as a yellow warning in Step 1. Unconfirmed command requests show a yellow warning in the step where the action was requested; only section-wide status request failures remain below the steps with Retry. The backend’s errorStep identifies the failed operation even when a connection request first installs the CLI or signs in. Sign-in and connection errors explain the next action. Network-command failures tell the user to refresh status before trying again.
Opening this section and automatic status requests never invoke CLI account commands or read Keychain credentials. Explicit sign-in, sign-out and tunnel operations can trigger a macOS Keychain authorization dialog for the CLI credential item. This is an OS credential-store prompt, not a Microsoft browser sign-in or installation prompt. It requests the login keychain password, which is usually the macOS account password. The CLI can wait inside this credential read before opening a browser, so no browser window does not by itself mean that the login command was not started. Complete the macOS prompt manually; if canceled, wait for the sign-in failure or timeout before retrying. Approving once may require approval on later CLI invocations; Always Allow changes the keychain access permission for the requesting executable. Loop does not enter passwords or change those permissions automatically.
The frontend does not receive or persist Microsoft credentials or host tokens in JavaScript storage. The local control cookie is HttpOnly and SameSite=Strict. Remote clients enter through the pairing gate; settings and project administration are available only on the computer.
Device Pairing
Step 4 → Paired devices automatically generates a pairing QR code once Step 3 is connected. The fourth marker shows a green check while at least one device has valid pairing authorization, including while another QR code is generated. Each paired device also shows a green check and its localized authorization expiry date. If all remaining devices have expired, Step 4 shows a red cross; individual expired devices retain their red cross even when another device is valid. A newly unpaired list keeps an empty marker. Scan the QR code with the phone. The brief “Scan with your phone.” guidance appears to the right of Paired devices; the QR image below has no pairing link. The paired-device list sits to the right of the QR image, with a maximum height of 208px matching the code; additional devices scroll vertically inside the list. Pending approval requests remain above this row, and the list uses the full row when no QR image is available. The invitation expires after five minutes and can be used once. Its URL uses Step 3’s public tunnel origin plus a one-use pairing secret in the fragment; the bare tunnel address alone cannot pair a device. Ordinary status polling does not replace the code. The single-arrow Refresh pairing code icon immediately left of Paired devices replaces the invitation and QR code on demand, including while a code is valid, without changing the tunnel URL. While this settings section remains open, an expired code is automatically replaced if the tunnel is connected and no pairing request awaits a decision. Failed generation, including an already-expired response, stops automatic renewal and leaves the icon available for manual retry. Refresh is disabled while disconnected, generating, processing a device action or awaiting a pairing decision. A new tunnel connection generates a fresh code and discards late results from the old connection. While a device request is pending, the used QR code is hidden; after the request is resolved, a fresh invitation becomes available automatically. The tunnel remains private: Microsoft service authorization may be required before the phone reaches Loop.
Enter a device name on the phone and select Request access. Compare its six-digit code with the pending device on the computer. Select Approve only when the codes match and the request is expected; Decline rejects it. Approval grants access to all registered projects and chats, prompt attachments and Agent commands under the session's existing permissions, including permission changes and tool approval. It is not a read-only or per-project grant.
The phone receives a standalone pairing page with the device-name form already in HTML. Its small script applies the saved/browser language and theme, removes the invitation fragment from browser history, enables submission and checks existing authorization in parallel. Before removal it saves the unsubmitted invitation only in same-origin, same-tab sessionStorage, with a five-minute limit from capture. Reload restores it without extending that deadline; a fresh scan replaces it. Successful submission or authorization clears it. Storage failure leaves the initial scan usable but disables refresh recovery. Server-side invitation expiry and one-use validation remain authoritative, and this storage never contains approved device credentials. A fresh QR invitation displays the form immediately, without waiting for React, full application translations or the authorization round trip. Ordinary refresh starts with a theme-aware Loop loading screen and keeps the entire pairing card hidden while checking authorization and downloading chats; authorized devices enter chats without a device-name form flash. A browser with no pairing cookie shows “This browser is not paired” and guidance to scan the current QR invitation, without claiming expiry or requiring a QR replacement. A plain tunnel URL in another browser or an incognito window cannot reuse the original browser’s authorization. Expired requests retain expiry guidance, and unavailable checks offer Retry. A pending authorization check cannot replace a pairing request already submitted. Pairing requests display the comparison code and poll for desktop approval; failed requests offer Retry, and rejected or expired requests require a new invitation. Network requests time out after ten seconds.
Only an authorized device downloads the React chat entry and shell, in parallel. Existing authorized devices open chats after the background check; newly approved devices exchange their cookie and recheck authorization first. The React gate consumes that check once from memory, avoiding another blocking round trip while it remains fresh for fifteen seconds; periodic checks and explicit authorization invalidation remain active. Settings loads when opened. Math rendering, its styles and code highlighting load only when message content needs them; ordinary Markdown appears immediately. Opening chats has a loading caption and failed downloads offer Retry. The phone waits without loading projects, conversations or other business data. Approval sets a Secure HttpOnly cookie and opens the existing chat interface. The credential is never returned to JavaScript or saved in browser storage; a separate CSRF value exists only in memory. Requests and invitations disappear on disconnect or backend restart.
Revoke access removes a paired device and closes its active requests and streams. The phone returns to pairing when authorization is rechecked, including after an SSE failure, or within the fifteen-second periodic check. Unavailable authorization checks hide the chat UI and offer Retry. Conversation snapshots and query data are cleared on authorization loss; user-written drafts and uncertain-delivery records remain in that browser. Already downloaded content cannot be retracted. Previously accepted Agent work can continue on the computer after revocation.
Device access expires fourteen days after approval and is not renewed automatically. Expired devices remain visible with a red cross and a prompt to pair again. Remove device deletes an expired record; the next successful approval also prunes expired records. Removing every device returns Step 4 to its empty marker. Expiry never grants access, and QR invitation renewal does not extend device authorization. Cookies belong to the exact public hostname. Persistent tunnel reconnection and backend restart preserve that hostname, so the same browser can reuse unexpired device authorization. A changed data root or replacement address requires new pairing. Disconnect preserves the cloud tunnel; pending invitations and active streams are still invalidated. Embedded browsers and external browsers have separate cookie stores: opening an already paired page in another browser requires a fresh invitation and desktop approval there. The consumed QR invitation cannot transfer authorization between browsers. Normal top-level page navigation from another app or Microsoft sign-in is accepted; cross-site API requests remain blocked. Settings, project registration, archive/delete operations and provider/MCP/skill configuration remain local and their controls are hidden remotely. See mobile layout and installed app for touch controls, home-screen installation, static caching and update prompts.