Desktop App (Operator)
The native macOS app for Matrix OS — projects, tasks, agent threads, terminals, and apps in one keyboard-first window.
Operator is the Matrix OS desktop app for macOS: a keyboard-first mission control where your projects, tasks, agent runs, terminals, files, and Matrix OS apps live in one window, connected to your Matrix computer. Nothing runs locally except the app itself — sign in on a new machine and everything is restored from your computer in the cloud.
macOS only
Operator is a macOS app. The web shell at app.matrix-os.com gives you the same
access to your Matrix computer from any browser. See the Web Shell docs.
Install and sign in
Download and install
Download the macOS build and drag Matrix OS.app to Applications. Signed and notarized public distribution is tracked in the desktop release pipeline; current builds are internal.
Sign in
Launch the app and click Sign in with Matrix OS. A browser window opens to approve the device. The deep link that returns you to the app is a focus signal only — auth completes via polling, so you can approve in any browser tab without copying tokens by hand.
Start working
Once approved, your projects and board load automatically. Your credential is stored in the macOS Keychain and never leaves the app's trusted process.
Signing out clears the local credential and any embedded web sessions, but never touches data on your Matrix computer.
Navigation
The collapsible sidebar holds four primary destinations — Home, Chat (Hermes), Terminal, and Apps — followed by your Projects list. Everything you open becomes a tab in the main area. Tabs are cached: switching away from a terminal never kills it, and coming back is instant. Close a tab with its close button or a middle-click; the Home tab always stays. Toggle the sidebar with ⌘B or ⌘\.
Board
Open a project from the sidebar to see its kanban board with Todo, Running, Waiting, Blocked, and Complete columns. Drag cards between columns, right-click a card for status, priority, archive, and delete actions, and press C to create a task from anywhere on the board. The create dialog offers Create (⌘↵) and Create + open (⌘⇧↵). Each task opens as its own tab. Changes made on the web shell, CLI, or by agents show up in real time.
Terminals
The Terminal tab lists your named sessions, shared with the web shell and CLI — all three surfaces show the same sessions. Click a session to attach to the live shell on your Matrix computer, with scrollback intact. Terminals reconnect automatically after a network drop or sleep/wake without duplicating output. If a session has ended on the server, the terminal shows a clear ended state with a one-click recreate action.
Sessions are shared across surfaces
A terminal session you open in Operator is immediately available from the web shell and the
CLI. See the CLI docs for matrix shell connect usage.
Agent threads (Hermes)
Press ⌘J to open the composer and start an agent run. Each run is a thread with live status (running, needs attention, done, failed). Run several at once and switch freely between them; the sidebar shows unread markers and needs-attention badges. The Chat sidebar item opens the full Hermes thread list as a tab.
Task workspace
Opening a task reveals a resizable panel strip — terminal, editor, git, files, artifacts, and a processes panel. Toggle panels with ⌘1–⌘6, drag dividers to resize, and the layout persists per task. The built-in code editor has syntax highlighting for common languages, find/replace, and conflict-safe saves (it warns if a file changed on the server since you opened it). Press ⌘P to quick-open a file by name.
Apps
The Apps tab opens your Matrix OS app launcher. Click any installed app to open it as a tab in an isolated context with the same data bridge you get on the web. Open apps also appear in the sidebar under Open apps for quick access without going back to the launcher.
Keyboard shortcuts
| Shortcut | Action |
|---|---|
| ⌘K | Command palette — tasks, projects, apps, files |
| ⌘J | Toggle agent composer |
| ⌘P | Quick-open file by name |
| C | New task (when not in a text field) |
| ⌘1–⌘6 | Toggle task workspace panels |
| ⌘B or ⌘\ | Toggle sidebar |
| ⌘W | Close current tab |
| Ctrl+Tab | Cycle to next tab |
| Ctrl+Shift+Tab | Cycle to previous tab |
Standard macOS menus, full-screen, and window controls work as expected.
Settings
Native settings cover Account, Billing, Appearance (dark/light/system), Agent (Hermes configuration), Runtime (switch Matrix computer target), Channels, Integrations, Schedules, and System info. Switching runtime re-targets every surface — board, terminals, chat, and apps.
Updates and What's New
When a release feed is configured, Matrix OS checks for eligible releases and downloads eligible updates in the background. You can keep working while the download completes. When the package is ready, a blue Update action appears beside your avatar in the bottom-left corner.
Clicking Update immediately restarts Matrix OS and installs the downloaded release. There is no second confirmation dialog, so save any local text you are editing before you click it. You do not need to download another installer bundle.
After the new version launches, Matrix OS automatically opens What's New with the release version, publication date, and release notes. It is shown automatically only once per installed version; closing the dialog acknowledges that release.
Availability
Automatic updates require a signed packaged build and a configured release channel. Development builds do not install OTA releases.
Privacy
The app holds no durable workspace data locally: only the credential, your connection profile, window and layout state, bounded caches, and the last installed release notes. Losing the machine loses no work.
Related
How is this guide?