hamedmp/matrix-os/matrix-cloud-run

Run Work on Matrix OS

Use the hosted Matrix MCP tools for remote work. Authenticate HTTP connections with the coding client's browser OAuth flow; no local Matrix CLI is required. The Matrix CLI fallback has separate authentication and is only for users who choose it or clients without remote MCP support.

MCP-first execution

1. Call list_computers and choose the explicit runtimeSlot; never guess or silently fall back to another computer.
2. Use run_command with the command argv array for short probes that need captured output. Hosted HTTP defaults to and caps commands at 45 seconds; use persistent terminals for longer work.
3. For observable or long-running work, use create_terminal, create_terminal_tab when useful, select_terminal_tab, and send_terminal_input. Report the terminal and tab names so the user can reconnect in Matrix.
4. Use list_files, read_file, download_file, and upload_file for bounded Matrix-home files. These tools never read or write arbitrary local paths.
5. Use list_chats, search_chats, and get_chat only when prior Matrix chat context is relevant; these tools are read-only.

For HTTP authentication failures, reconnect using codex mcp login <configured-server-name> or Claude Code's /mcp authentication flow. Do not collect tokens in chat. matrix login only repairs stdio/CLI authentication, not HTTP OAuth. If hosted MCP is unavailable, explain that status and offer the CLI fallback explicitly.

CLI fallback terminal policy

• Always use matrix run -it --project <project> ... -- <argv...> for remote commands; use main outside a known project.
• When another terminal or concurrent task is needed, create another tab in the same project workspace.
• Report every returned tab ID and matrix shell connect --project <project> --tab <tab-id> command immediately.
• Pass prompts as command arguments after --; never interpolate user input into sh -c, bash -lc, substitutions, or a single shell string.

CLI fallback readiness gate

Verify the local CLI, hosted profile, login, identity, and instance:

matrix --version
matrix profile show cloud
matrix doctor
matrix whoami
matrix status
matrix instance info --json

matrix instance info --json reads authenticated instance metadata from the gateway. A successful structured response confirms metadata reachability, not command execution. Use matrix doctor and a separate bounded one-shot matrix run --project main -- true command when execution health is required; do not infer execution readiness from matrix instance info.

If login is missing or expired, run matrix login --profile cloud and let the user complete browser/device authentication. If the instance is not provisioned, use https://app.matrix-os.com and wait until it is ready.

Check only the selected agent in separate readiness tabs:

matrix run -it --project main -- codex --version
matrix run -it --project main -- codex login status
matrix run -it --project main -- claude --version
matrix run -it --project main -- claude auth status

Run only the Codex pair or Claude pair. Authenticate a disconnected agent in auth-codex-<suffix> or auth-claude-<suffix>. Never scan, read, or upload local credential files. Ask before installing a missing global tool and prefer Matrix's visible developer-tool installation path.

Validate the destination

• Normalize a safe relative destination under the Matrix home.
• Reject empty paths, absolute paths, backslashes, control characters, and . or .. segments.
• Use apps/<slug> for a runnable Matrix app and projects/<name> for ordinary work.
• Inspect an existing destination before using it and stop on conflicting contents.

Use separate observable tabs for each probe:

matrix run -it --project main -- test -e <dir>
matrix run -it --project main -- test -d <dir>
matrix run -it --project main -- ls -la <dir>

For a new app, create the normalized directory before selecting it:

matrix run -it --project main -- mkdir -p -- apps/<slug>
matrix run -it --project main -C apps/<slug> -- pwd

-C selects an existing directory; it never creates it. Do not pass a nonexistent path to matrix run -C.

Run tasks

Create a new tab for every command:

matrix run -it --project <project> -C <dir> -- <argv...>
matrix shell connect --project <project> --tab <tab-id>

Observe the session through completion and report its actual command result. Never infer success from partial output or a disconnected local terminal.

For Codex inspection:

matrix run -it --project <project> -C <dir> -- codex --ask-for-approval never --sandbox read-only exec -- <prompt>

For Codex changes:

matrix run -it --project <project> -C <dir> -- codex --ask-for-approval never --sandbox workspace-write exec -- <prompt>

Pair unattended Codex with --ask-for-approval never and an explicit sandbox. Never use danger-full-access without explicit direction.

Run Claude without repetitive permission questions using its verified auto mode:

matrix run -it --project <project> -C <dir> -- claude --permission-mode auto -p <prompt>

Auto mode keeps background safety checks while minimizing clarification and permission prompts. If the installed Claude version or account does not support auto mode, report that limitation and stop; do not fall back to a permission bypass.

Handoff

Report the normalized destination, exact argv, validation performed, changed files, outcome, every terminal reference, and every matrix shell connect --project <project> --tab <tab-id> command.