Quickstart
Set up a working Matrix OS computer with the guided prompt or manual steps. Choose your install path, open the workspace, and run your first task.
Maintained by the Matrix OS team. Product instructions are updated with the supported workflow.
This guide walks you through the two Matrix OS install paths: managed Matrix Cloud, or a manual VPS install for operators who want to bring their own Linux server.
Choose your install path
Managed Matrix Cloud
Matrix provisions the cloud computer, routing, auth, updates, backups, billing, and integrations. This is the recommended path for daily work, teams, and pilots.
Manual VPS install
Run the main-domain installer on an apt-based Linux VPS you control. You operate DNS, TLS, backups, upgrades, integrations, and server security.
Manual installs can start from a server IP
A domain is optional for first boot. For long-running public use, put the instance behind DNS plus TLS, Tailscale, Cloudflare Access, or another trusted edge.
Fastest path: paste the setup prompt
If you prefer to hand setup to an agent, paste this prompt into Claude Code, Codex, or another terminal agent after your Matrix computer is provisioned:
Help me finish setting up my Matrix OS cloud computer.
Steps:
1. Install the CLI if it is not already present: npm install -g @finnaai/matrix or brew install finnaai/tap/matrix.
2. Run matrix login --profile cloud and approve the device in the browser tab that opens.
3. Verify with matrix doctor and matrix whoami.
4. Create one remote terminal: matrix shell new --project main --name setup --attach.
5. Inside that remote terminal, run matrix-github-developer-login. Let me complete GitHub's browser login and confirm or edit the proposed commit identity.
6. Ask me to confirm the repository URL. Clone it under ~/projects using its canonical SSH URL. Install dependencies using its lockfile and run its documented baseline checks.
7. Start claude or codex from the cloned directory in that remote terminal. Complete the tool's own login and give it one bounded task that stops for review.
8. For reconnection, run matrix shell ls, then matrix shell connect --project main --tab YOUR_TAB_ID using the real existing tab ID. Do not create a replacement tab and call that recovery.
Do not scan my local machine for credentials. Do not upload local private keys. Everything authenticates through its own browser/device flow or a Matrix-managed key inside the runtime.Use Ctrl-\ Ctrl-\ to detach from an attached terminal session without killing the remote process.
Manual setup
If you prefer to perform each step yourself instead of handing the flow to an agent, use the managed cloud walkthrough below. For a VPS you operate directly, follow the self-host guide.
Managed setup
Create your account
Go to app.matrix-os.com and sign up with your email or a social provider. Choose your Matrix handle — it becomes your identity across the OS and the Matrix protocol (@handle:matrix-os.com). You do not need a credit card at this step.
Choose compute power and region
Choose a plan and an available region in onboarding. Compare the resources and features shown for each plan against the work you want to run, such as a single coding task or several parallel agents.
See current plans and pricing for the latest options. Before confirming, review the selected plan, billing interval, trial eligibility and total in Checkout. Checkout shows the price you will pay.
Plan preselect from the pricing page
If you clicked a plan on the matrix-os.com pricing page before signing up, that plan is already highlighted in the picker.
Complete billing
If this is your first primary Matrix computer, Checkout offers a 14-day free trial on Starter, Builder, or Max. A card is required, but the order summary shows $0 today, the exact first-charge date, and the selected monthly or annual price that begins after the trial. During this 14-day trial, your saved card is charged when the trial ends unless you cancel before the displayed date; Stripe automatically charges only the selected price shown at Checkout.
Complete Stripe Checkout to save the card. Matrix may begin preparing your selected computer while Checkout is open, but it waits for the signed Stripe subscription webhook before granting access. Returning to the success page does not activate the computer by itself, and the payment-settling state typically resolves in under a minute.
Checkout continues without interruption if early preparation is not available. Matrix automatically starts or resumes provisioning after payment is authorized. You do not need to choose your setup or start provisioning again; onboarding—including browser approval opened by the CLI or Desktop app—moves directly to passive build progress and continues automatically when your computer is ready.
One trial per Matrix account
The trial applies only to your first primary computer. Additional computers, previous subscribers, and later subscriptions begin billing immediately.
Pick your developer tools
Before provisioning starts, Matrix asks which coding tools you want pre-installed on your computer: Codex, Claude Code, OpenCode, and Pi.
Wait for provisioning
Matrix provisions your computer in the cloud and gets it ready. The onboarding screen tracks progress through four stages: creating, booting, registering, and finalizing. After payment, this is a passive progress screen rather than another setup decision. This usually takes a few minutes.
Do not close the tab
Keep the browser tab open while provisioning runs. If you close it you can return to app.matrix-os.com and the screen picks up where it left off.
Land in the web shell
When provisioning finishes, Matrix opens the web shell. Open a Terminal tab first — it is the primary surface for the next steps. Canvas, files, preview, and Symphony are available from the sidebar once your developer basics are in place.
Authenticate GitHub
In 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 checking the account, SSH, and commit identity.
To set up GitHub manually inside a Terminal tab, run:
matrix-github-developer-loginFor manual setup, complete GitHub’s browser authorization and confirm or edit the proposed commit name and email in Terminal. This is separate from using Continue with GitHub to sign in to Matrix. See GitHub developer access for ownership and recovery details.
Clone a repository
mkdir -p ~/projects
cd ~/projects
git clone git@github.com:owner/repo.gitReplace owner/repo with your target repository. New managed GitHub clones use SSH; existing HTTPS remotes remain supported without being rewritten.
Next steps
Matrix CLI
Install the CLI on your laptop to attach to shell sessions, sync files, and run coding agents from your local terminal.
Self-host
Install Matrix OS on your own Linux VPS with the main-domain server installer.
Web shell
Learn Terminal tabs, Canvas mode, the app sidebar, and shell keyboard shortcuts.
How is this guide?

