Aplikasi macOS | Mayros Docs

Aplikasi macOS adalah companion menu-bar untuk Mayros. Ini memiliki izin, mengelola/melampirkan ke Gateway secara lokal (launchd atau manual), dan mengekspos kemampuan macOS ke agen sebagai node.

Apa yang dilakukannya

Menampilkan notifikasi native dan status di menu bar.
Memiliki prompt TCC (Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Automation/AppleScript).
Menjalankan atau terhubung ke Gateway (lokal atau remote).
Mengekspos tool khusus macOS (Canvas, Camera, Screen Recording, system.run).
Memulai service host node lokal dalam mode remote (launchd), dan menghentikannya dalam mode local.
Opsional meng-host PeekabooBridge untuk UI automation.
Menginstal CLI global (mayros) melalui npm/pnpm atas permintaan (bun tidak direkomendasikan untuk runtime Gateway).

Mode lokal vs remote

Lokal (default): aplikasi melampirkan ke Gateway lokal yang sedang berjalan jika ada; jika tidak, aplikasi mengaktifkan service launchd melalui mayros gateway install.
Remote: aplikasi terhubung ke Gateway melalui SSH/Tailscale dan tidak pernah memulai proses lokal. Aplikasi memulai service host node lokal sehingga Gateway remote dapat mencapai Mac ini. Aplikasi tidak menelurkan Gateway sebagai child process.

Kontrol Launchd

Aplikasi mengelola LaunchAgent per-pengguna yang diberi label bot.molt.gateway (atau bot.molt.<profile> saat menggunakan --profile/MAYROS_PROFILE; lama com.mayros.* masih di-unload).

bash
launchctl kickstart -k gui/$UID/bot.molt.gateway
launchctl bootout gui/$UID/bot.molt.gateway

Ganti label dengan bot.molt.<profile> saat menjalankan profil yang diberi nama.

Jika LaunchAgent tidak diinstal, aktifkan dari aplikasi atau jalankan mayros gateway install.

Kemampuan node (mac)

Aplikasi macOS menampilkan dirinya sebagai node. Command umum:

Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
Camera: camera.snap, camera.clip
Screen: screen.record
System: system.run, system.notify

Node melaporkan peta permissions sehingga agen dapat memutuskan apa yang diizinkan.

Service node + IPC aplikasi:

Ketika service host node headless berjalan (mode remote), ia terhubung ke Gateway WS sebagai node.
system.run dieksekusi di aplikasi macOS (konteks UI/TCC) melalui Unix socket lokal; prompt + output tetap di dalam aplikasi.

Diagram (SCI):

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + TCC + system.run)

Persetujuan Exec (system.run)

system.run dikontrol oleh Exec approvals di aplikasi macOS (Settings → Exec approvals). Keamanan + tanya + allowlist disimpan secara lokal di Mac di:

~/.mayros/exec-approvals.json

Contoh:

json
{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}

Catatan:

Entri allowlist adalah pola glob untuk jalur binary yang di-resolve.
Memilih "Always Allow" di prompt menambahkan command itu ke allowlist.
Override environment system.run difilter (drops PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT) dan kemudian digabungkan dengan environment aplikasi.

Deep links

Aplikasi mendaftarkan skema URL mayros:// untuk aksi lokal.

`mayros://agent`

Memicu request agent Gateway.

bash
open 'mayros://agent?message=Hello%20from%20deep%20link'

Parameter query:

message (wajib)
sessionKey (opsional)
thinking (opsional)
deliver / to / channel (opsional)
timeoutSeconds (opsional)
key (kunci mode unattended opsional)

Keamanan:

Tanpa key, aplikasi meminta konfirmasi.
Tanpa key, aplikasi memberlakukan batas pesan pendek untuk prompt konfirmasi dan mengabaikan deliver / to / channel.
Dengan key yang valid, run berjalan tanpa pengawasan (ditujukan untuk otomasi pribadi).

Alur onboarding (tipikal)

Instal dan luncurkan Mayros.app.
Selesaikan checklist izin (prompt TCC).
Pastikan mode Lokal aktif dan Gateway berjalan.
Instal CLI jika Anda ingin akses terminal.

Alur kerja build & dev (native)

cd apps/macos && swift build
swift run Mayros (atau Xcode)
Package aplikasi: scripts/package-mac-app.sh

Debug konektivitas gateway (macOS CLI)

Gunakan debug CLI untuk menjalankan logika handshake dan discovery Gateway WebSocket yang sama dengan yang digunakan aplikasi macOS, tanpa meluncurkan aplikasi.

bash
cd apps/macos
swift run mayros-mac connect --json
swift run mayros-mac discover --timeout 3000 --json

Opsi connect:

--url <ws://host:port>: override config
--mode <local|remote>: resolve dari config (default: config atau local)
--probe: paksa health probe baru
--timeout <ms>: timeout request (default: 15000)
--json: output terstruktur untuk diffing

Opsi discovery:

--include-local: sertakan gateways yang akan difilter sebagai "local"
--timeout <ms>: jendela discovery keseluruhan (default: 2000)
--json: output terstruktur untuk diffing

Tips: bandingkan dengan mayros gateway discover --json untuk melihat apakah pipeline discovery aplikasi macOS (NWBrowser + fallback DNS-SD tailnet) berbeda dari discovery berbasis dns-sd Node CLI.

Plumbing koneksi remote (SSH tunnels)

Ketika aplikasi macOS berjalan dalam mode Remote, ia membuka SSH tunnel sehingga komponen UI lokal dapat berkomunikasi dengan Gateway remote seolah-olah ada di localhost.

Control tunnel (port WebSocket Gateway)

Tujuan: health checks, status, Web Chat, config, dan panggilan control-plane lainnya.
Port lokal: port Gateway (default 18789), selalu stabil.
Port remote: port Gateway yang sama di host remote.
Perilaku: tidak ada port lokal acak; aplikasi menggunakan kembali tunnel sehat yang ada atau memulai ulang jika diperlukan.
Bentuk SSH: ssh -N -L <local>:127.0.0.1:<remote> dengan BatchMode + ExitOnForwardFailure + opsi keepalive.
Pelaporan IP: SSH tunnel menggunakan loopback, jadi gateway akan melihat IP node sebagai 127.0.0.1. Gunakan transport Direct (ws/wss) jika Anda ingin IP klien nyata muncul (lihat akses remote macOS).

Untuk langkah-langkah setup, lihat akses remote macOS. Untuk detail protokol, lihat protokol Gateway.

Mayros macOS Companion (menu bar + gateway broker)