Desktop App

The native macOS and Windows client for projects, agent threads, shared terminals, files, and apps in one window.

Matrix OS Desktop is the native macOS and Windows client: 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.

Desktop downloads

Download the current signed macOS or Windows x64 build, or the Linux x86_64 AppImage, and follow the visual activation guide on the Matrix OS Desktop page. The web shell at app.matrix-os.com gives you the same Matrix computer from any browser. See the Web Shell docs.

Download and install

Download the latest Matrix OS Desktop stable release for your platform. On macOS, open the disk image and drag Matrix OS.app to Applications. On Windows x64, run the signed Windows x64 NSIS installer (.exe); it installs Matrix OS for your Windows account and adds Start menu and desktop shortcuts. If Windows shows Windows protected your PC, select More info, verify the publisher is Finna Labs Inc., then select Run anyway. Run as administrator does not bypass SmartScreen. This prompt can appear for a newly signed release while Microsoft builds its download reputation. Stable builds are the recommended channel for normal use; review the release notes before installing.

Launch the app and click Sign in with Matrix OS. A browser window opens to approve the device. Sign in with an existing Matrix account, or create an account from that page. Matrix Desktop never handles your password.

Start your hosted computer

New hosted users choose a plan and complete Stripe Checkout with a card. The first primary computer includes a 3-day trial; Stripe collects the card during checkout and charges the selected plan when the trial ends unless you cancel first. Existing users with a running computer skip this step and select the computer they want to connect. After Checkout, the browser keeps the Desktop approval request active and shows progress until the selected computer is ready; there is no second setup or build step.

Approve and return

Review the account, computer, and matching device code, then approve the connection. The browser returns you to Matrix OS automatically while the app completes authorization by polling. Your projects and board then load, and the credential is stored using the operating system's protected credential storage (macOS Keychain or Windows DPAPI) without leaving the app's trusted process.

The matrixos://auth?status=approved deep link is a focus signal only. The browser never puts a credential in the URL; Matrix Desktop finishes sign-in through the one-time device-code poll.

Signing out clears the local credential and any embedded web sessions, but never touches data on your Matrix computer.

The collapsible sidebar holds four primary destinations — Home, Chat, 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 ⌘\ on macOS and Ctrl+B or Ctrl+\ on Windows.

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 (⌘↵ on macOS, Ctrl+Enter on Windows) and Create + open (⌘⇧↵ on macOS, Ctrl+Shift+Enter on Windows). 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.

The same named sessions are also available from Windows Terminal through the Matrix CLI, so you can move between the native app and your preferred local terminal without creating duplicate sessions.

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.

Copy and paste shortcuts, right-click Copy and Select All, mouse-aware selection behavior, and Canvas/Desktop parity are covered in the Web Shell terminal guide.

Electron Desktop also shares keyboard navigation, customizable shortcuts, and Zellij pane controls with Web Canvas and Web Desktop. Use the pane toolbar or Command/Option shortcuts to split, focus, resize, and maximize panes inside the attached session.

Chat conversations

Open Chat to find and resume saved conversations on your selected Matrix computer. Choose an available agent harness and model in the composer. Use New chat to start a draft, and send your first message to save the conversation. See Chat conversations for message search and safe deletion.

Press ⌘J on macOS or Ctrl+J on Windows to open the composer from anywhere in the app.

You can also associate a chat with one project so future turns use that project's workspace. See Project context for Chat for setup and recovery when a workspace is unavailable.

Task workspace

Opening a task reveals a resizable panel strip — terminal, editor, git, files, artifacts, and a processes panel. Toggle panels with ⌘1–⌘6 on macOS or Ctrl+1–Ctrl+6 on Windows, 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 on macOS or Ctrl+P on Windows 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

macOS	Windows	Action
⌘K	Ctrl+K	Search chats when Chat is active and the palette is closed; otherwise toggle Command Palette
⌘J	Ctrl+J	Toggle agent composer
⌘P	Ctrl+P	Quick-open file by name
C	C	New task (when not in a text field)
⌘1–⌘6	Ctrl+1–Ctrl+6	Toggle task workspace panels
⌘B or ⌘\	Ctrl+B or Ctrl+\	Toggle sidebar
⌘W	Ctrl+W	Close current tab
Ctrl+Tab	Ctrl+Tab	Cycle to next tab
Ctrl+Shift+Tab	Ctrl+Shift+Tab	Cycle to previous tab

Standard platform menus, full-screen behavior, and native macOS or Windows 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.

Installed and running versions must match

Installed version is the release recorded on your Matrix computer. Running version is the gateway process currently serving projects, terminals, and apps. System settings only says the computer is on the latest release when those values match. If they differ, or the running version cannot be verified, run matrix instance restart from the Matrix CLI and retry the project action after the services return.

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.