One-click Remote (GoodQA #1889)
Dark. Platform setting desktop.oneClickRemote (default off, per-org grammar like machines.enabled) and the desktop
app's agent switch. A trust-boundary hold: it stays off until the real-host acceptance run passes and Eric says yes.
This page states what the code guarantees and what is not yet proven.
Defensive purpose: a person deliberately lends narrowly bounded, revocable control of their OWN computer and OWN signed-in browser to a named agent they chose, while credentials cannot leave and they can stop it instantly.
The one click
On the desktop app's Remote control screen the button Enable remote for my agent opens ONE consent screen, pre-filled with
the owner-ruled defaults (Eric, 2026-10-06, D1): browser control of three named sites (goodqa.app, framebright.com,
gethawkeye.app) plus the QaTablet desktop tier, 4 hours, auto-expiring, files and shell off. Full Control is never
part of it: a person types a separate phrase in the app for that, and the server bundle refuses it in every spelling
(422 full_control_not_allowed). The person can instead pick, on purpose, Until I turn it off (no expiry); it is never the
default, is refused together with files/shell, and is always shown as an active session with a one-click revoke.
Pressing Allow creates ONE consent record and the matching grants in one transaction, then shows the always-on-top Agent in control - STOP bar, the red tray state and the Ctrl/Cmd+Shift+K hotkey.
Server (apps/api/src/modules/machines/remote-sessions)
| Route | What | Gate |
|---|---|---|
GET /v1/orgs/{orgId}/machines/remote-sessions/availability | 404 while the flag is off; else the consent defaults (the desktop shows the button only then) | flag, a signed-in person |
POST /v1/orgs/{orgId}/machines/remote-sessions | create the consent + grants (idempotent by clientRequestId) | flag, a signed-in person, recent sign-in |
GET /v1/orgs/{orgId}/machines/remote-sessions | the person's sessions | Machines |
GET /v1/orgs/{orgId}/machines/remote-sessions/{sessionId} | one session; an expired one is closed on read | Machines |
POST /v1/orgs/{orgId}/machines/remote-sessions/{sessionId}/stop | revoke EVERY grant in one call (atomic with its audit) | Machines; never needs the flag or a recent sign-in |
POST /v1/orgs/{orgId}/machines/remote-sessions/{sessionId}/renew | extend a timed session, never past 24 h from its start | flag |
PATCH /v1/orgs/{orgId}/machines/remote-sessions/{sessionId} | narrow it (bumps the generation); adding a site needs a separate confirm; anything wider needs a new consent | flag |
Enforcement stays where it already was: command admission reads the grants (revoked, not started, expired = refused), so a stop,
an expiry or the kill switch IS a grant revoke or expiry. A session carries a generation that rises with every consent and
every scope change. The tier grants are the existing ones: resting = screen, ui_tree, system (risky acts wait for the person);
qaTablet = those plus shell restricted to the adb command list (no typing on the computer, no files unless folders are
typed); files/shell is its own grant that always waits for the person. Origins must be exact HTTPS origins of named hosts and
may not be sign-in, bank, password-manager or mail sites.
The browser step is an interface: until the browser-wire lane lands the view says honestly browser.status = not_connected.
Kill switch and rollback
Write off to desktop.oneClickRemote: create, renew and change answer 404 and the paths leave the served OpenAPI document
(byte-identical to the base, pinned by machines-remote-sessions-flag-off.test.ts); live sessions are closed (revoked,
stopReason: kill_switch) at the next status read or machines sweep. Stop and status stay reachable.
What is NOT proven yet
See docs/design/oneclick-consent/REPORT.md: no real Windows or macOS host, no real Chrome profile, no real tray or hotkey
on those systems, the Go host does not yet check the local generation counter (the contract and a fake host are tested).
References
- API reference:
/v1/openapi.jsoncarries the seven operations while the flag is on;docs/openapi-all-features.jsonalways lists them as dark. - MCP tools: none. Machines work from a signed-in session only, never an API key or a user token; see the MCP tool list for what agents can do once granted.
- Runbook: One-click Remote operator runbook.