CLI
Install the Matrix CLI to log in, connect coding agents over MCP, run agents, sync files, forward ports, and manage persistent shell sessions.
Maintained by the Matrix OS team. Product instructions are updated with the supported workflow.
The Matrix CLI is a single binary installed as matrix, matrixos, and mos. Use it to log in, attach to terminal sessions, sync files, forward ports, and run commands on your Matrix computer from any local terminal.
Install
Install the CLI
# Homebrew (macOS / Linux)
brew install finnaai/tap/matrix
# npm (requires Node.js 20+)
npm install -g @finnaai/matrix
# Standalone binary — no Node.js required
curl -fsSL https://get.matrix-os.com | shVerify
matrix --version
matrix doctorYou can also run without installing using npx --yes @finnaai/matrix <command> or pnpm dlx @finnaai/matrix <command>. Auth tokens are stored in ~/.matrixos/ and reused across invocations.
Update the CLI
CLI 0.3.22 and later include a single update command:
matrix update --check # check without installing
matrix update # install the newest stable CLIThis updates the CLI on the computer where you run it. It preserves saved profiles and sign-ins; it does not update or restart your Matrix computer.
Standalone installs verify the official release checksum and executable version before replacing the binary. Homebrew and recognized pnpm global installs use their package manager. Other managed installs should use their original manager.
If your CLI does not recognize update or preview
CLI 0.3.21 and earlier do not include matrix update. Refresh an existing
standalone installation with the official installer, using its current folder:
curl -fsSL https://get.matrix-os.com | MATRIX_INSTALL_DIR="$(dirname "$(command -v matrix)")" sh
matrix --version
matrix preview --helpFor Homebrew, run brew update followed by brew upgrade finnaai/tap/matrix.
preview is an internal team command and requires an eligible account.
Connect a coding agent over MCP
The Streamable HTTP integration with browser OAuth does not need a local Matrix CLI, but is not yet enabled. Use stdio until hosted rollout and browser sign-in are verified.
The stdio alternative remains available in Matrix CLI 0.3.16 and later. It runs a local bridge but executes tools on Matrix. Sign in, then configure your agent to launch the server command:
matrix login --profile cloud
matrix mcp serve --profile cloudThe second command is launched by your coding client as a stdio server. For clients with an mcpServers JSON configuration, merge this entry into the existing configuration after completing CLI login:
{
"mcpServers": {
"matrix": {
"command": "matrix",
"args": ["mcp", "serve", "--profile", "cloud"]
}
}
}Ensure matrix is on the coding client's PATH, or use its absolute executable path. Clients with another configuration format need the same command and argument list. This connection uses your CLI profile; it does not use HTTP OAuth or the hosted plugin. Configure one Matrix connection per client to avoid duplicate tools.
The server uses your existing Matrix CLI login and exposes remote tools for:
- listing the Matrix computers your account can access;
- running a captured command on an explicitly selected computer;
- listing and creating persistent zellij terminal sessions and tabs;
- selecting a terminal tab and sending input to it;
- listing, reading, downloading, and uploading bounded files in Matrix home; and
- listing, searching, and reading Matrix chats.
Call list_computers first. Every other tool requires the computer's runtimeSlot, even when you only have one computer. Matrix credentials stay in the CLI profile and are never passed as MCP tool arguments.
Tab creation returns a stable tab ID. Pass that ID to select_terminal_tab; the displayed tab position can change when other tabs are created, closed, or reordered.
Processes and persistent terminals
A process is a running program on a computer. Use run_command for a bounded, one-shot process whose output and exit status should be returned to the agent. Use a named terminal session and tab for a long-running or interactive process that should stay visible and reconnectable in Matrix.
MCP file transfer is content-only: it does not grant access to paths on the coding agent's host. Text reads are limited to 256 KiB, binary transfers to 1 MiB, directory listings to 500 entries, terminal input to 60,000 bytes, and chat pages to 100 items. Uploads do not overwrite an existing file unless overwrite is explicitly enabled.
The MCP server routes its own tools to Matrix. It cannot disable or replace any local shell tool that the coding-agent host separately provides.
Log in
matrix loginThis opens a browser for the device authentication flow. If you do not have a Matrix account yet, matrix login waits while the browser walks you through signup, checkout, and provisioning. After Checkout, Matrix keeps the device request active, shows build progress, and continues automatically when your computer is ready. You will not be asked to choose tools or start the build a second time. Approve the CLI in that same browser tab once provisioning finishes.
Flags
| Flag | Description |
|---|---|
--profile <name> | Authenticate into a specific named profile |
--platform <url> | Override the platform URL (default: https://app.matrix-os.com) |
--gateway <url> | Override the gateway URL written into the profile on success |
Local development shortcuts
# Skip the device flow; writes a stub token for a local dev stack
matrix login --dev
# Equivalent — uses the "local" profile and localhost endpoints
matrix login --profile local--dev expects the local gateway running without MATRIX_AUTH_TOKEN (any bearer is accepted in that mode).
Run agents
matrix run starts a command on your Matrix computer. With -it, it creates a new terminal tab and attaches to it. Use a separate local terminal for each interactive command.
matrix run -it --project main -- claude
matrix run -it --project main -- codexTo start in an existing repository, pass a path relative to your Matrix home:
matrix run -it --project main -C projects/my-repo -- claude| Flag | Description |
|---|---|
-it | Create a remote terminal tab and attach a TTY |
--project <project> | Select a registered project or main |
-C, --cwd <dir> | Working directory relative to the Matrix home |
--no-mouse | Drop mouse escape sequences before forwarding input |
Non-interactive runs capture stdout and stderr and forward the command's exit code. Interactive runs create new tabs; reconnect to an existing tab with shell connect instead of repeating run.
Connect to terminal tabs
The CLI and Web Desktop connect to the same remote terminal tabs. Create a tab once, then reconnect using the ID shown by shell ls:
# Create a new terminal and attach
matrix shell new --project main --name setup --attach
# Later, list existing tabs
matrix shell ls
# Replace YOUR_TAB_ID with the existing tab's ID
matrix shell connect --project main --tab YOUR_TAB_IDconnect and attach are aliases. --tab accepts a tab ID or an unambiguous tab name. Use the ID when names repeat. The old session-name commands and create-on-connect option are no longer supported.
Detach without stopping the remote process: press Ctrl-\ twice quickly. Closing a viewer does not stop the computer, but a host reboot or process exit does stop a running command.
If terminal creation fails
Run matrix shell ls and reconnect to an existing tab using its actual ID. Do not repeatedly create tabs or mistake a new tab for the previous agent conversation.
File sync
The sync daemon mirrors a local folder against your Matrix home directory and runs as a background service.
# Start syncing ~/matrixos (default local folder)
matrix sync
# Start syncing a specific local path
matrix sync ~/my-projects
# Scope sync to a subtree on the Matrix side
matrix sync ~/work --folder projects
# Check sync status
matrix sync status
# Pause and resume
matrix sync pause
matrix sync resumematrix sync installs and starts the daemon on first run. Subsequent calls with the same path reuse the running daemon without restarting it.
Flags
| Flag | Description |
|---|---|
-p, --path <dir> | Local folder to sync (default: ~/matrixos/) |
-f, --folder <name> | Gateway subtree to scope sync to. Default: full mirror of your sync root |
Upload and download single files
Use matrix upload and matrix download for one-off file transfers without starting or touching the sync daemon.
matrix upload ./README.md projects/demo/README.md
matrix upload --force ./config.json system/config.json
matrix upload --secret ./api-key.txt system/secrets/api-key.txt
matrix download projects/demo/README.md ./README.remote.md
matrix download --force projects/demo/README.md ./README.remote.mdFlags (both commands)
| Flag | Description |
|---|---|
--force | Overwrite the destination if it already exists |
--secret | Mark the file as secret on upload (affects storage handling) |
Port forwarding
matrix port forward (or the top-level matrix forward alias) opens a local loopback listener and tunnels it to a port on your Matrix computer. The local listener always binds to 127.0.0.1. The remote target must also be a loopback address on the Matrix computer.
Spec format
<port> # local and remote port are the same
<localPort>:<remoteHost>:<remotePort>Valid remote hosts: 127.0.0.1, localhost, [::1].
Examples
# Forward local 3000 to Matrix computer 127.0.0.1:3000
matrix port forward 3000
# Forward local 8080 to Matrix computer port 3000
matrix port forward 8080:127.0.0.1:3000
# Same via the top-level alias
matrix forward 3000
# Forward a Vite dev server running on the Matrix computer
matrix port forward 5173After the forwarding is active, open http://127.0.0.1:<localPort> in your local browser. The command keeps running until you press Ctrl-C.
Start the service first
The target service must already be running on the Matrix computer before forwarding traffic to it. Attach a terminal session to start your dev server there, then run matrix port forward in a separate local terminal.
GitHub developer access inside a Matrix session
Run the fixed developer-access setup inside a Matrix terminal session rather than moving credentials from your local machine. This configures GitHub CLI, SSH, and commit identity on the Matrix computer where your agents and workflows run.
matrix run -it --project main -- matrix-github-developer-loginSet 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.
Status and diagnostics
# Show active profile, gateway URL, and auth state
matrix status
# Show the authenticated Matrix identity
matrix whoami
# Run all health checks and print fix-it hints
matrix doctormatrix doctor checks profile config, auth token validity, the local sync daemon, gateway reachability, and the shell backend. Run it before filing a support issue.
$ matrix doctor
OK profile
OK auth
FAIL daemon - Start sync with `mos sync`.
OK gateway
OK shell-backend
OK protocolGlobal flags
Most commands accept these flags:
| Flag | Description |
|---|---|
--profile <name> | Use a named profile (default: active profile from profiles.json) |
--gateway <url> | Override gateway URL for this invocation |
--platform <url> | Override platform URL for this invocation |
--token <jwt> | Override auth token (useful in CI) |
--dev | Shorthand for --profile local |
--json | Emit machine-readable JSON (NDJSON for streaming commands) |
How is this guide?
Self-host
Install Matrix OS on your own Linux VPS with the server installer. Review requirements, setup steps, data ownership, updates, and maintenance.
Matrix MCP
Connect your coding agent to your Matrix computer over Streamable HTTP with Matrix MCP. Learn authentication, setup, tools, and access boundaries.


