Skip to content

docs(rfc): propose remote Computer Use for a connected Mac - #21981

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
unstablebrainiac:rfc-remote-computer-use
Oct 22, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
unstablebrainiac:rfc-remote-computer-use

Conversation

@unstablebrainiac

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record a design, for maintainers to accept or reject, that lets a gateway on a headless Linux host drive native apps on the Mac whose desktop app is connected to it.

The setup the docs recommend runs the gateway on a remote Linux host and the person on a Mac in Remote Tunnel mode. In that setup Computer Use cannot be turned on: Settings shows LINUX_REASON and no toggle, the spec gate never advertises the tools, and the apps the person wants driven are on the other machine anyway. Running a second gateway on the Mac works, but splits memory, crons and sessions across two crews.

Why it matters

Computer Use is unavailable to everyone on the recommended remote setup. The design touches the Computer Use security boundary (a remote party gains input synthesis on a laptop), so it needs a recorded decision before any code lands.

Not a goal

  • Implementing any of it. This PR adds the document and its index row only.
  • A Linux AT-SPI driver.
  • Windows executors, several Macs per gateway, or remote executors for a macOS or Windows gateway.
  • Gateway-to-gateway peers.

What changed (motivation → approach → change)

Adds docs/request-for-change/rfc-remote-computer-use.md (status draft, measured at 310ad48b5f) and its row in docs/request-for-change/README.md.

Decision What it means
Split below the chokepoint A RemoteExecutorBackend on the gateway forwards each backend method; keystone, policy, index, fingerprint, refusals and audit stay on the gateway
The Mac only dials out The desktop app pulls requests over the tunnel it already holds; no port opens on the Mac
Scoped credential New routes accept only an executor credential minted over SSH, never the internal secret, a cookie or a link token
Mac switch Off by default, bound to the remote host key and gateway installation id, and the key that holds against a compromised gateway
Mac re-checks every config-free floor On its own walk and its own handles: secure fields, the text scan, the Kiro Crew window, launch identity, capture suppression, pointer moves
One call, one attachment A per-call lease on an attachment generation; watchdogs on the Mac kill a stuck executor before the gateway admits a replacement

The approach reuses the browser panel's outbound-pull pattern and the existing backend swap seam rather than moving dispatch to the Mac, which would fork the audit, the operator policy and the second caller of dispatch_tool. Four phases follow, each with pass/fail exit criteria, starting with a probe of whether a desktop-app child inherits the app's macOS permission grants.

Backwards compatibility

Compatible: documentation only; no code, config or route changes.

Removes nothing: the diff adds one document and one index row.

Tests

N/A: documentation only. scripts/docs_lint.py passes.

Manual verification

Every claim about current code was checked against 310ad48b5f with git show and git grep. None of the cited files changed between that commit and this PR's base.

Related Issues

no linked issue: the RFC is the first artifact; implementation PRs will reference it.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@github-actions github-actions Bot added the fork Pull request from a fork (external contributor) label Oct 18, 2026
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 18, 2026
@github-actions

github-actions Bot commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 5cf9211d1a1dd843cd1ead45fbd48bb3323f0b49 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ⏭️ skipped

Revision 5cf9211d1a1dd843cd1ead45fbd48bb3323f0b49 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 5cf9211d1a1dd843cd1ead45fbd48bb3323f0b49 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

This adds only a draft RFC and its index row. It keeps Computer Use ungoverned, and the code seams it cites are on the base tree.

[DESIGN-REVIEWED] 5cf9211

Description read

[DESCRIPTION-READ] 2124eead96af0f29df680db57f47611ecac9f43077c2ce6c0bf30fccdaa759be

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 5cf9211d1a1dd843cd1ead45fbd48bb3323f0b49 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5cf9211

@github-actions

github-actions Bot commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 5cf9211d1a1dd843cd1ead45fbd48bb3323f0b49 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 5cf9211

@unstablebrainiac
unstablebrainiac force-pushed the rfc-remote-computer-use branch 5 times, most recently from 050285d to 2366de2 Compare October 19, 2026 01:17
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 19, 2026
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 19, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 19, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 19, 2026
@unstablebrainiac
unstablebrainiac force-pushed the rfc-remote-computer-use branch 2 times, most recently from 2b02c48 to a33f516 Compare October 19, 2026 05:19
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 19, 2026
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 21, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 21, 2026
@unstablebrainiac
unstablebrainiac force-pushed the rfc-remote-computer-use branch 2 times, most recently from 58209c3 to fcc3cb2 Compare October 21, 2026 14:03
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 21, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Oct 21, 2026
…Tunnel mode

A Linux gateway cannot drive desktop apps today, and in the recommended setup the apps live on the Mac the desktop app runs on. The RFC splits Computer Use at the backend seam: the chokepoint stays on the gateway, a Mac-side executor supervised by the desktop app runs the macOS driver and re-checks every floor that has no config key, and the app pulls requests over its existing tunnel with an SSH-minted, route-scoped credential.

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE -- reviewed 5cf9211.

This is docs only: a draft RFC plus its index row, with no code, config or route change. Approving it records the proposal; accepting the design remains a maintainer decision, as the Goal says. The security section is candid about the residual risks: the Mac switch is the only key against a compromised gateway, the typed-text scan is a pattern check, and the ssh localhost gap is the existing one. The symbols I spot-checked on current main exist where described.

One nit, non-blocking: _STRICT_INTERNAL_API_PATHS now lives in dashboard/server_internal_paths.py, not server.py.

All AI lanes are clean and checks are green; I read the document and CI and ran nothing.

— crew-pr-reviewer (r119)

@rubencu rubencu mentioned this pull request Oct 22, 2026
5 tasks done
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

@iamwhatever Confirmed. _STRICT_INTERNAL_API_PATHS was in server.py at the audit pin 310ad48b5f and moved to dashboard/server_internal_paths.py in #22867 on Oct 21. I'll correct the citation when the row is next re-verified against main.

@Jim-Kincaid-CSTG

Copy link
Copy Markdown

Use case from a headless Linux gateway on EC2. It has no inbound SSH port, so my Mac would reach it through an ssh-config Host entry whose ProxyCommand runs aws ssm start-session (AWS-StartSSHSession). Two things I'd like covered:

  1. Could Phase 3 include a host reached through a ProxyCommand like that? The tunnel keeper and token fetch already handle ProxyCommand (Desktop client-only remote mode cannot work unaided: no port-forward owner, plus a hardcoded ssh path and a recurrence of #9360's stdin hang in fetchRemoteToken #9380, Instance diagnostics report ssh_unreachable (false positive) when SSH uses a ProxyCommand and the gateway has no console — probe never closes the child's stdin #9360), but the latency and wake tests read as if they assume a direct SSH hop.

  2. Once the Mac's AWS SSO session expires, the ProxyCommand fails, and with BatchMode=yes nothing can prompt for a new login. So "wake and re-attach within one TTL" won't happen until I sign in again. no_executor is the right refusal, but it would help if the refusal or the app said the tunnel can't reconnect, so it doesn't look the same as a sleeping Mac.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants