Matrix OSMatrix OS

Desktop App

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

Maintained by the Matrix OS team. Product instructions are updated with the supported workflow.

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. Agent work runs on that computer. The app can also read local Claude Code and Codex transcripts when you choose to import them. Sign in on a new machine to restore work already saved to your Matrix computer.

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.

Install and sign in

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.

Sign in or create an account

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 14-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 App Gallery preview uses the shared top bar for Desktop/Canvas view selection, Search, app/task Inbox, Help, computer selection and account actions. The launcher includes distinct Desktop and Canvas icons. Organization selection is hidden in this preview.

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, Paste, 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.

Import local Claude Code and Codex chats

Open Settings → Import chats in Electron Desktop. Matrix finds conversations on this computer in ~/.claude/projects and ~/.codex/sessions, including archived Codex sessions. There is no file picker. Refresh after creating new conversations; history from another computer does not appear in this list.

Settings shows all conversations found, selected by default. Uncheck any you want to leave out, or use Deselect all and choose individually. Search by conversation or project, filter by app, and browse pages in large libraries. Filters preserve your selection; the count includes selected conversations hidden by the current filter.

Choose Import selected chats to import the full selection. Matrix reads and uploads one conversation at a time, so large selections do not need to be split into small batches. Each becomes a separate private Matrix chat. Use a conversation’s Preview action if you want to review or edit its title first. Discovery and previews stay local; uploads begin only after you choose Import. Original files remain unchanged, and retrying the same transcript avoids duplicate imports. If a scan reaches its safety limit, Settings tells you the list may be incomplete.

Progress and recovery are shown per chat. A failed import can be retried without repeating successful imports. Stop waiting stops the current wait; an upload already accepted by your Matrix computer may still finish. Retry the same transcript to check its result.

Imported chats appear in Chat with a small Claude Code or Codex source icon. The Chat source filter shows all chats, imported chats, or one app's imports. The source icon identifies where the history came from, independently of the harness selected for future turns. Chats already saved to Matrix are readable in Web Canvas and Web Desktop too. Browsers cannot automatically scan your computer's home folders; their import flow uses explicitly selected transcript files.

Original history and privacy

Supported messages, tool activity, and embedded attachments become readable history. Matrix preserves the original transcript privately, including internal context and thinking. Local files referenced by a transcript are not uploaded automatically. Transcripts may contain pasted secrets. Sharing a chat does not share its private original archive.

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

macOSWindowsAction
⌘KCtrl+KSearch chats when Chat is active and the palette is closed; otherwise toggle Command Palette
⌘NCtrl+NOpen a new Chat draft while Chat is active, preserving its floating-window or maximized-tab presentation
⌘JCtrl+JToggle agent composer
⌘PCtrl+PQuick-open file by name
CCNew task (when not in a text field)
⌘1–⌘6Ctrl+1–Ctrl+6Toggle task workspace panels
⌘B or ⌘\Ctrl+B or Ctrl+\Toggle sidebar
⌘WCtrl+WClose current tab
Ctrl+TabCtrl+TabCycle to next tab
Ctrl+Shift+TabCtrl+Shift+TabCycle 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.

Matrix OS Canary

Matrix OS Canary is an early build of the desktop app. It is rebuilt each time a change to the desktop app lands, so it gets new features before the stable release. Canary can have bugs that stable does not. Use stable for normal work.

Canary is a separate app, so you can install it next to Matrix OS:

  • It is named Matrix OS Canary and has a black icon with a white rabbit.
  • It keeps its own settings, sign-in, and downloaded updates. Signing out of one app does not sign out the other.
  • Both apps can be signed in to the same Matrix computer at the same time.
  • It uses the matrixos-canary:// link, so browser approval returns you to the app that asked.
  • It updates only from the Canary feed. It never replaces your stable install.

Canary can be newer than the software on your Matrix computer. Canary does not show the Update Matrix OS dialog when the two releases are different but can still work together. It shows the dialog only when they cannot work together.

Earlier Canary installs

A Canary build from before this change uses the same app identity as stable, so it cannot update itself into Matrix OS Canary. If your Matrix OS.app came from the Canary feed, install the stable release again. Then install Matrix OS Canary one time. On Windows, uninstall any earlier Canary build by hand.

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.

How is this guide?

On this page