hamedmp/matrix-os/matrix-onboarding

Matrix OS Setup and Recovery

Prepare the user's Matrix cloud computer without collecting or transferring local secrets. Prefer the bundled hosted Matrix MCP tools with browser OAuth; no Matrix CLI installation is needed. Keep the separately authenticated CLI fallback optional for diagnosis and recovery.

MCP readiness

When remote tools are available, call list_computers first. After selecting an explicit runtimeSlot, use run_command for captured readiness checks and the terminal tools (create_terminal, create_terminal_tab, select_terminal_tab, and send_terminal_input) for observable authentication or recovery work. Never pass credentials as tool arguments.

For HTTP authentication failures, use codex mcp login <configured-server-name> or Claude Code's /mcp browser authentication. matrix login repairs only stdio/CLI credentials. If hosted tools are unavailable, explain the status and offer the CLI fallback. Never collect OAuth tokens or codes in chat. Hosted run_command takes a command array and defaults to/caps at 45 seconds; longer work belongs in persistent terminals.

Safety and terminal rules

• For the CLI fallback, use the cloud profile unless the user explicitly requests local development. Hosted HTTP has no local CLI profile.
• Use browser/device authentication inside Matrix. Never scan, read, or upload local credential files.
• Never ask for tokens, OAuth codes, API keys, or credential contents in chat.
• Ask before deleting files, resetting authentication or sessions, or installing global tools.
• Prefer Matrix's visible developer-tool installation path for missing agents or GitHub CLI.
• With MCP, use explicit named terminals and tabs and report their identities.
• Always run remote work in a tab created with matrix run -it --project <project>; use main outside a known project.
• Each project owns one workspace. Open another Matrix tab whenever another terminal or concurrent task is needed.
• Report every returned tab ID and its matrix shell connect --project <project> --tab <tab-id> command.
• Use the existing Matrix CLI. Do not invent endpoints, SSH access, persistence, or detached-job APIs.

CLI fallback readiness gate

1. Verify the local CLI and hosted profile:

matrix --version
matrix profile show cloud

If the CLI is missing, use current instructions from https://matrix-os.com/skills.md. If the cloud profile or login is missing or expired, run matrix login --profile cloud and let the user finish the browser/device flow. If no computer is provisioned, direct the user to https://app.matrix-os.com and wait for provisioning.

1. Verify health, identity, routing, and readiness:

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.

1. Check the selected coding agent inside its own observable tabs:

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

or:

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

Treat a missing executable separately from an unauthenticated executable. Ask before global installation.

1. Authenticate a present but disconnected tool in a new main tab:

matrix run -it --project main -- codex login
matrix shell connect --project main --tab <tab-id>
matrix run -it --project main -- claude

Use the agent's native interactive login and re-run its status in a new tab afterward.

1. When GitHub access is needed, check and authenticate it on Matrix:

matrix run -it --project main -- gh auth status
matrix run -it --project main -- gh auth login --hostname github.com --git-protocol ssh --web
matrix shell connect --project main --tab <tab-id>

Run login only when authentication is missing. Do not rely on the local computer's GitHub login.

Recovery

• Repeat matrix login --profile cloud for an expired Matrix login, then repeat the gate.
• Wait for the runtime page to report ready during provisioning; do not switch to localhost.
• For a failed attach, list tabs with matrix shell list, then connect to the exact project and tab ID.
• Do not repeat the same failed tab create indefinitely; reconnect a valid tab or create another tab.
• Keep failed authentication tabs visible for diagnosis. Never replace device authentication with copied credentials.
• Report timeouts, non-zero exits, disconnects, and incomplete output accurately.

Handoff

Report the cloud profile, Matrix identity, readiness source, doctor result, selected agent and authentication status, GitHub status when relevant, every active terminal reference, and each reconnect command.