Web Shell
Open your Matrix computer in a browser at app.matrix-os.com. Work with Terminal, Files, Apps, and Chat from the same persistent workspace.
Maintained by the Matrix OS team. Product instructions are updated with the supported workflow.
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.
Shared top bar
In the App Gallery preview, Web Desktop, Web Canvas and Electron Desktop share Search, Inbox, Help, computer selection and the account menu. The view menu switches between Desktop view and Canvas view without closing apps. Your web and Electron presentation choices are remembered independently.
Inbox shows recent app/task activity and tasks that need attention. An unavailable feed offers Retry; it does not report an empty inbox. Help contains Getting started, Support chat and Join Discord. Computer selection identifies the current computer and only offers available computers for switching. Settings, plans and sign-out remain in the account menu.
Launcher and dock artwork use transparent images. Web Mobile's support launcher sits above app navigation; opening a support conversation keeps the normal chat panel. Owner-selected app artwork is preserved.
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 setupUse -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.
Agent sign-in terminals
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.
In Web Desktop, Web Canvas, and Electron Desktop, right-click anywhere inside Terminal and choose Paste, even when no output is selected. Paste closes the menu and returns focus to that terminal. It inserts clipboard text without pressing Enter; review the text before running it. If clipboard access is denied or unavailable, allow clipboard access and try again. Paste stays scoped to the terminal where you opened the 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.
Keyboard navigation and Zellij panes
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 developer access
Open Settings > Connect Apps, find GitHub Developer, and select Connect. Select Copy and Open GitHub, then enter the code on GitHub and authorize the computer. Settings automatically refreshes the status after verifying the connection.
To configure GitHub manually in Terminal, run:
matrix-github-developer-loginFor manual setup, complete the browser flow and confirm or edit the proposed commit identity. Setup becomes ready only after the account, SSH, and commit identity checks pass. The credentials, SSH keys, and Git identity stay on your Matrix computer and persist across sessions. See GitHub developer access for the distinction from Matrix sign-in, recovery, and key ownership.
Set a passphrase for your SSH key
When the setup command 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.
Related
How is this guide?
Matrix MCP
Connect your coding agent to your Matrix computer over Streamable HTTP with Matrix MCP. Learn authentication, setup, tools, and access boundaries.
Coding Agents
Install and run coding agents on your Matrix computer. Connect a local agent over MCP, manage sessions, and inspect the files your agents create.

