Repository navigation
Description
Status: approved by owner; implementation to follow as a separate PR.
Problem
The profile model has three accepted names (owner, desktop, observe) plus the refused legacy name sandbox, and the boundary between them is unclear.
The browser (@playwright/mcp) and the shell are both shell-equivalent. desktop blocks exec* and limits the browser to a 15-tool allowlist, but #45 and #46 established that it is still shell-equivalent through GUI control. The Oracle VM (PR #58) runs the browser under desktop, so the browser inherits the shell-equivalent trust level without an explicit decision. See also #45 (browser tier egress).
Decision (owner)
Two profiles only. The desktop profile is removed entirely.
- observe: exactly
sys_infoandscreenshot. No shell-class tool, no browser. - owner: the full local and upstream tool set, shell-equivalent. This includes the shell class and every
browser_*tool.
The browser is owner-level, not isolated. This applies to the current browser, which uses this computer's persistent profile and network. It does not rule out the isolated browser tier planned in tool-profiles.md / #45. That tier can be added later as a new profile or a proxy, once it has a real boundary (throwaway profile, egress block, or separate VM).
desktop is not an alias of owner
desktop is no longer a profile. A desktop value, whether requested by an attach call or stored in a persisted grant, resolves to observe. It never resolves to owner. This fails closed.
Why map instead of refuse like sandbox (#46): sandbox was never a granted profile, so refusing it loses nothing. desktop grants exist in the wild and sit in persisted state. A hard refusal would fail every existing attach call and would leave stored rows that cannot be served. Mapping to observe keeps the attach working, widens nothing, and makes the change visible to the granter.
Why not owner: today desktop blocks every exec* tool and excludes browser_evaluate, browser_run_code_unsafe, upload/PDF, and network inspection (ToolProfile.swift:84-106). An alias to owner would grant all of these, including arbitrary JavaScript in the logged-in browser profile.
Default profile is observe
When an attach request has no profile, both daemons use observe. This is the single default for Swift and Linux. Today Swift defaults to desktop (MCPHTTPEndpoint.swift:115) and Linux defaults to owner (poc/reverse-attach-linux/src/http.rs, handle_attach). Both change to observe.
Migration (breaking change)
This is a breaking change for anyone who used desktop for the browser. After it lands, that browser access is gone until an owner grant is issued. Nothing in the migration issues owner.
- Requested
desktop: the attach call succeeds with effective profileobserve. The response carriesprofile: observe,requested_profile: desktop, and awarningfield. The daemon log and an audit log entry record the mapping too, but the log is not the only signal. - Stored
desktopgrant: on resume (daemon start) the row is kept, its effective profile isobserve, and the row is not upgraded and not deleted.GET /attach(the attach list) andgrant.jsonshowprofile: observe,requested_profile: desktop, and a warning, so the granter sees it the next time they look at the list. - Re-enabling shell or browser access requires an explicit
ownergrant from the person who holds the machine. sandbox: unchanged from fix(profile): desktop (was sandbox) is shell-equivalent; add observe; document profiles #46. Persistedsandboxgrants are still dropped on resume, andsandboxrequests are still refused. Whether those drops should also keep the row and report it is not decided here.- Commit with
!. The release note has a migration section that states the mapping above. - Open a client companion issue (as fix(profile): desktop (was sandbox) is shell-equivalent; add observe; document profiles #46 did). Clients stop sending
desktop. Clients that want browser access requestownerexplicitly. - Use one rejection message on both platforms for unknown profiles:
400 profile must be one of [owner, observe].
Work
The list below comes from grep -rni desktop on a fresh clone of origin/main at f456d047823572acae7110447ad39f1f7f8dde6c. That gives 42 files. Each hit is first classified: a profile name changes, while a desktop-session or GUI wording stays unless it names the profile.
Swift core (Sources/InstanceMCPCore)
ToolProfile.swift(13 hits): removecase desktopanddesktopBrowserTools. KeepToolClassandlocalToolClass, because they enforce theobserveboundary.ownerincludes allbrowser_*tools.MCPHTTPEndpoint.swift(line 115): default profileobserve. Map a requesteddesktoptoobservewith a warning. Reject other unknown values with the 400 message above.AttachManager.swift(5 hits):resumekeeps a persisteddesktoprow, resolves its effective profile toobserve, and reports the warning. RemovedesktopInstructions.sandboxhandling is unchanged.Switchboard.swift(2 hits,instructions()): removedesktop.PermissionStatus.swift,Tools/OsascriptTool.swift,Tools/ScreenshotTool.swift(1 hit each): wording check, change only profile references.
Swift app (Sources/oab-instance-mcp)
main.swift(6 hits):--switchboard-profilehelp text and validation acceptownerandobserveonly.PermissionSetupWindowController.swift(2 hits),StatusItemController.swift(1 hit): removedesktop.
Swift tests (Tests/InstanceMCPCoreTests)
ProfileBoundaryTests.swift(12 hits),ReverseAttachTests.swift(11),SwitchboardTests.swift(6),UpstreamMCPTests.swift(5),GrantPersistenceTests.swift(3),ConformanceVectorTests.swift(1): update to two profiles and add the tests in the Tests section.
Linux (poc/reverse-attach-linux)
src/mcp.rs(17 hits): removeDESKTOP_BROWSER_TOOLSand everydesktopbranch intool_list,profile_is_shell_equivalent,local_tool_allowed,upstream_tool_allowed, andhandle_tool_call. KeepOBSERVE_TOOLSand the tool classification. Replace the hardcoded["owner", "desktop", "observe"]list (mcp.rs:518) with a single source constant.src/http.rs(line 579 message,handle_attachdefault): defaultobserve, same mapping and 400 message as Swift.src/attach/store.rs(1 hit,normalize_profile): a storeddesktoprow resolves toobservewith a warning and is kept.src/tools/input.rs(4),src/tools/screen.rs(1),src/tools/sysinfo.rs(1): wording check.src/platform/desktop.rs(13),src/platform/mod.rs(5),src/platform/linux/seat.rs(12),src/platform/linux/wlroots.rs(13): desktop-session wording. Change only if a line names the profile.smoke.sh(10 hits): add thedesktopmaps toobservewith warning check, and update the other profile assertions.pw-mcp.sh(1 hit),README.md(8 hits): two profiles.
Docs
README.md(17 hits),docs/tool-profiles.md(14 hits),docs/linux-setup.md(12 hits): two profiles,observedefault,desktopmapped toobserve.docs/adr/reverse-attach.md(4),docs/adr/linux-rust-port.md(4): add an ADR entry for this decision and the alternatives below. Update the existing profile text.docs/requirements/reverse-attach.md(1),docs/requirements/connect-closed-loop.md(1): two profiles.docs/releasing.md(1): release note migration section.poc/pw-mcp/README.md(1): browser runs underowner.
Scripts
scripts/install-linux.sh(8 hits),scripts/install-prebuilt.sh(1),scripts/pkg/postinstall(2),scripts/test-packaging.sh(2): default profile and profile wording.
Conformance (new vectors, see Tests)
conformance/profile_vectors.json(new),conformance/README.md(update the list of vectors).
Tests
Local tools (ProfileBoundaryTests and the Rust profile tests)
- Every local tool is checked under
observeand underowner. Underobserve, onlysys_infoandscreenshotare allowed. Underowner, every local tool is allowed. A new local tool with no classification fails the test.
Browser tools (new file, separate from ProfileBoundaryTests; Rust equivalent in the Linux test module)
- Against an upstream fixture that lists the full
browser_*tool set: underownerevery tool is allowed, none is skipped. Underobservenone is allowed. - A new upstream tool that is not in the fixture is denied under
observe. ownerreachesbashandbrowser_*through the realtools/callpath, not only through the allowlist function.
Call path
- A tool hidden from the profile, called directly through
tools/call, returns unknown tool (Swiftscoped(to:), Linuxhandle_tool_call).
Grants and attach
- A stored
desktopgrant resolves toobserve, emits a warning, the row is kept, andGET /attachandgrant.jsonreport the effective and requested profile. - An attach request with
desktopgetsobservewith a warning. It never getsowner. - An attach request with no profile gets
observe. - Unknown names (
browser,sandbox,OWNER) return the 400 message.
Shared conformance vectors (F6)
- Add
conformance/profile_vectors.jsonnext to the existingauth_vectors.jsonandreverse_attach_vectors.json. Each vector has: input profile, accepted or rejected, effective profile, warning required, persisted-grant behavior, local tools, upstream tools, and shell-equivalent. - Swift runs it in
ConformanceVectorTests, which the existingswift test --skip OsascriptToolTestsstep inci.ymlalready runs on macOS. - Linux runs it in
cargo test --release(ci.yml, "Unit + conformance tests"), with the same include pattern asauth.rs. - Edit a vector only when the change is intended on both sides.
- The upstream fixture in the vector is the full browser tool list, so both platforms check the same set.
- Known gap, not in scope:
OsascriptToolTestsis skipped in CI (ADR: sandbox adapter — backend-agnostic sandbox_* tools (OrbStack first; k3s / Lambda MicroVMs later) #1). The osascript path stays untested end to end.
Acceptance
On both macOS and Linux. Tools are grouped by class, not by name alone.
- Observe class (
{sys_info, screenshot}):observeserves exactly these two tools. It serves no shell-class tool and no upstream tool. - Shell class (macOS:
exec,exec_start,osascript,key,mouse; Linux:bash,key,mouse; any future tool classified as shell): served only byowner. Underobserveeach one is hidden and returns unknown tool on a direct call. - Browser class (every
browser_*upstream tool): served only byowner. Underobserveeach one is hidden and returns unknown tool on a direct call. - Unclassified tool: fails the test. A tool with no class is never served under
observe. ownerserves the full local tool set and the full upstream tool set.- A requested
desktopresolves toobservewith a warning, and never widens toowner. - A stored
desktopgrant is kept on resume, resolves toobserve, and is reported inGET /attachandgrant.json. - Unknown names (for example
browser,sandbox,OWNER) are rejected with400 profile must be one of [owner, observe]. - An attach request without a profile gets
observe. grant.jsonandGET /attachreport the effective profile and the requested profile.- Shared conformance vectors pass on both platforms in CI.
- Linux smoke test covers "
desktopmaps toobservewith a warning". - macOS
swift testand Linuxcargo test(with conformance) and smoke are green in CI.
Ordering
- Implement and test this issue. It lands before PR docs: Oracle Cloud reference architecture for instance-mcp #58 is finalised.
- Update PR docs: Oracle Cloud reference architecture for instance-mcp #58 (Oracle VM refarch) to describe two profiles only: profile table, tool counts, attach examples. No
desktopin the text. - Merge PR docs: Oracle Cloud reference architecture for instance-mcp #58 only after this issue is done, so
mainnever publishes deployment guidance that refers todesktop. If docs: Oracle Cloud reference architecture for instance-mcp #58 must merge first, mark it transitional and make this issue a hard gate for the same release. - This decision covers only the current shared-profile browser. The isolated browser tier planned in
tool-profiles.md/ Planned restricted tiers (isolated browser, typed app control, custom policies, VM): acceptance criteria #45 is not blocked. It can be added later as a new profile or as a proxy in front of the browser.
Alternatives considered
- Alias
desktoptoownerwith a warning. Rejected: silent widening of live and persisted grants. - Refuse
desktopwith a 400, likesandbox. Rejected: fails existing attach calls and leaves stored rows that cannot be served. Mapping toobservekeeps the attach working and fails closed. - Alias with explicit client-side opt-in. Rejected: adds a consent flow to keep a name that is going away. An explicit
ownergrant gives the same consent with less code. - Keep
desktopas a named preset (GUI plus restricted browser, no direct shell, no arbitrary JS). It reduces accidental misuse, but it keeps the three-name confusion this issue removes. Revisit as a custom policy if needed. - Build the isolated browser tier (Planned restricted tiers (isolated browser, typed app control, custom policies, VM): acceptance criteria #45) first, then collapse. Not required: the collapse is reversible, and the isolated tier can be added later as a subset of
owneror as a separate profile.
Related
- Planned restricted tiers (isolated browser, typed app control, custom policies, VM): acceptance criteria #45: browser tier egress
- fix(profile): desktop (was sandbox) is shell-equivalent; add observe; document profiles #46, fix(profile): classify every tool; boundary tests fail on unclassified ones #48:
sandboxrefusal and tool classification - PR docs: Oracle Cloud reference architecture for instance-mcp #58: Oracle VM refarch (must describe two profiles only before merge)
- ADR: sandbox adapter — backend-agnostic sandbox_* tools (OrbStack first; k3s / Lambda MicroVMs later) #1:
OsascriptToolTestsskipped in CI (known gap, not in scope)
Activity
chaodu-agent commentedon Oct 29, 2026
Important
CHANGES REQUESTED⚠️ - Two profiles is the right model, but the Migration section would silently widen existing
desktopgrants toowner. The issue needs a decided migration contract and tighter acceptance criteria before implementation starts.What This Issue Proposes
Collapse the tool profiles to
observe(sys_info,screenshot) andowner(everything, including allbrowser_*), and removedesktopor turn it into an alias ofowner. The goal is a profile model whose names match the real trust boundary: shell-equivalent or not.How It Would Work
ToolProfileand Linuxsrc/mcp.rsdropdesktopand its browser allowlists (desktopBrowserTools/DESKTOP_BROWSER_TOOLS).browser_*upstream tools move toowner.desktoprequests either fail or map toowner. The issue currently says both (see F1).observekeeps its current behavior, and thesandboxrefusal from fix(profile): desktop (was sandbox) is shell-equivalent; add observe; document profiles #46 stays as it is.Findings
sandboxprecedent without a stated reasondesktop->ownerwidens live and persisted grants, and a warning in the daemon log does not reach the granterToolProfile.swift:84-106,AttachManager.resume, Linuxstore::loadMCPHTTPEndpoint.swift:115,http.rs:557bash) and omitsmouse,key,osascript,exec*. It should be stated by tool classbrowser_*and call-path behavior need their own testsProfileBoundaryTests,mcp.rstestsdesktopmain!commit, or client companion planowneris the honest choiceFinding Details
🔴 F1: Decide the migration contract
Work says "remove
desktop, or make it an alias ofowner". Migration saysdesktopmust map toownerwith a warning. Only one of these can ship.The repository already made this decision once. #46/#48 changed
sandboxfrom an alias to a hard refusal (ToolProfile.swift:24: "The old namesandboxis not accepted"). Ifdesktopbecomes an alias, the issue should explain why that reasoning does not apply here.Requested change: Choose one option and record the reason:
desktopwith a 400 likesandbox, and drop storeddesktopgrants. This is the recommended option.desktoponly as a transitional alias that requires explicit client-side consent (see F2).🔴 F2: Aliasing
desktoptoownerwidens grants without consentToday
desktopblocks everyexec*tool (ToolProfile.swift:86). It allows only 15 browser tools, and the list explicitly excludesbrowser_evaluate,browser_run_code_unsafe, upload/PDF, and network inspection (ToolProfile.swift:96-106). Linux has the matching testdesktop_never_gets_arbitrary_javascript.An alias would give existing
desktopclients:exec/exec_start(macOS) orbash(Linux);The threat model already treats
desktopas shell-equivalent, so this is not a new privilege class. It does remove the guard against accidental misuse that the allowlist provides.The persisted-grant path is the most serious case. Swift
AttachManager.resumeand Linuxstore::loadboth normalize the stored profile. Linuxnormalize_profilealso feeds attach validation,local_tool_allowed, andupstream_tool_allowed, so changing that one function widens three paths at once. After a daemon upgrade and restart, a grant lent asdesktopwould come back asowner. A warning on stderr does not reach the person who granted it:POST /attachstill returns success.Requested change: Handle new requests and stored grants separately. Stored
desktopgrants must be dropped and re-granted, never upgraded in the background. If option (b) from F1 is chosen, the attach response must return the effective profile (owner) and the requested value (desktop), show a warning the user can see, and write an audit log entry.🔴 F3: Define the default profile
When the request has no profile, Swift
POST /attachdefaults todesktop(MCPHTTPEndpoint.swift:115) and Linux defaults toowner(http.rs:557). Oncedesktopis gone, the macOS default changes implicitly, and under an alias a bare attach would gainexec*and the full browser.Requested change: Set one explicit default on both platforms.
observeis the fail-closed choice.🟡 F4: State Acceptance by tool class
Acceptance says
observecannot reachbashorbrowser_*.bashis the Linux name. The macOS shell-class tools areexec,exec_start,osascript,key, andmouse.mouseandkeyare missing on both platforms.Requested change: Replace the wording with:
observeserves exactly{sys_info, screenshot}and no.shell-class tool, on both platforms;ownerserves the full local and upstream tool set;tools/callreturns unknown tool (Swiftscoped(to:), Linuxhandle_tool_call);sandbox,Desktop,browser, and others) are still rejected and never widen;grant.jsonandGET /attachreport the effective profile, not the requested alias;desktoprequests and for persisteddesktop/sandboxgrants is covered by tests.🟡 F5: Test coverage beyond local tools
ProfileBoundaryTestsand the LinuxLOCAL_TOOL_CLASSchecks cover local tools completely. Upstreambrowser_*tools are dynamic: the Linuxserved()helper excludes them, and the Swift browser test checks only a few hardcoded names.Requested change: Add tests against an upstream fixture:
ownergets all of it,observegets none of it, and an unknown new upstream tool is denied underobserve. Keep the "unclassified tool fails" behavior. Replace the hardcoded["owner", "desktop", "observe"]list in the Linux test (mcp.rs:518) with a single source constant, as Swift already does withallCases.🟡 F6: Shared conformance vectors
CI runs
swift teston macOS andcargo testplus conformance on Linux, but no shared vector defines profile -> tools. This change is a good time to add one, with fields for input profile, accepted/rejected, canonical profile, warning required, persisted-grant behavior, local tools, upstream tools, and shell-equivalence. Run it on both platforms, ideally with a mock upstream that serves the full browser tool list.Also note that
OsascriptToolTestsis skipped in CI (#1). The Swift profile boundary is covered, but the end-to-endosascriptpath is not.🟡 F7: Complete the Work list
The Work list names
ToolProfile.swift, three Linux symbols,ProfileBoundaryTests, anddocs/linux-setup.md. About 40 files onmainreferencedesktop, including:normalize_profile,upstream_tool_allowed,DESKTOP_BROWSER_TOOLS,OBSERVE_TOOLS,handle_tool_call;Switchboard.instructions(),AttachManager.desktopInstructions,--switchboard-profilehelp and validation inmain.swift,PermissionSetupWindowController,StatusItemController;GrantPersistenceTestsand others),scripts/install-*.sh, README,tool-profiles.md, ADRs, anddocs/requirements/*.If
desktopis refused, remove both browser allowlists rather than leaving dead code. Keep theToolClass/LOCAL_TOOL_CLASSmachinery, because it is what enforces theobserveboundary.🟡 F8: Treat this as a breaking change
Profile behavior changes for existing clients. Plan a
!commit, a release-note migration section, and a client companion issue, as #46 had with the client-side changes. Use the same rejection message on both platforms (for exampleprofile must be one of [owner, observe]), and add a smoke test that checksdesktopis rejected.🟡 F9: PR #58 ordering and #45
PR #58 (Oracle VM docs) uses
desktopthroughout its profile table, tool counts, and attach examples. If it merges first,mainwill publish deployment guidance that is about to become wrong, and people follow these docs to decide what to grant.Requested change: Decide the #59 contract first, then update #58 to the two-profile model before it merges. If #58 must merge first, mark it as transitional and make #59 a hard gate for the same release. Also add one sentence saying this decision covers only the current shared-profile browser, and that the isolated browser tier planned in
tool-profiles.md/ #45 can still be added later as a subset ofowner.🟢 F10: The core decision holds
The privilege structure is binary: shell-equivalent or not. #45 showed that a browser using the shared persistent profile and the host network can reach localhost, the tailnet,
file://, and logged-in services, so labeling itowneris honest. Collapsing profiles can be undone later. The migration semantics cannot, which is why F1-F3 block.Baseline Check
mainatf456d047823572acae7110447ad39f1f7f8dde6c, and PR docs: Oracle Cloud reference architecture for instance-mcp #58 atc52109a954c7c7cc772e40e1a2cfe74809031864owner,desktop,observe);desktopis documented as shell-equivalent (fix(profile): desktop (was sandbox) is shell-equivalent; add observe; document profiles #46); every local tool is classified and unclassified tools fail tests (fix(profile): classify every tool; boundary tests fail on unclassified ones #48);sandboxis refusedAlternatives the issue should address
The issue has no alternatives section. It should at least explain why it does not choose:
desktoplikesandbox(no alias).desktopas an explicitly named preset (GUI plus restricted browser, no direct shell, no arbitrary JS) on top of a two-level boundary. This fits the custom-policy item on the roadmap.5. Three Reasons We Might Not Need This Change
desktopis already documented as shell-equivalent. What remains is mostly naming and maintenance cleanup, not a new boundary.desktopreduces accidents. A confused or weak agent cannot run a shell orbrowser_evaluateby mistake, because those tools are not listed. After the collapse, any grant aboveobserveis fullowner, so the usual lend gets more exposure.observeadds churn. Deprecatingdesktopin docs and deleting it later is a cheaper path, though it keeps the three-name confusion this issue wants to remove.chaodu-agent commentedon Oct 29, 2026
Revised the issue body. Point by point:
desktopis not an alias ofowner" and Migration. Chose mappingdesktoptoobserve(fail closed), with the reason for not refusing likesandbox.desktop" and "Storeddesktopgrant". The row is kept, the effective profile isobserve, andGET /attachandgrant.jsonshow it. Re-enabling needs an explicitownergrant.observe" (one default for Swift and Linux, with both current defaults named).conformance/profile_vectors.json, run byswift testandcargo testin CI.origin/main(42 files), grouped by area.!commit, release note, client companion issue, and the 400 message.owner.docs: fix Oracle refarch 7.5 upgrade order and profile status
docs: Oracle Cloud reference architecture for instance-mcp (#58)
test(conformance): address review of wire fixtures and negatives (refs …
test(linux): smoke a bare attach end to end; fix the bash-profile line
chore: drop a duplicate smoke check; placeholder the README attach ex…
fix(linux): bare POST /attach defaults to observe, not owner (#86)
feat: audit file for desktop -> observe mappings (#59)
chore: bump to 0.9.0 (#95)