Web Shell

The web shell at https://app.matrix-os.com is the primary interface to your Matrix computer. It gives you Terminal, Files, Canvas, apps, integrations, and settings — all running on your persistent Matrix computer.

Unread chats

In Chat, right-click a conversation and choose Mark as unread, the first menu item. An unread chat offers Mark as read in that position. Use the Unread filter to find conversations you want to return to, and All to show the full list. These choices persist and synchronize with Electron Desktop when both clients use the same Matrix computer.

Marking the chat you are currently viewing unread keeps the reminder until you leave and reopen it or explicitly mark it read. See Chat read behavior for details about new replies and background windows.

Terminal and sessions

The Terminal is a persistent shell that keeps running after you close the browser. Your sessions are shared across the web shell, the CLI, and the desktop app — start work in the browser and pick it up later from the CLI exactly where you left off.

Open Terminal

From the shell, click Terminal in the sidebar or dock. A new terminal session opens on your Matrix computer.

Create or attach a named session

Named sessions let you organize work and reattach from any surface. From the CLI:

matrix shell new main --attach
matrix shell connect main
matrix shell connect -c setup

Use -c (--create-or-connect) to open the session if it exists, or create it if it does not.

Detach without closing

To leave a session running while you switch away:

Ctrl-\ Ctrl-\

The session stays live on your Matrix computer. Reconnect from the browser or CLI at any time.

Sessions are shared across surfaces

The web Terminal, matrix shell connect, and the desktop app all attach to the same named session model. A session you open in the browser is immediately available from the CLI and vice versa.

Close, detach, or delete

Closing the outer Terminal window only detaches that view. Its named sessions keep running on your Matrix computer and remain available from Web Desktop, Web Canvas, Electron Desktop, and the CLI.

Close pane ends the focused pane's process inside the attached Zellij session. Other panes in that session keep running; closing its last pane ends the session. Closing a Matrix Terminal session tab or choosing Delete session stops the named session and removes its saved Terminal references. Older saved layouts can contain separate named sessions, so check the session you are closing.

Stopping work is different from hiding it

Use the outer window close control when you want work to continue in the background. Close a pane or delete a session only when you intend to stop that work.

Updates and recovery

On releases with the supervised terminal runtime, a normal gateway update or app rollback disconnects attachments while the terminal process keeps running. Reconnect to the same named session after Matrix returns. A host reboot or runtime failure does not automatically restart your shell command or coding agent.

In Web Desktop and Web Canvas, when a saved session is unavailable, Terminal shows Session is unavailable instead of silently creating a replacement. Choose Recover session explicitly, or remove the stale session reference. Recovery is not a promise to restore the previous command, viewport, or complete scrollback. Check the recovered shell before resuming work; recovery cannot bring a terminated process back to life.

A deliberately deleted session is removed from saved layouts and is not offered there for recovery.

Terminal output can contain sensitive data

Terminal history may contain commands, paths, credentials, or other printed content. Deleting a session does not guarantee that every retained copy of its output has been erased. Avoid printing secrets into terminal history or sharing output that contains them.

In Web Desktop and Web Canvas, coding-agent installation and sign-in actions use a dedicated temporary Terminal window. That setup window does not read or overwrite your ordinary Terminal layout, and its temporary session is cleaned up when the setup window closes.

Electron Desktop uses a regular named session for provider setup. Closing its outer Terminal window detaches the view; close the setup session explicitly when you are finished with it.

Copy, paste, and selection

Terminal clipboard controls work the same way in the web shell and native desktop app, in both Canvas and Desktop layouts:

Action	macOS	Other platforms
Copy the current selection	⌘C or ⌘⇧C	Ctrl⇧C
Paste into the focused terminal	⌘V	Ctrl⇧V
Select all terminal output and scrollback	⌘A	Right-click and choose Select All

Right-click a terminal selection to open its menu. Copy stays enabled for the complete highlighted range, including multiple rows, wrapped lines, whitespace, punctuation, and Unicode. The word beneath the pointer does not replace the selection. You can also choose Select All from this menu.

When a coding agent or another terminal application enables mouse reporting, ordinary pointer movement does not clear a completed selection. Deliberate terminal input—typing, pasting, or beginning a new selection—returns control to the application normally.

Selections and clipboard behavior are consistent between Canvas and Desktop, including after changing Canvas zoom. Clipboard failures show a generic error, leave the selection available for retry, and never partially paste text.

Web Canvas, Web Desktop, and Electron Desktop share the same terminal keyboard settings and pane controls. Click inside the terminal before using shortcuts. On macOS, the default Mac editing profile provides:

Action	Shortcut
Beginning / end of the input line	⌘← / ⌘→
Previous / next word	⌥← / ⌥→
Delete the previous word	⌥⌫
Delete back to the beginning of the line	⌘⌫
Top / bottom of the pane history	⌘↑ / ⌘↓
Focus a neighboring pane	⌘⌥ + arrow
Resize the focused pane	⌘⌥⇧ + arrow
Split right / below	⌘D / ⌘⇧D
Maximize / restore the focused pane	⌘⇧Enter

Line editing uses the shell application's bindings. For applications with their own keymaps, select Standard terminal or Pass through to application from Keyboard shortcuts. The latter turns off Matrix keyboard interception for editing and pane commands; the pane toolbar remains available.

On other platforms, the default pane shortcuts use Ctrl⇧ + arrow for focus, CtrlAlt⇧ + arrow for resize, Ctrl⇧D / Ctrl⇧E for split right / below, and Ctrl⇧Enter for maximize / restore. Standard terminal uses these same pane shortcuts on macOS while preserving the application's normal editing keys.

Prefix alternative

Browsers and operating systems reserve some shortcuts. With Mac editing or Standard terminal selected, press CtrlG, release it, then press one of:

Key	Action
H / J / K / L, or an arrow	Focus left / down / up / right
Shift + arrow	Resize
V / S	Split right / below
F	Maximize / restore
T / B	Top / bottom of pane history
X	Close the focused pane and end its process

Escape cancels the prefix; it also expires after two seconds. The toolbar provides the same actions if the browser intercepts a key before Matrix receives it.

Customize shortcuts

Open Keyboard shortcuts, choose a profile, edit a binding, and click Save shortcuts. Use names such as Meta+ArrowLeft (Command on macOS) or Ctrl+Shift+D. Clear a field to disable that command. Duplicate bindings and reserved clipboard, search, or prefix shortcuts are rejected. Reset defaults restores the draft defaults; click Save shortcuts to apply them.

Settings are saved on your Matrix computer and loaded when you attach a terminal. Copy, paste, selection, and text composition keep their existing behavior.

New splits are Zellij panes within the current named session. They persist with that session and are available when you reattach from another surface. Older saved layouts containing separate sessions remain readable. Close pane ends the focused pane's process; closing the last pane ends the session. Controls are disabled while disconnected or when this surface no longer owns terminal input.

GitHub auth

Run gh auth login inside a terminal session to authenticate with GitHub. The credentials are stored on your Matrix computer and persist across sessions.

gh auth login

Choose the browser-based flow and complete the login in the browser tab that opens. Once done, git and gh commands work from any terminal session without re-authenticating.

Set a passphrase for your SSH key

When gh auth login generates an SSH key in the shell, choose a password (passphrase) for it — don't leave it empty. The key lives on your Matrix computer; a passphrase keeps it protected.

File browser

Click Files in the sidebar to open the file browser. It shows your Matrix home directory and lets you navigate folders, select files, rename, copy, paste, delete, and move items to Trash.

Navigate directories with the column view or list view.
Select a file and press Space to preview it with Quick Look.
Double-click a file to open it in the Preview panel.
Right-click any file or folder for a context menu with copy, cut, paste, duplicate, rename, and delete options.

Files you create or clone in the Terminal appear immediately in the file browser. Changes sync across the web shell and persist on your Matrix computer.

Refresh and PWA cache

The browser and installed PWA keep a private shell snapshot on your device so refreshes can restore your theme, wallpaper, dock, launcher apps, and saved shell bootstrap before the network finishes. The snapshot is scoped to the signed-in account and runtime path, expires automatically, and is replaced after the shell revalidates with your Matrix computer.

Static shell assets such as icons, fonts, bundled wallpapers, and Next.js chunks can be cached by the browser and service worker. Private APIs, auth pages, app documents, billing/provisioning routes, and owner data stay no-store and are never shared through the CDN cache.

Desktop icon layout

Your Desktop icon positions are durable owner state on your Matrix computer. The same layout appears in the web shell and the desktop app, and it follows you when you sign in on another device. A private, account-and-computer-scoped browser snapshot can show the last validated layout immediately during startup, then the shell reconciles it with the durable copy.

New Desktops start with Chat, Terminal, Files, Editor, VS Code, Settings, Plugins, Browser, Notes, and Whiteboard. During the durable-layout upgrade, an older Desktop that had lost every icon because its layout was never initialized is restored once. Matrix OS does not add icons to a customized nonempty layout or reorder it.

If you intentionally remove every icon, that empty Desktop remains valid after the one-time recovery has run. Move, add, and remove actions continue to save normally and appear on your other devices after they reconnect.

What persists

Shell sessions and terminal output.
Source repositories under ~/projects.
GitHub credentials and agent credentials you install inside the workspace.
App state and settings under your Matrix home.

CLI

Attach to sessions, sync files, and run commands from your local terminal.

Coding Agents

Run Claude, Codex, and other agents inside your Matrix terminal sessions.