Claude Code in the cloud: move your project to Matrix

To run terminal-based Claude Code independently of your laptop, put the repository and Claude process on a computer that remains running. In Matrix, provision a cloud computer, open its Terminal, authenticate GitHub and Claude there, prepare your project, and test a small task before leaving a longer one unattended.

This guide explains what moves, what stays separate, and how to prove the setup works. You can use the graphical route throughout; the optional CLI steps were checked against Matrix CLI 0.3.22. No running local conversation is automatically teleported by cloning a repository.

What does “Claude Code in the cloud” mean?

The model and the machine running its tools are different things. A model can be served remotely while Claude Code still reads files and runs tests on your laptop. To keep those tools working while that laptop sleeps, their execution has to happen elsewhere.

Anthropic documents both Remote Control and cloud sessions. Remote Control keeps execution on its host; cloud sessions move execution to cloud infrastructure. Matrix is another place to run the terminal tool, with a workspace around it. Choose the workflow that fits rather than assuming all remote interfaces move computation.

01 · YOUR DEVICE

A window into the work

Matrix Desktop, Web Desktop or the Matrix CLI sends input and shows output. Closing this viewer does not power off the cloud computer.

02 · MATRIX COMPUTER

Where tools execute

Your Linux environment holds the repository, dependencies, terminal processes and output files. Claude Code runs its tools here.

03 · AI ACCESS

Where inference is served

The configured AI service handles model requests. Its account, usage limits and charges still apply separately from Matrix compute.

What moves to Matrix, and what does not?

A successful migration moves a reproducible development environment, not your entire laptop.

Keep the original project available until the remote copy builds, tests and produces a result you can review. Do not sync an entire home folder, upload laptop private keys, or copy node_modules from macOS into Linux.

Step 1: choose and provision your Matrix computer

Download Matrix Desktop, install it and sign in. The browser handles account approval, computer selection and Checkout; return to Desktop when the computer is ready. You can also open an existing computer through Matrix on the web. The quickstart covers the full onboarding flow.

Always-on starts at $20/month on Starter, with one agent/task at a time. Builder is $100/month and adds capacity for three parallel agents. Max is $200/month for larger workloads. AI subscriptions and usage are separate; check the selected plan, supported access source and terms at current pricing and Checkout.

The first eligible primary computer has a 3-day trial, card required and $0 initially. Billing starts automatically at the selected price after the trial unless you cancel first. Additional computers and previous subscribers are not eligible for another trial.

Select Claude Code in the developer-tools step if offered for your computer. Installation can finish after core provisioning; computer readiness and tool readiness are separate checks.

Step 2: open the Terminal where work will run

In Web Desktop or Electron Desktop, select the intended computer and open Terminal. Create a tab for this project. Run these commands there, not in your laptop terminal:

pwd
uname -s
node --version
git --version
claude --version

Expect the remote operating system to be Linux. Match your project's required Node/Python/runtime version rather than assuming the preinstalled version is right. If Claude is missing, wait for your selected tool installation or follow the official installation instructions.

Optional: attach from your laptop's CLI

After installing the Matrix CLI, run locally:

matrix --version
matrix login --profile cloud
matrix doctor
matrix shell new --project main --name cloud-setup --attach

Approve the device through the browser. The last command opens a remote terminal tab in the main workspace. Everything typed inside that attached tab executes on Matrix. In another local terminal, matrix shell ls lists tabs and their IDs. Keep the workspace and tab ID for reconnecting.

Older guides may show named-session commands. In CLI 0.3.22, terminal tabs use --project and --tab; check matrix shell connect --help if your installed version differs.

Step 3: authenticate GitHub on the remote computer

For a GitHub repository, run this inside the Matrix Terminal:

gh auth login --hostname github.com --git-protocol https --web
gh auth setup-git

Follow GitHub's browser flow and grant only the repository access needed. An account that can sign in to Matrix is not automatically signed in to GitHub. An organization's SSO policy may require an additional approval.

Then clone your repository. Replace OWNER/REPO with its actual path:

mkdir -p ~/projects
cd ~/projects
git clone https://github.com/OWNER/REPO.git
cd REPO
git status --short
git remote -v

If the repository already exists on this computer, inspect it before cloning or changing branches. For work that exists only on your laptop, save it to a reviewed branch in your private repository or transfer a reviewed patch. A new clone includes pushed commits, not unsaved files or unpushed work.

Step 4: reproduce the project environment

Follow the repository's setup instructions. Keep package manager and runtime versions consistent with its lockfiles. For a project using pnpm, an example is:

pnpm install --frozen-lockfile
pnpm test

Run the project's actual test command if different. First establish the baseline: distinguish a test already failing after setup from a regression the agent introduces. A lockfile error often means the selected package manager or runtime is wrong; do not regenerate it merely to make installation pass.

Create the required development configuration on Matrix. Use the project's .env.example to identify variables, supply the minimum development credentials, and avoid production databases. localhost now refers to Matrix, so a database on your laptop does not appear there automatically. Recreate disposable test data or set up an authorized private connection deliberately.

Step 5: sign in to Claude and start a bounded task

In the remote repository directory:

claude

Follow Claude's supported login. Check the selected account and available usage. Do not assume your local sign-in, subscription or API key has moved with the code. Remote Control and other optional features can have different access requirements from the terminal tool.

Give Claude an explicit contract:

Work only on this repository's one failing test.
First reproduce it and explain the cause.
Make the smallest implementation change that preserves the test's intent.
Run the relevant tests and save a short result summary in cloud-task-result.md.
Stop for my review. Do not commit, push, merge or deploy.
If authentication, a required dependency or an approval is missing, tell me.

Watch the start to resolve setup and permission prompts. An always-on computer cannot turn an unanswered approval into permission. Leave a task with a defined stopping point and inspect its result before expanding its scope.

No suitable repository yet? Try this small exercise

In a new empty directory on Matrix, create these two files. The implementation deliberately mishandles surrounding and repeated whitespace.

export function slug(text) {
  return text.toLowerCase().replaceAll(' ', '-');
}

import assert from 'node:assert/strict';
import test from 'node:test';
import { slug } from './slug.mjs';

test('keeps an existing slug', () => {
  assert.equal(slug('matrix-os'), 'matrix-os');
});
test('normalizes whitespace and case', () => {
  assert.equal(slug('  Matrix  OS  '), 'matrix-os');
});

Run node --test slug.test.mjs to see the failing baseline. Ask Claude to fix only slug.mjs without weakening the tests, then rerun the command yourself. This is a controlled exercise, not a benchmark or customer result.

Step 6: prove disconnection and reconnection separately

Terminal attachment and conversation recovery solve different problems. First verify the computer can make progress while your viewer is disconnected, without depending on a model request.

In the Matrix Terminal, run:

node -e 'let n=0; const t=setInterval(()=>{console.log(new Date().toISOString(), ++n); if(n===12) clearInterval(t)},5000)'

This prints twelve timestamps over roughly one minute. Close the viewing client while it runs; do not shut down the Matrix computer or terminate the tab. Reopen the same computer and Terminal tab and inspect the later timestamps. If you use the CLI, detach with Ctrl-\ twice quickly, then run locally:

matrix shell ls
matrix shell connect --project main --tab YOUR_TAB_ID

Replace YOUR_TAB_ID with the actual tab ID listed under main; for a project workspace, use that project's name or ID instead. Reconnecting must select the existing tab. Creating another tab does not recover the old process.

The timestamp exercise proves remote execution while disconnected. It does not prove Claude completed its job. Repeat the disconnect/reconnect check with the bounded agent task, then inspect its result and test output. It may have finished, failed, or paused for input.

Step 7: preview and review what changed

Start your app using its documented development command on Matrix. For example, a pnpm project might use pnpm dev; check the actual port printed in its output. From a separate terminal on your laptop, forward that port:

matrix forward 3000

Use the app's real port instead of 3000 if different, then open http://127.0.0.1:3000 locally. Here, the local loopback address reaches the forwarded service on Matrix. Keep the forwarding command running. Do not expose an unauthenticated development server publicly to make previewing work.

Before accepting a code change, run inside the remote repository:

git status --short
git diff --check
git diff --stat
git diff

Rerun the test command established in Step 4. Read cloud-task-result.md, verify the UI where relevant and look for unrelated changes. Keep commits, pushes and deployment as deliberate review steps. A model saying “done” is not the acceptance criterion.

What happens after a restart, error or usage limit?

A reboot stops processes. Disk-backed code and saved output can remain, while an active process or connection needs recovery. If Claude exited, reopen the correct remote repository and use its supported conversation selector:

claude --resume

Choose the intended history if available. If the history is absent, start with your saved task summary, branch, diff and test output. Do not copy credential files or claim the previous conversation was recovered merely because the repository is present. Anthropic's session documentation describes the current continuation controls.

Add parallel work only after one task works

A second agent needs its own worktree, branch, terminal tab, ports and development database. Starter supports one agent/task at a time; select a plan that fits the parallel workload. Use the Claude Code and Codex parallel guide for the next step.

A recurring workflow also needs a scheduler, credentials, a clear action boundary and failure handling. Verify the configured Hermes workflow or Symphony setup before relying on it. Moving a terminal process does not automatically install integrations, notifications or a schedule.

Your migration is ready when these checks pass

• The intended repository, branch and setup instructions are present on Matrix.
• GitHub and Claude authenticate on that computer with the access the task needs.
• Dependencies install and the baseline tests are understood.
• A later timestamp confirms execution while the viewer is disconnected.
• You reconnect to the same tab and inspect the actual task result.
• The diff, tests and preview meet the acceptance criteria.

Start with Matrix Desktop, then follow the quickstart. If you already have a computer, open it and migrate one small project before moving a larger workflow.