Skip to content

Epic: evaOS Mac Access v0.1 standalone menu-bar connector #698

Open
0 of 8 issues completed
Open
Epic: evaOS Mac Access v0.1 standalone menu-bar connector#698
0 of 8 issues completed
Labels
area:brokerevaOS broker/session/auth integrationarea:native-companionNative macOS companion boundaryarea:releasePackaging, signing, updater, rollbackarea:shellAionUi shell and navigation surfaceenhancementNew feature or requestevaosevaOS public beta R&D workkind:integrationIntegration implementation issueready-for-agentIssue has enough handoff detail for an agent to startrisk:securitySecurity, auth, secrets, permission risk
Milestone
evaOS Mac Access v0.1

Description

@100yenadmin
100yenadmin
opened on Jul 14, 2026

Current coordination amendment — 2026-07-15

This section supersedes stale current-state and dependency language below.

Fast implementation loop

Exact next action

Treat PR #707 head b0e26adaea15714ded504e1b690653ea543b9f25 as the architecture gate only after its current-head CI and all named review surfaces are terminal and clean. Then implement #700 from that exact accepted head in its isolated worktree. Do not merge, tag, publish, or alter the independent v2.1.36 release lane without separate authorization.

Context

Customers need a small Mac-side product that lets their evaOS VM agent use audited computer control without installing the full evaOS Workbench. The product should live in the canonical 100yenadmin/evaOS-GUI repository so the standalone app and Workbench consume one connector implementation, while retaining an independent build, version, and release cadence.

This is a post-v2.1.36 productization sprint. It must not delay, modify, or weaken the active v2.1.36 release gate.

Goal

Ship evaOS Mac Access v0.1 as a native menu-bar app and reusable connector core that:

  1. pairs a customer Mac to the broker-selected customer/device/grant scope;
  2. accepts only authenticated, scoped control requests from that selected VM agent path;
  3. executes audited CUA through the existing native/Peekaboo/helper stack;
  4. requires no Workbench installation, preinstalled Python, Homebrew package, or Tailscale/private-network setup;
  5. gives the Mac owner obvious Off, Ask Every Time, and Full Access controls plus immediate pause/revoke/kill-switch actions; and
  6. becomes the same stable Mac permission-owning runtime that Workbench can discover and use instead of starting a second connector.

Product and repository decision

  • Canonical repo and issue tracker: 100yenadmin/evaOS-GUI.
  • Standalone product: packages/mac-access.
  • Reusable runtime/package boundary: packages/mac-connector-core.
  • Workbench remains in packages/desktop and becomes a client of the shared runtime when Mac Access is installed.
  • Mac Access has its own semantic version, signed/notarized artifact, update feed, and rollback path.
  • Do not create a new repository unless a later evidence-backed decision shows separate access control, ownership, or release governance is required. The package boundary keeps that option open without duplicating source now.

Verified current state (2026-07-15)

Live GitHub truth was read at PR #697 head ae9f35062f8a4b212fab4576d44602b57dc0303a:

Architecture contract

Customer VM agent
      |
      v
evaOS broker / ws-proxy
      |
      | authenticated outbound WSS channel, selected binding only
      v
evaOS Mac Access.app  <---- authenticated local client ----  evaOS Workbench
      |
      v
mac-connector-core
      |
      v
stable signed helper / native CUA engine / bundled Peekaboo fallback

Stable identity

  • App bundle ID: com.evaos.mac-access
  • Helper/XPC identity: com.evaos.mac-access.helper
  • Connector LaunchAgent label, if a user LaunchAgent is still required: com.evaos.mac-access.connector
  • These identities are frozen before live permission proof. Workbench must not become a second TCC permission owner.
  • Secrets and pairing material stay in Keychain/main-process or native-service custody. They never enter a renderer, issue, screenshot, or default diagnostic bundle.

Transport

  • Remote control uses an outbound authenticated WebSocket/TLS connection to the existing broker/ws-proxy plane.
  • Every command is bound to the broker-selected customer_account_id, Mac/device ID, grant ID, session ID, nonce, expiry, and audit/correlation ID.
  • No public inbound listener, manual port forwarding, connector URL, raw token, or Tailscale enrollment is part of customer onboarding.
  • A loopback-only local API is allowed for Workbench integration, but it must require peer/authentication checks and must not be reachable off-host.

Runtime packaging

  • mac-connector-core is the only owned connector source.
  • Workbench and Mac Access package the same exact core digest and contract fixtures.
  • A v0.1 implementation may embed a private Python runtime while the existing bridge is migrated, but it must never depend on system Python, Homebrew, a customer shell command, or a separately installed package.
  • Rewriting the mature connector wholesale in Swift is not a v0.1 requirement. Native code owns the menu-bar UX, stable app/helper identity, Keychain custody, lifecycle, and TCC-facing boundary.

Customer experience

Mac Access runs as a menu-bar app with no Dock icon. Its dropdown provides:

  • one clear state: Disconnected, Connecting, Approval needed, Connected, Paused, or Blocked;
  • Connect to evaOS / Disconnect;
  • current access mode: Off, Ask Every Time, or Full Access;
  • permission status and one-click links to the correct macOS panes;
  • paired VM/account label using safe display names only;
  • last action time and safe action category;
  • Pause now, Revoke this VM, and Emergency stop;
  • redacted diagnostics, update status, and quit.

First run must be guided and recoverable: install, open, pair with a short code or broker handoff, grant the named permissions, choose an access mode, and see the first proof. No terminal instructions are part of the normal path.

Child issues

Issue Deliverable Initial state Dependencies
#699 Freeze architecture, identities, and connector-core boundary Ready for agent PR #697 may remain open for read-only inspection
#700 Extract the owned connector into reusable mac-connector-core Blocked #699 and merged/superseding PR #697 baseline
#701 Build native menu-bar app and first-run onboarding Blocked #699; integrates #700
#702 Add outbound broker-selected transport without Tailscale Blocked #699 and #700
#703 Enforce access modes, approvals, audit, revoke, and kill switch Blocked #700 and #702
#704 Make Workbench use shared runtime without dual ownership Blocked #700, #701, #702, and #703
#705 Add independent signed/notarized packaging, updater, and rollback Blocked #700, #701, and #703
#706 Prove pristine-Mac onboarding and VM-to-Mac CUA end to end Blocked #702, #703, #704, and #705

Dependency graph

PR #697 merged/superseded
      |
      v
#699 Architecture/identity contract
      |\
      | +--> #701 Native menu-bar shell/onboarding
      v
#700 Connector-core extraction
      |
      +--> #702 Outbound selected-binding transport --> #703 Access policy/audit
      |                                              |
      +------------------> #704 Workbench integration <---+
                             |                       |
                             +--> #705 Packaging/update <-+
                                      |
                                      v
                         #706 Pristine-Mac + VM CUA proof

Architecture work may inspect PR #697 while it is open. Implementation must branch from the merged/superseding canonical bridge baseline, not copy or fork the archived repository and not edit the active v2.1.36 release worktree.

Durable Plan Contract

  • Goal: deliver a standalone, simple Mac connector and shared Workbench dependency with one stable local trust owner.
  • Resume identity: repo 100yenadmin/evaOS-GUI; default branch main; active release branch evaos/beta-rc-20260612; precursor PR fix(workbench): own Mac bridge source #697; this epic and its milestone evaOS Mac Access v0.1 are the sprint source of truth.
  • Tracking/source of truth: GitHub issues, PRs, reviews, and CI own implementation. The Workbench One-App Experience initiative owns roadmap state. Notion stores architecture/evidence links only.
  • Scope: macOS menu-bar product, shared connector core, outbound selected-binding transport, user access controls, Workbench client integration, independent packaging, and proof.
  • Non-goals: Windows, iPhone Mirroring, reviving the archived bridge repo, changing v2.1.36 scope, a wholesale connector rewrite, customer rollout, or public release authorization.
  • Current state: PR fix(workbench): own Mac bridge source #697 is open and green/mergeable at the verified head; no standalone Mac Access app exists.
  • Exact next action: merge or supersede PR fix(workbench): own Mac bridge source #697, then execute the architecture/identity child issue in a clean isolated worktree.
  • Critical invariants: one TCC owner; broker-selected scope only; outbound-only remote transport; no external Python/Tailscale dependency; code-only public pairing; renderer receives no secrets; stop/revoke/kill switch fail closed; no second connector/listener when Workbench is present.
  • Execution lanes: architecture, core extraction, native shell, transport, policy/audit, Workbench integration, packaging, proof.
  • Evidence path: /Volumes/LEXAR/Codex/evidence/evaos-mac-access-v0.1/ with redacted manifests and exact source/artifact identities.

Validation and proof gates

  • Eval required: yes.
  • Initial claim class: PR quality only. No release-ready or customer-ready claim is allowed by this tracker.
  • Focused gates: contract/schema tests, core behavior tests, local IPC authentication, transport reconnect/replay/expiry tests, access-mode tests, redaction tests, migration/coexistence tests, signed-helper identity tests, and negative-path tests.
  • Broad gates: canonical GitHub Actions on each exact PR head.
  • Artifact gate: Developer ID signed, notarized, stapled Mac Access DMG/app; exact core digest and source SHA recorded; Gatekeeper accepted from a clean download.
  • Pristine-Mac gate: supported clean Mac with no Workbench, Homebrew Python, connector package, or Tailscale; normal onboarding uses no terminal.
  • Runtime gate: broker-selected VM agent executes read-only screen observation and one approved low-impact CUA action through the same binding, with audit IDs, then stop/revoke/kill switch block later actions.
  • Coexistence gate: installing/launching Workbench does not create a second connector, permission owner, listener, grant, or conflicting update channel.
  • Rollback gate: downgrade/uninstall/reinstall preserves safe revocation behavior and never leaves an orphan remote-control path.

Definition of done

  1. All eight child issues are closed by merged PRs and exact-head CI.
  2. One source package supplies both Mac Access and Workbench; no archived-repo checkout or duplicate connector source remains.
  3. The standalone signed/notarized artifact passes the pristine-Mac and VM-to-Mac CUA proof packet.
  4. Off/Ask Every Time/Full Access, pause, revoke, and kill switch pass positive and negative tests.
  5. Workbench coexistence passes with one local trust owner.
  6. Release notes and update metadata identify the standalone artifact and its independent version.
  7. Any public publication or customer rollout is separately authorized after evidence review.

Stop conditions

Stop and update this tracker if work would:

  • modify or delay the active v2.1.36 release candidate;
  • copy from or publish from the archived bridge repository;
  • introduce a second TCC/helper identity or dual connector ownership;
  • expose tokens, endpoints, private addresses, customer data, raw prompts, screenshots, or accessibility trees;
  • accept commands outside the broker-selected binding;
  • require a customer-installed Python, Homebrew package, Tailscale, port forward, or terminal command;
  • weaken approval, audit, stop/revoke, or kill-switch behavior to make a demo pass; or
  • claim release/customer readiness from fixtures, source review, CI, or a prepared Mac alone.

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:brokerevaOS broker/session/auth integrationarea:native-companionNative macOS companion boundaryarea:releasePackaging, signing, updater, rollbackarea:shellAionUi shell and navigation surfaceenhancementNew feature or requestevaosevaOS public beta R&D workkind:integrationIntegration implementation issueready-for-agentIssue has enough handoff detail for an agent to startrisk:securitySecurity, auth, secrets, permission risk

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions