Matrix OSMatrix OS

Cloud Coding

Set up workspaces, owner-controlled GitHub developer access, Browser IDE, reviews, and sandboxed coding agents in Matrix OS.

Maintained by the Matrix OS team. Product instructions are updated with the supported workflow.

Matrix OS cloud coding workspaces turn each user VPS into a private development machine. Projects, tasks, worktrees, sessions, transcripts, reviews, and editor settings live in the user's Matrix home so the gateway, web desktop, CLI, TUI, and browser IDE all operate on the same records.

GitHub developer access

Availability: These controls appear only after your Matrix client and computer receive compatible releases that include GitHub developer access. For Electron, update the Desktop app as well as the computer when prompted. Until then, follow the GitHub setup shown by your current Matrix version.

Matrix sign-in and GitHub access are separate

Continue with GitHub signs you in to Matrix through Clerk. It identifies your Matrix account, but it does not grant your Matrix computer repository access, configure SSH, or choose the author recorded on commits.

GitHub developer access is configured separately on each Matrix computer. It gives Git, GitHub CLI, terminal sessions, the Browser IDE, and coding agents one owner-controlled GitHub identity for private clones, commits, pushes, and pull requests.

Connect a Matrix computer

On Web or Electron Desktop, open Settings > Connect Apps, find GitHub Developer, and select Connect or Finish setup. Select Copy to copy the one-time code, then select Open GitHub. Enter the code on GitHub and authorize the computer. Settings automatically refreshes the status after verifying the GitHub account, SSH, and commit identity.

Setup reuses an SSH key that already works for the connected account. If a key needs to be registered, Matrix picks the first eligible local key or generates a dedicated key if none is available. Setup fills in any missing Git commit name or email from your GitHub profile and keeps your existing valid identity.

On Native Mobile, open Settings > Developer access and follow the Terminal flow. You can also run the same manual setup command in a Terminal on the selected Matrix computer:

Terminal
matrix-github-developer-login

In the manual flow, complete GitHub's browser authorization and confirm or edit the proposed Git identity in Terminal. Use this flow if you need to select your own SSH key or fix an existing Git identity.

Disconnect GitHub Developer

In Web or Electron Desktop, open Connect Apps, find GitHub Developer, and select Disconnect. Confirm the GitHub account shown for the selected Matrix computer. Terminal shows the sign-out result. When you return to Connect Apps, the card rechecks the current GitHub CLI account.

Your SSH keys and Git commit identity stay on the computer. Git operations that authenticate directly with an existing SSH key can still work. To reconnect, select Connect and complete GitHub authorization again.

What belongs to you

The setup keeps developer credentials and identity inside the owner's Matrix home:

  • GitHub CLI credentials live in .config/gh.
  • SSH keys and Matrix's pinned GitHub host-key configuration live in .ssh.
  • The confirmed commit name and email live in .gitconfig.

GitHub CLI detects an existing public key or creates and uploads a new public key. Matrix never asks for, reads, or uploads a private key. Matrix also does not copy the GitHub token, SSH key, or Git identity into a platform credential database.

If Git identity is missing, setup proposes the GitHub display name or login and GitHub's private commit-address form, <id>+<login>@users.noreply.github.com. Review both values before saving them. Coding-agent commits stop safely when a valid owner identity is unavailable instead of falling back to a generic Matrix author.

New managed GitHub clones use canonical SSH remotes. Existing HTTPS remotes remain unchanged and continue through GitHub CLI's credential helper.

Terminal
matrixos project add github.com/owner/repo

Project import validates repository URLs, stages clones safely, and creates a durable project record before worktrees, sessions, or reviews attach to it.

Repository actions in Bot and Chat

This requires a computer release that includes the Bot and Chat GitHub tool, in addition to the owner setup above. First connect an available model source in Agents & providers, then choose the conversation you intend to use:

  • Ordinary Chat: The floating Message Matrix widget opens ordinary Chat. Its default Supervised mode does not offer github_developer. For this workflow, open a private Chat and choose Full access from its permission control with a supported model from Matrix AI or your connected ChatGPT subscription. If that mode or tool is unavailable, check Agents & providers and your computer version.
  • Matrix Bot: In Chat's sidebar, select the + beside Agents (labelled Add new agent), find Matrix Bot, and select Set up bot. Review Name and Bot model, choose an available model and funding source, then select Create bot. Task executor can stay on Bot tools only. The resulting direct conversation shows Bot controls, the bot's name, and Details. Custom Bots also need the GitHub developer capability.

Choose the model source separately for ordinary Chat and each Bot. ChatGPT subscription requests use your connected Electron device, which must stay online while they run. An expired Preview allowance does not fall back to paid credit.

In either conversation, ask it to use github_developer to check access, clone a GitHub repository into its workspace, create a development branch, commit selected files, push, and open a draft pull request. A connected label or a successful access check does not verify the full repository workflow.

You approve each GitHub action other than the access-status check through the conversation's approval prompt. Review the account, branch, commit identity, and files before approving. If repository contents or identity change while approval is pending, request a fresh action. Mutations in supervised Chat, group conversations, and background Bot runs are not supported.

GitHub operations run on your computer using your confirmed owner identity. The tool does not expose GitHub credentials to the model. GitHub login and SSH setup use the owner’s credentials on the selected computer. Existing HTTPS origins are preserved. Linked worktrees and repositories with executable Git configuration are not supported by this bounded tool; use your owner Terminal for those advanced workflows.

Existing-file edits require a fresh content hash. Your computer retains the previous file in an owner-only .artifact-recovery folder, with up to 64 recovery slots. Review and remove individual slots in your owner Terminal when needed; there is no automatic purge. Capture and publication briefly leave the target path absent. Concurrent edits or an uncertain outcome require owner reconciliation before another attempt.

Recovery and removal

If any readiness check is incomplete, reopen the setup terminal and rerun matrix-github-developer-login, then refresh the settings page. A failed or cancelled run can leave partial owner-local setup, but it does not make Matrix report the workflow as ready.

On older computer configurations, retained Terminal sessions may still share mirrored tab focus between clients. If you use manual GitHub setup, use one active Terminal client. Preserve your work before changing sessions or configuration; an update does not automatically reset or migrate those retained sessions. Any migration is a deliberate owner action. If the prompt is blank or input appears unresponsive, check the active Terminal connection before retrying login; do not assume the previous attempt had no effect.

Signing out of Matrix does not sign GitHub CLI out of the computer. Developer logout and SSH-key removal are explicit owner actions: use GitHub CLI in the computer terminal to sign out, and use GitHub's SSH key settings when you want to revoke or delete a key. Matrix does not provide automatic key rotation or deletion in this release.

Rich GitHub API automation is deferred. Notifications, issue actions, pull-request detail APIs, and similar connected-app actions are not part of developer access; use Git and GitHub CLI for the supported clone, commit, push, and pull-request workflow.

Local CLI launch

Run the Matrix CLI from your laptop without a global install:

Terminal
npx --yes @finnaai/matrix login --profile cloud
npx --yes @finnaai/matrix run -it -- claude

With pnpm:

Terminal
pnpm dlx @finnaai/matrix login --profile cloud
pnpm dlx @finnaai/matrix run -it -- claude

Both runners use ~/.matrixos/ for profiles and auth, so the login is reused if you later install the CLI permanently. To preview a web app running on your Matrix computer, start the dev server in a Matrix shell and forward it locally:

Terminal
npx --yes @finnaai/matrix forward 5173
open http://127.0.0.1:5173

Installing tools

Your Matrix VPS is your own Linux machine. The matrix user has passwordless sudo, so you can install operating-system packages directly:

Terminal
sudo apt-get update
sudo apt-get install -y jq ripgrep

Developer CLIs that are not available from Ubuntu's default package repositories are installed with Homebrew on Linux:

Terminal
brew install yq
brew install charmbracelet/tap/glow

Baseline developer tools such as Git, Homebrew, Graphite CLI, and GitHub CLI are installed automatically on new Matrix VPSes. New Matrix VPSes also include cmatrix as a terminal animation you can run from any Matrix shell session.

Data ownership

Your workspace data belongs to you. Source repositories live under ~/projects, session records live under ~/system/sessions, transcripts live under ~/system/session-output, and review state lives under ~/system/reviews.

Matrix OS treats these files as the source of truth. Exports include owned project, task, session, transcript, review, preview, and activity records. Deleting workspace data is owner-scoped and does not depend on a shared platform database.

Worktrees

Each branch or pull request can get an isolated git worktree with a stable Matrix worktree ID. That keeps long-running agents, human shell sessions, and review loops from fighting over the same checkout.

Terminal
matrixos worktree create my-project --pr 42
matrixos session start --project my-project --agent codex

Dirty worktrees require explicit cleanup. Matrix OS tracks leases so two writers do not mutate the same worktree at the same time.

Session sharing

Coding sessions are durable workspace objects. You can attach as the active operator, observe without taking control, take over when needed, duplicate panes, or hand a session to a local terminal.

Session transcripts are retained with bounded replay caps, so reconnecting from web, desktop, CLI, or TUI can show recent output without keeping unbounded process output in memory.

Review loops

Review loops coordinate reviewer and implementer agents through explicit control files and review records. Each round records findings, transitions, verification status, and operator decisions.

The operator can approve, stop, or advance a loop. Matrix OS treats parse failures, stalled convergence, and failed verification as visible states instead of hiding them behind generic agent output.

Browser IDE

The Browser IDE is code-server running privately on the user's VPS and exposed through the authenticated Matrix platform proxy. It opens the same files that agents and terminal sessions edit.

Editor assets and WebSocket traffic stay behind Matrix authentication. Platform credentials are stripped before requests reach code-server, and cache-control headers prevent protected editor responses from being cached publicly.

Sandboxing

Sandboxing starts with a non-root runtime and preflight checks for required tools such as bubblewrap, git, GitHub CLI, Zellij, tmux, and supported agent CLIs.

Agent launches fail closed when a requested sandbox cannot be prepared. Health output reports workspace, session, review, sandbox, and Browser IDE status without exposing filesystem paths, provider names, secrets, or raw internal errors.

How is this guide?

On this page