# CLI (/docs/cli) The Matrix CLI is a single binary installed as `matrix`, `matrixos`, and `mos`. Use it to log in, attach to terminal sessions, sync files, forward ports, and run commands on your Matrix computer from any local terminal. ## Install [#install] **Install the CLI** ```bash # Homebrew (macOS / Linux) brew install finnaai/tap/matrix # npm (requires Node.js 20+) npm install -g @finnaai/matrix # Standalone binary — no Node.js required curl -fsSL https://get.matrix-os.com | sh ``` **Verify** ```bash matrix --version matrix doctor ``` You can also run without installing using `npx --yes @finnaai/matrix ` or `pnpm dlx @finnaai/matrix `. Auth tokens are stored in `~/.matrixos/` and reused across invocations. ## Connect a coding agent over MCP [#connect-a-coding-agent-over-mcp] The [Streamable HTTP integration with browser OAuth](/docs/mcp) does not need a local Matrix CLI, but is not yet enabled. Use stdio until hosted rollout and browser sign-in are verified. The stdio alternative remains available in Matrix CLI 0.3.16 and later. It runs a local bridge but executes tools on Matrix. Sign in, then configure your agent to launch the server command: ```bash matrix login --profile cloud matrix mcp serve --profile cloud ``` The second command is launched by your coding client as a stdio server. For clients with an `mcpServers` JSON configuration, merge this entry into the existing configuration after completing CLI login: ```json { "mcpServers": { "matrix": { "command": "matrix", "args": ["mcp", "serve", "--profile", "cloud"] } } } ``` Ensure `matrix` is on the coding client's PATH, or use its absolute executable path. Clients with another configuration format need the same command and argument list. This connection uses your CLI profile; it does not use HTTP OAuth or the hosted plugin. Configure one Matrix connection per client to avoid duplicate tools. The server uses your existing Matrix CLI login and exposes remote tools for: * listing the Matrix computers your account can access; * running a captured command on an explicitly selected computer; * listing and creating persistent zellij terminal sessions and tabs; * selecting a terminal tab and sending input to it; * listing, reading, downloading, and uploading bounded files in Matrix home; and * listing, searching, and reading Matrix chats. Call `list_computers` first. Every other tool requires the computer's `runtimeSlot`, even when you only have one computer. Matrix credentials stay in the CLI profile and are never passed as MCP tool arguments. Tab creation returns a stable tab ID. Pass that ID to `select_terminal_tab`; the displayed tab position can change when other tabs are created, closed, or reordered. A process is a running program on a computer. Use `run_command` for a bounded, one-shot process whose output and exit status should be returned to the agent. Use a named terminal session and tab for a long-running or interactive process that should stay visible and reconnectable in Matrix. MCP file transfer is content-only: it does not grant access to paths on the coding agent's host. Text reads are limited to 256 KiB, binary transfers to 1 MiB, directory listings to 500 entries, terminal input to 60,000 bytes, and chat pages to 100 items. Uploads do not overwrite an existing file unless `overwrite` is explicitly enabled. The MCP server routes its own tools to Matrix. It cannot disable or replace any local shell tool that the coding-agent host separately provides. ## Log in [#log-in] ```bash matrix login ``` This opens a browser for the device authentication flow. If you do not have a Matrix account yet, `matrix login` waits while the browser walks you through signup, checkout, and provisioning. After Checkout, Matrix keeps the device request active, shows build progress, and continues automatically when your computer is ready. You will not be asked to choose tools or start the build a second time. Approve the CLI in that same browser tab once provisioning finishes. **Flags** | Flag | Description | | ------------------ | ---------------------------------------------------------------- | | `--profile ` | Authenticate into a specific named profile | | `--platform ` | Override the platform URL (default: `https://app.matrix-os.com`) | | `--gateway ` | Override the gateway URL written into the profile on success | **Local development shortcuts** ```bash # Skip the device flow; writes a stub token for a local dev stack matrix login --dev # Equivalent — uses the "local" profile and localhost endpoints matrix login --profile local ``` `--dev` expects the local gateway running without `MATRIX_AUTH_TOKEN` (any bearer is accepted in that mode). ## Run agents [#run-agents] `matrix run` starts a command on your Matrix computer and, with `-it`, attaches an interactive terminal to it. ```bash matrix run -it -- claude matrix run -it -- codex ``` Use `--session` to give the session a name so you and other agents can reattach to it later: ```bash matrix run -it --session setup -- gh auth login matrix run -it --session setup -- claude matrix run -it --session review -- opencode ``` **Flags** | Flag | Description | | ------------------- | --------------------------------------------------- | | `-it` | Interactive — attach a TTY to the remote command | | `--session ` | Create or attach a named session (requires `-it`) | | `-C`, `--cwd ` | Working directory inside the Matrix home | | `--no-mouse` | Drop mouse escape sequences before forwarding input | Non-interactive runs (without `-it`) capture stdout and stderr and print them locally. Exit code is forwarded from the remote process. When you pass `--session ` and a session with that name already exists, `matrix run -it` attaches to the existing session instead of failing. This means multiple team members or agents can all connect to the same named context. ## Connect to sessions [#connect-to-sessions] Your sessions live on your Matrix computer. The same sessions you see in the web shell are available from the CLI. ```bash # List sessions matrix shell ls # Connect to an existing session matrix shell connect main # Create a session if it does not exist, then connect matrix shell connect -c setup # Create a new session without attaching matrix shell new work # Create and attach immediately matrix shell new work --attach # Remove a session matrix shell rm old-session --force ``` `connect` and `attach` are aliases for the same subcommand. Pass `-c` (`--create`) to create the session if it does not exist before connecting — this is the recommended pattern for agent setup sessions. Detach without stopping the session: press `Ctrl-\` twice quickly. Reconnect any time with `matrix shell connect `. If `matrix run -it`, `matrix shell new`, or `matrix shell attach` fails to start a session, run `matrix shell ls` and connect to an existing session rather than retrying the same create path. ## File sync [#file-sync] The sync daemon mirrors a local folder against your Matrix home directory and runs as a background service. ```bash # Start syncing ~/matrixos (default local folder) matrix sync # Start syncing a specific local path matrix sync ~/my-projects # Scope sync to a subtree on the Matrix side matrix sync ~/work --folder projects # Check sync status matrix sync status # Pause and resume matrix sync pause matrix sync resume ``` `matrix sync` installs and starts the daemon on first run. Subsequent calls with the same path reuse the running daemon without restarting it. **Flags** | Flag | Description | | ----------------------- | ------------------------------------------------------------------------ | | `-p`, `--path ` | Local folder to sync (default: `~/matrixos/`) | | `-f`, `--folder ` | Gateway subtree to scope sync to. Default: full mirror of your sync root | ## Upload and download single files [#upload-and-download-single-files] Use `matrix upload` and `matrix download` for one-off file transfers without starting or touching the sync daemon. ```bash matrix upload ./README.md projects/demo/README.md matrix upload --force ./config.json system/config.json matrix upload --secret ./api-key.txt system/secrets/api-key.txt matrix download projects/demo/README.md ./README.remote.md matrix download --force projects/demo/README.md ./README.remote.md ``` **Flags (both commands)** | Flag | Description | | ---------- | ------------------------------------------------------------ | | `--force` | Overwrite the destination if it already exists | | `--secret` | Mark the file as secret on upload (affects storage handling) | ## Port forwarding [#port-forwarding] `matrix port forward` (or the top-level `matrix forward` alias) opens a local loopback listener and tunnels it to a port on your Matrix computer. The local listener always binds to `127.0.0.1`. The remote target must also be a loopback address on the Matrix computer. **Spec format** ``` # local and remote port are the same :: ``` Valid remote hosts: `127.0.0.1`, `localhost`, `[::1]`. **Examples** ```bash # Forward local 3000 to Matrix computer 127.0.0.1:3000 matrix port forward 3000 # Forward local 8080 to Matrix computer port 3000 matrix port forward 8080:127.0.0.1:3000 # Same via the top-level alias matrix forward 3000 # Forward a Vite dev server running on the Matrix computer matrix port forward 5173 ``` After the forwarding is active, open `http://127.0.0.1:` in your local browser. The command keeps running until you press `Ctrl-C`. The target service must already be running on the Matrix computer before forwarding traffic to it. Attach a terminal session to start your dev server there, then run `matrix port forward` in a separate local terminal. ## GitHub auth inside a Matrix session [#github-auth-inside-a-matrix-session] Run `gh auth login` inside a Matrix terminal session rather than on your local machine. This registers credentials on the Matrix computer where your agents and workflows run. ```bash matrix run -it --session setup -- gh auth login ``` When `gh auth login` generates an SSH key in the shell, choose a password (passphrase) for it — don't leave it empty. The key lives on your Matrix computer; a passphrase keeps it protected. ## Status and diagnostics [#status-and-diagnostics] ```bash # Show active profile, gateway URL, and auth state matrix status # Show the authenticated Matrix identity matrix whoami # Run all health checks and print fix-it hints matrix doctor ``` `matrix doctor` checks profile config, auth token validity, the local sync daemon, gateway reachability, and the shell backend. Run it before filing a support issue. ``` $ matrix doctor OK profile OK auth FAIL daemon - Start sync with `mos sync`. OK gateway OK shell-backend OK protocol ``` ## Global flags [#global-flags] Most commands accept these flags: | Flag | Description | | ------------------ | ------------------------------------------------------------------ | | `--profile ` | Use a named profile (default: active profile from `profiles.json`) | | `--gateway ` | Override gateway URL for this invocation | | `--platform ` | Override platform URL for this invocation | | `--token ` | Override auth token (useful in CI) | | `--dev` | Shorthand for `--profile local` | | `--json` | Emit machine-readable JSON (NDJSON for streaming commands) | # Coding Agents (/docs/coding-agents) Matrix OS runs coding agents on your Matrix computer, not on your laptop. The agent gets the same shell, files, repository, dev server, and Matrix skills that you see in the web shell — and it keeps running after you close your browser. ## Supported agents [#supported-agents] Four coding agents are supported: Hermes is the always-on Matrix chat agent, not a coding agent you install from the Terminal menu. See [Hermes](/docs/hermes) for details. ## Installing an agent [#installing-an-agent] The Terminal `+` menu shows all four agents and whether each one is installed on your Matrix computer. If an agent is missing, clicking it opens a new shell tab and runs the npm installer there so you can watch the output. The install command that runs is: ```bash export MATRIX_NODE_PREFIX="${MATRIX_NODE_PREFIX:-/opt/matrix/runtime/node}" npm install -g --prefix "$MATRIX_NODE_PREFIX" ``` Each agent maps to an npm package: | Agent | Package | | ----------- | ---------------------------------------- | | Claude Code | `@anthropic-ai/claude-code@latest` | | Codex | `@openai/codex@latest` | | OpenCode | `opencode-ai@latest` | | Pi | `@earendil-works/pi-coding-agent@latest` | The default node prefix is `/opt/matrix/runtime/node`. Set `MATRIX_NODE_PREFIX` in your environment to use a different location. ### Claude Code quick start [#claude-code-quick-start] Open Terminal, click `+`, and select **Claude Code**. If it is not installed yet, Matrix opens a visible installer tab. Wait for it to finish, then select **Claude Code** again. Complete Claude Code's own browser login in the terminal. Keep account credentials in that provider-owned login flow. Start a new named Claude Code session for your project. It keeps running on the Matrix computer when you disconnect. ### Let a local agent operate Matrix [#let-a-local-agent-operate-matrix] On your local computer, install the public Matrix OS pack when you want an agent to connect to Matrix through the CLI. Matrix's website delegates to the pinned [skills.sh CLI](https://skills.sh/docs) and installs all three focused skills globally for detected agents: ```bash curl -fsSL https://matrix-os.com/install/skills | sh ``` Start a new Codex, Claude Code, OpenCode, or Pi session afterward. The pack installs `matrix-onboarding`, `matrix-cloud-run`, and `matrix-github-project`: setup/recovery, observable cloud work, and safe GitHub checkout workflows. The separate 19-skill pack already available inside a Matrix computer teaches agents how to build and use Matrix apps. Skills teach workflows; MCP supplies executable tools. The Matrix OS plugin's hosted configuration connects to the same HTTP endpoint described below. Installing skills alone does not configure an MCP connection. The [stdio alternative](/docs/cli#connect-a-coding-agent-over-mcp) uses the Matrix CLI and its separate `cloud` login. To move an active local repository and task context into Matrix, install and use the separate `matrix-handoff` skill. It previews an exact upload scope and requires a matching approval token before transferring anything. See [Hand off an active task to Matrix](/docs/matrix-skills#hand-off-an-active-task-to-matrix). See [Matrix Skills](/docs/matrix-skills) for the three skill sets, a one-command install across all four agents, and how Agent Skills differ from [AGENTS.md](https://agents.md/) project instructions. OpenCode and Pi also document their native skill support in the [OpenCode skills guide](https://opencode.ai/docs/skills/) and [Pi skills guide](https://pi.dev/docs/latest/skills). ## Connect a local agent over MCP [#connect-a-local-agent-over-mcp] Use the separately authenticated stdio alternative while hosted MCP is disabled. After hosted rollout, connect over **Streamable HTTP** directly or through the Matrix OS plugin. See [Matrix MCP: install and connect](/docs/mcp) for client setup, browser OAuth, rollout status, and a first test. ## Running an agent [#running-an-agent] ### From the Terminal menu [#from-the-terminal-menu] Open Terminal in the web shell. Click the `+` button to open the new-session menu. Select the agent you want to run. If it is installed, a new tab opens running the agent. If it is not installed, a new tab opens running the installer instead. ### From the CLI [#from-the-cli] Use `matrix run -it` to start an agent in a named shell session. Named sessions keep working after you disconnect. ```bash matrix run -it --session main -- claude matrix run -it --session main -- codex matrix run -it --session main -- opencode matrix run -it --session main -- pi ``` Or connect to an existing session and run the agent manually: ```bash matrix shell connect -c main cd ~/projects/my-repo claude ``` See [CLI reference](/docs/cli) for `matrix run` and `matrix shell connect` options, and [Shell](/docs/shell) for how named sessions work across devices. ## Approvals and connector requests in Chat [#approvals-and-connector-requests-in-chat] When you use a coding agent through Matrix Chat, a simple task can pause while the agent waits for permission or a response. **Waiting for your approval** or **Waiting for your response** is different from active model work. Review the pending request in the conversation before retrying the task. Connector requests may ask for a choice, a short form, or authorization in an external browser page. Choose **Allow once** only after reviewing the request. Use **Decline** or **Cancel** if you do not want to continue; you do not need to fill required fields to decline or cancel. Nothing is selected or submitted automatically, and allowing one request does not create a permanent grant. For browser authorization, check the displayed destination before opening it. Complete the connector's own authorization flow, then return to Chat to confirm. Opening the link alone does not submit your response. Do not paste account credentials into a conversation. Unanswered requests expire after about five minutes and are cancelled, not approved. Unsupported connector forms fail closed. If a run appears stuck, check for a pending request before sending the same task again: switching from polling to streaming by itself does not resolve a missing permission response. These controls require the updated Matrix runtime and Chat client. If your version shows only a spinner instead of a pending request, update both and retry the task. Terminal-launched agents continue to use their own interfaces. ## Agent credentials [#agent-credentials] Each agent requires its own credentials. Sign in through the agent's own CLI flow after the install completes — for example `claude` prompts for Anthropic account login, and `codex` and `opencode` require an API key or provider login. Sign in to each coding agent only through its own supported CLI flow. Do not paste API keys into chats, documents, or terminal output that may be shared or logged. ## Matrix skills for agents [#matrix-skills-for-agents] Matrix OS syncs a curated skill pack into each agent's skill discovery path at install time. The skills teach agents how to build Matrix apps, use the shell design system, and navigate the project layout. They are stored under `~/agents/skills/` on your Matrix computer and updated when you run `matrix sync`. # Desktop App (/docs/desktop) Matrix OS Desktop is a keyboard-first mission control where your projects, tasks, agent runs, terminals, files, and Matrix OS apps live in one window, connected to your Matrix computer. Nothing runs locally except the app itself — sign in on a new machine and everything is restored from your computer in the cloud. Download the current macOS or Linux build and follow the visual activation guide on the [Matrix OS Desktop page](/desktop). The web shell at `app.matrix-os.com` gives you the same Matrix computer from any browser. See the [Web Shell](/docs/shell) docs. ## Install and sign in [#install-and-sign-in] ### Download and install [#download-and-install] Download the latest [Matrix OS Desktop canary](https://github.com/HamedMP/matrix-os/releases/tag/desktop-canary) for your Mac, open the disk image, and drag **Matrix OS.app** to Applications. Canary builds receive updates before the stable channel, so review the release notes before installing. ### Sign in or create an account [#sign-in-or-create-an-account] Launch the app and click **Sign in with Matrix OS**. A browser window opens to approve the device. Sign in with an existing Matrix account, or create an account from that page. Matrix Desktop never handles your password. ### Start your hosted computer [#start-your-hosted-computer] New hosted users choose a plan and complete Stripe Checkout with a card. The first primary computer includes a **3-day trial**; Stripe collects the card during checkout and charges the selected plan when the trial ends unless you cancel first. Existing users with a running computer skip this step and select the computer they want to connect. After Checkout, the browser keeps the Desktop approval request active and shows progress until the selected computer is ready; there is no second setup or build step. ### Approve and return [#approve-and-return] Review the account, computer, and matching device code, then approve the connection. The browser returns you to Matrix OS automatically while the app completes authorization by polling. Your projects and board then load, and the credential is stored in the macOS Keychain without leaving the app's trusted process. The `matrixos://auth?status=approved` deep link is a focus signal only. The browser never puts a credential in the URL; Matrix Desktop finishes sign-in through the one-time device-code poll. Signing out clears the local credential and any embedded web sessions, but never touches data on your Matrix computer. ## Navigation [#navigation] The collapsible sidebar holds four primary destinations — **Home**, **Chat**, **Terminal**, and **Apps** — followed by your **Projects** list. Everything you open becomes a **tab** in the main area. Tabs are cached: switching away from a terminal never kills it, and coming back is instant. Close a tab with its close button or a middle-click; the Home tab always stays. Toggle the sidebar with **⌘B** or **⌘\\**. ## Board [#board] Open a project from the sidebar to see its kanban board with **Todo, Running, Waiting, Blocked, and Complete** columns. Drag cards between columns, right-click a card for status, priority, archive, and delete actions, and press **C** to create a task from anywhere on the board. The create dialog offers **Create** (⌘↵) and **Create + open** (⌘⇧↵). Each task opens as its own tab. Changes made on the web shell, CLI, or by agents show up in real time. ## Terminals [#terminals] The **Terminal** tab lists your named sessions, shared with the web shell and CLI — all three surfaces show the same sessions. Click a session to attach to the live shell on your Matrix computer, with scrollback intact. Terminals reconnect automatically after a network drop or sleep/wake without duplicating output. If a session has ended on the server, the terminal shows a clear ended state with a one-click recreate action. A terminal session you open in Operator is immediately available from the web shell and the CLI. See the [CLI](/docs/cli) docs for `matrix shell connect` usage. Copy and paste shortcuts, right-click **Copy** and **Select All**, mouse-aware selection behavior, and Canvas/Desktop parity are covered in the [Web Shell terminal guide](/docs/shell#copy-paste-and-selection). Electron Desktop also shares [keyboard navigation, customizable shortcuts, and Zellij pane controls](/docs/shell#keyboard-navigation-and-zellij-panes) with Web Canvas and Web Desktop. Use the pane toolbar or Command/Option shortcuts to split, focus, resize, and maximize panes inside the attached session. ## Chat conversations [#chat-conversations] Open **Chat** to find and resume saved conversations on your selected Matrix computer. Choose an available agent harness and model in the composer. Use **New chat** to start a draft, and send your first message to save the conversation. See [Chat conversations](/docs/desktop/chat-conversations) for message search and safe deletion. You can also associate a chat with one project so future turns use that project's workspace. See [Project context for Chat](/docs/desktop/chat-project-context) for setup and recovery when a workspace is unavailable. ## Task workspace [#task-workspace] Opening a task reveals a resizable panel strip — terminal, editor, git, files, artifacts, and a processes panel. Toggle panels with **⌘1–⌘6**, drag dividers to resize, and the layout persists per task. The built-in code editor has syntax highlighting for common languages, find/replace, and conflict-safe saves (it warns if a file changed on the server since you opened it). Press **⌘P** to quick-open a file by name. ## Apps [#apps] The **Apps** tab opens your Matrix OS app launcher. Click any installed app to open it as a tab in an isolated context with the same data bridge you get on the web. Open apps also appear in the sidebar under **Open apps** for quick access without going back to the launcher. ## Keyboard shortcuts [#keyboard-shortcuts] | Shortcut | Action | | --------------------------- | ---------------------------------------------- | | **⌘K** | Command palette — tasks, projects, apps, files | | **⌘J** | Toggle agent composer | | **⌘P** | Quick-open file by name | | **C** | New task (when not in a text field) | | **⌘1–⌘6** | Toggle task workspace panels | | **⌘B** or **⌘\\** | Toggle sidebar | | **⌘W** | Close current tab | | **Ctrl+Tab** | Cycle to next tab | | **Ctrl+Shift+Tab** | Cycle to previous tab | Standard macOS menus, full-screen, and window controls work as expected. ## Settings [#settings] Native settings cover **Account**, **Billing**, **Appearance** (dark/light/system), **Agent** (Hermes configuration), **Runtime** (switch Matrix computer target), **Channels**, **Integrations**, **Schedules**, and **System info**. Switching runtime re-targets every surface — board, terminals, chat, and apps. **Installed version** is the release recorded on your Matrix computer. **Running version** is the gateway process currently serving projects, terminals, and apps. System settings only says the computer is on the latest release when those values match. If they differ, or the running version cannot be verified, run `matrix instance restart` from the Matrix CLI and retry the project action after the services return. ## Updates and What's New [#updates-and-whats-new] When a release feed is configured, Matrix OS checks for eligible releases and downloads eligible updates in the background. You can keep working while the download completes. When the package is ready, a blue **Update** action appears beside your avatar in the bottom-left corner. Clicking **Update** immediately restarts Matrix OS and installs the downloaded release. There is no second confirmation dialog, so save any local text you are editing before you click it. You do not need to download another installer bundle. After the new version launches, Matrix OS automatically opens **What's New** with the release version, publication date, and release notes. It is shown automatically only once per installed version; closing the dialog acknowledges that release. Automatic updates require a signed packaged build and a configured release channel. Development builds do not install OTA releases. ## Privacy [#privacy] The app holds no durable workspace data locally: only the credential, your connection profile, window and layout state, bounded caches, and the last installed release notes. Losing the machine loses no work. ## Related [#related] # Glossary (/docs/glossary) A quick reference for the terms you'll see across these guides. ## The basics [#the-basics] **Matrix computer** — Your personal computer in the cloud. A real machine with a terminal, a file system, and an AI kernel, reachable from the web, CLI, mobile, and desktop. It keeps running after you disconnect. **Web shell** — The browser interface at [app.matrix-os.com](https://app.matrix-os.com). Your main way to use your Matrix computer: Terminal, Files, apps, and settings. **Shell / Terminal** — The command line on your Matrix computer, where you run commands, builds, tests, and coding agents. **Session** — A running terminal that lives on your Matrix computer. You can name sessions, leave them running, and reconnect from any device. Closing the browser does not end a session. **Attach / detach** — Connecting to a session (*attach*) or stepping away from it without stopping it (*detach*). In the CLI, detach by pressing `Ctrl-\` twice quickly. **Provisioning** — The first-time setup that creates and boots your Matrix computer after you sign up and choose a plan. ## Working in Matrix [#working-in-matrix] **CLI** — The `matrix` command-line tool you install on your laptop to log in, attach to sessions, sync files, forward ports, and run agents. See the [CLI guide](/docs/cli). **Sync** — Keeping files mirrored between your laptop and your Matrix computer with the CLI. **Port forwarding** — Making a port on your Matrix computer (for example, a dev server) reachable on your own machine so you can open it in your local browser. **Workspace / home** — Your files, repositories, and data on your Matrix computer (your home directory). It's yours, and it's preserved across updates. **Matrix app** — An app that runs inside Matrix OS — on the web, desktop, or mobile — with access to your data through the built-in Matrix bridge. **Desktop app (Operator)** — The native macOS app for Matrix OS: projects, tasks, agent threads, terminals, and apps in one keyboard-first window. See the [Desktop guide](/docs/desktop). ## AI and agents [#ai-and-agents] **AI kernel** — The AI at the core of your Matrix computer. With your permission it can use the shell, files, apps, and integrations. It's the operating system itself, not a chat box bolted on the side. **Coding agent** — An AI coding tool — Claude, Codex, Pi, or OpenCode — that you install and run on your Matrix computer inside a session. See [Coding Agents](/docs/coding-agents). **Hermes** — Matrix's always-on chat agent. It runs in the background and replies across web chat, mobile, and messaging channels. Hermes is model-agnostic — [pick a model](/docs/hermes) (Claude, GPT, Gemini, and more) before it can respond. **Skill** — A short instruction file that coding agents discover and use to learn how Matrix works — build conventions, UI patterns, and debug playbooks. See [Matrix Skills](/docs/matrix-skills). # Hermes and OpenClaw (/docs/hermes) Matrix OS has two separate agent layers. **Chat stays on the Matrix kernel** across the web and mobile shells. **Hermes and OpenClaw are optional messaging runtimes** for Telegram, WhatsApp, and other connected channels. Installing, configuring, or switching a messaging runtime does not replace the Matrix kernel used by Chat. If no messaging runtime is configured, Chat continues to work normally. ## Choose a messaging runtime [#choose-a-messaging-runtime] Open **Settings → Agent** to see both runtimes. One can be selected at a time: the selected runtime is highlighted as active, while the other remains installed but stopped. Matrix performs the switch and reports the resulting service health in the same panel. Hermes selected as the messaging runtime, with OpenClaw installed and stopped OpenClaw selected and healthy, with Hermes installed and stopped Runtime health and provider readiness are separate. For example, a runtime can start successfully while still showing **No providers available** until you finish its model authentication. A **Degraded** or action-required state means you should inspect the provider configuration before expecting replies from connected channels. ## Configure Hermes [#configure-hermes] Hermes is model-agnostic. Its main model handles core reasoning, and auxiliary model slots can inherit that choice or use their own providers. If Hermes is missing, select **Install Hermes** . Matrix opens a visible Terminal tab and runs the official installer. Select **Use Hermes** , then wait for the runtime cards to refresh. Choose an available provider and model, then select **Save messaging model** . Select **Configure Hermes** to manage the settings and credentials exposed by the installed Hermes version. Hermes configuration in Settings, with searchable categories and typed controls The **Configure Hermes** panel reads the configuration capabilities published by the exact Hermes version installed on your computer. Matrix currently verifies this integration against **Hermes Agent 0.20.0**. The panel renders supported boolean, number, choice, text, and list values as typed controls, and keeps changes local until you select **Save changes**. This follows the pinned Hermes [Config dashboard](https://github.com/NousResearch/hermes-agent/blob/e05eba26a3af1313d304799ffb85a11b8c2b0988/website/docs/user-guide/features/web-dashboard.md#config) and [configuration](https://github.com/NousResearch/hermes-agent/blob/e05eba26a3af1313d304799ffb85a11b8c2b0988/website/docs/user-guide/configuration.md) contracts. For model slots and supported providers, see the [Hermes model configuration docs](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models). ### Add Hermes credentials [#add-hermes-credentials] Open the **Credentials** tab to add or replace a provider credential. Secrets remain write-only: Settings shows connection state and a redacted preview, never the full stored value. Messaging channel secrets remain in their dedicated channel setup rather than being duplicated here. Hermes credentials in Settings, showing write-only provider keys and redacted status The credentials view follows the pinned Hermes [dashboard API Keys documentation](https://github.com/NousResearch/hermes-agent/blob/e05eba26a3af1313d304799ffb85a11b8c2b0988/website/docs/user-guide/features/web-dashboard.md#api-keys) and [environment-variable reference](https://github.com/NousResearch/hermes-agent/blob/e05eba26a3af1313d304799ffb85a11b8c2b0988/website/docs/reference/environment-variables.md). Hermes configuration remains owner-controlled in files under `~/.hermes/`; Settings is a renderer for that configuration, not a separate platform copy. ### Before Hermes can respond [#before-hermes-can-respond] Hermes needs both a selected main model and a usable credential for that model's provider. If either is missing, Hermes may be installed or running but cannot complete inference for connected messaging channels. Finish provider setup before using a channel to verify real replies. To verify inference independently of a messaging channel, open Terminal and ask Hermes for a deterministic response. A successful reply confirms that the selected model and its credential are working end to end: ```bash hermes chat -q "Reply with exactly: HERMES_RUNTIME_OK" ``` Hermes returning HERMES_RUNTIME_OK in the Matrix Terminal ## Install and configure OpenClaw [#install-and-configure-openclaw] Matrix OS pins OpenClaw to **2026.7.1** for this integration. Keep installation and authentication visible in Terminal so you can review prompts, errors, and the exact version being configured. If OpenClaw is missing, select **Install OpenClaw** in **Settings → Agent** . Follow the installer in the Terminal tab that Matrix opens. Return to Settings when installation completes. Select **Configure OpenClaw** . Matrix opens a Terminal flow for `openclaw models auth add` . Add a provider credential and choose a usable model inside OpenClaw. Return to Settings, select **Use OpenClaw** , and wait for OpenClaw to show as active and healthy. OpenClaw install action on the Agent settings page OpenClaw's pinned installer running visibly in Terminal OpenClaw provider authentication running visibly in Terminal This state means OpenClaw still needs model authentication or configuration. It is separate from runtime switching: complete **Configure OpenClaw**, then return to Settings and confirm both provider readiness and runtime health. ## Permissions and ownership [#permissions-and-ownership] Messaging access is default-deny. Connecting a runtime does not grant it access to every room, file, tool, or integration. * **Messages:** grant read and reply access per room. See [Messages](/docs/messages). * **Files and tools:** require explicit owner permission where the selected runtime uses them. * **Integrations:** approve each capability separately in Settings. * **Configuration:** remains in owner-controlled runtime files on the Matrix computer. ## Messaging runtimes versus coding agents [#messaging-runtimes-versus-coding-agents] | | Hermes or OpenClaw | Coding agents | | ------------------ | ----------------------------------- | -------------------------------------------- | | Primary surface | Connected messaging channels | Interactive Terminal sessions | | Always-on service | Yes, when selected and configured | No — start one per session | | Installation | Visible Terminal flow from Settings | Visible Terminal flow from the Terminal menu | | Model setup | Configure the selected runtime | Authenticate each coding agent | | Matrix Chat kernel | Does not replace it | Does not replace it | Use Hermes or OpenClaw for connected messaging channels and background message handling. Use coding agents for interactive development with persistent terminal context. See [Coding Agents](/docs/coding-agents) for installation and launch instructions. # Matrix OS (/docs)

Cloud coding computer

Matrix OS is a persistent cloud computer with an AI kernel — for developers who run AI coding agents.

Sessions keep running after your laptop closes. Reach your computer from the web shell, CLI, mobile, or desktop.

Matrix OS is a real computer hosted in the cloud. It has a terminal, a file system, persistent shell sessions, and an always-on AI kernel. You clone repos, run tests, launch coding agents, and leave long-running work running — then pick it up from any device. Matrix is not a chat window bolted onto a cloud service. The AI is the kernel: it has access to the shell, files, integrations, and skills, and it keeps working after you close the browser. ## How it works [#how-it-works] ### Provision your Matrix computer [#provision-your-matrix-computer] Sign up at `app.matrix-os.com`, choose your power level and region, complete billing, and wait for your computer to provision. Takes a few minutes. ### Open the web shell [#open-the-web-shell] The web shell at `app.matrix-os.com` is your primary interface. Open Terminal, authenticate GitHub with `gh auth login`, clone your repo, and start working. ### Connect from your laptop [#connect-from-your-laptop] Install the `matrix` CLI and run `matrix login`. Attach to persistent sessions, sync files, and run coding agents — all against the same cloud computer. ### Launch a coding agent [#launch-a-coding-agent] Start Claude, Codex, Pi, or OpenCode in a named session. The agent runs on the Matrix computer and keeps going after you detach. Pick it up later from the web, mobile, or desktop app. ## Where to go next [#where-to-go-next] Sign up, provision your Matrix computer, authenticate GitHub, and clone your first repo. Install the Matrix CLI, log in, attach to remote sessions, and sync files from your laptop. Install Claude, Codex, Pi, or OpenCode on your Matrix computer and run them in persistent sessions. The always-on Matrix chat agent. Runs in the background, responds across web, mobile, and messaging channels. ## What Matrix is [#what-matrix-is] **Persistent sessions.** Your terminal sessions keep running on your Matrix computer. Disconnect and reconnect from anywhere — long builds, agent runs, and test suites keep going. **One computer, four surfaces.** The web shell (`app.matrix-os.com`), the `matrix` CLI, the mobile app, and the desktop app all connect to the same machine and the same sessions. No re-cloning, no re-authenticating. **AI at the kernel level.** Hermes is always on. Coding agents — Claude, Codex, Pi, OpenCode — install as tools on your Matrix computer and run in named sessions. The AI kernel has access to the shell, files, apps, and integrations with your permission. **Your files are yours.** Your home directory, repos, and workspace data live on your Matrix computer. The platform handles routing, auth, and recovery. # Matrix Skills (/docs/matrix-skills) Matrix uses Agent Skills to give coding agents the right instructions for where they are running. The local computer, a Matrix computer, and the Matrix OS source repository have different jobs, so they use separate skill sets. ## How skills trigger [#how-skills-trigger] Skills support two complementary paths: * **Automatic selection:** the agent sees each installed skill's name and description, then loads the full instructions when your request matches. A request such as “make this drawer feel less janky” can select `debug-animation` without you naming it. * **Explicit trigger:** name the skill when you want to guarantee that workflow. The examples below use Codex's `$skill-name` form. In an agent that does not expose `$` invocation, say “Use `skill-name` to…” instead. You can name multiple skills when the work crosses boundaries: ```text Use $matrix-app-builder, $matrix-design-system, and $animation-accessibility to build a calm, reduced-motion habit tracker for Matrix. ``` Explicitly naming a skill selects its instructions; it does not bypass approvals, authentication, repository rules, or tool permissions. ## Three skill sets [#three-skill-sets]
## Your computer: install the public pack [#1-your-computer-install-the-public-pack] The recommended public pack lives at `plugins/matrix-os/skills/` and contains three focused skills: | Skill | When your agent uses it | Explicit example | Full instructions | | ----------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `matrix-onboarding` | Install or diagnose the Matrix CLI, sign in, select a computer, verify readiness, and recover authentication. | `Use $matrix-onboarding to diagnose why my Matrix computer is not ready.` | [Read `SKILL.md`](https://github.com/HamedMP/matrix-os/blob/main/plugins/matrix-os/skills/matrix-onboarding/SKILL.md) | | `matrix-cloud-run` | Run commands and coding-agent tasks in observable, reconnectable Matrix sessions. | `Use $matrix-cloud-run to run the test suite on my Matrix computer.` | [Read `SKILL.md`](https://github.com/HamedMP/matrix-os/blob/main/plugins/matrix-os/skills/matrix-cloud-run/SKILL.md) | | `matrix-github-project` | Clone, verify, reuse, change, and validate GitHub projects on Matrix without overwriting existing work. | `Use $matrix-github-project to clone this repository on Matrix and fix its tests.` | [Read `SKILL.md`](https://github.com/HamedMP/matrix-os/blob/main/plugins/matrix-os/skills/matrix-github-project/SKILL.md) | Install all three globally through Matrix's website: ```bash curl -fsSL https://matrix-os.com/install/skills | sh ``` The Matrix-owned endpoint is a small shell script that delegates to the pinned [skills.sh CLI](https://skills.sh/docs). `skills.sh` detects supported local agents and installs the pack into their global skill directories. Start a new Codex, Claude Code, OpenCode, or Pi session after installation so it refreshes skill discovery. Inspect the installer before running it: ```bash curl -fsSL https://matrix-os.com/install/skills ``` ### Advanced: manual skills.sh command [#advanced-manual-skillssh-command] The website command is the recommended install path. If you want to call skills.sh directly, the equivalent pinned command is: ```bash pnpm dlx skills@1.5.23 add https://github.com/HamedMP/matrix-os/tree/main/plugins/matrix-os/skills --global --all ``` To list the pack without installing it, replace `--global --all` with `--list`. Then try: ```text Use Matrix to check my cloud computer, clone this repository, and run its tests in an observable session. ``` [OpenCode](https://opencode.ai/docs/skills/) and [Pi](https://pi.dev/docs/latest/skills) support shared `.agents/skills/` discovery in addition to their own skill directories. Pi only loads project skills after the project is trusted. Skills can influence agent behavior and may include executable helpers. Review the source and the skills.sh security information before installing any third-party skill. ### Hand off an active task to Matrix [#hand-off-an-active-task-to-matrix] Install the optional `matrix-handoff` skill when you want Codex or Claude Code to move the current repository and task context into a new project on your Matrix computer: ```bash pnpm dlx skills@1.5.23 add https://github.com/HamedMP/matrix-os/tree/main/.agents/skills/matrix-handoff --global --all ``` Start a new agent session after installation, then ask it to use `$matrix-handoff`. Claude Code also exposes `/matrix-handoff` when you work from a Matrix OS source checkout. [Read the complete `matrix-handoff` instructions](https://github.com/HamedMP/matrix-os/blob/main/.agents/skills/matrix-handoff/SKILL.md). The handoff is a two-phase workflow. First, the agent previews the filtered files, optional repository-matched transcript, Matrix destination, selected coding agent, and a SHA-256 approval token. After you approve that exact scope, the agent reruns with the token. The helper stages the inputs again and refuses to upload if the repository files, continuation brief, transcript, agent, profile, or destination basis changed after preview. By default the destination keeps the repository name: `~/projects/`. If that directory already exists, handoff stops before uploading and asks you to choose another `--project-name`; it does not invent a `-handoff` suffix or overwrite the existing project. Use `--no-history` when you want to transfer only the repository and a secret-free continuation brief: ```text Use $matrix-handoff to move this task to Matrix with Codex, using --no-history. ``` The handoff excludes common credential files, private keys, `.env` files, agent auth databases, dependencies, and build output. It never copies local authentication into Matrix. Authenticate GitHub and the selected coding agent through their own browser or device flow, or use a Matrix-managed SSH key created inside the runtime.
## Matrix computer: build and use apps [#2-matrix-computer-build-and-use-apps] The runtime pack lives at `skills/matrix/` in the Matrix OS source and is available automatically on your Matrix computer. You do not install this pack with skills.sh. Matrix syncs it into supported agent discovery paths and updates Matrix-managed entries without removing user-managed skills. The complete bundled set contains 19 skills: six Matrix app skills and thirteen motion skills. App builders load `matrix-app-builder`, `matrix-design-system`, and `matrix-app-ui-patterns` first, then add only the motion skills relevant to the task. Matrix's current brand is the system frame: Teal `#0E3422`, Coral `#D06E53`, Gold `#F1C379`, Green `#BED77B`, Blue `#C5D6E2`; Bricolage Grotesque for display, Geist for body/UI, and Geist Mono for code. Generated apps also form a taste brief from your references, domain, desired personality, and density. The goal is a coherent Matrix app that reflects your taste—not the same gradients, glass, capsules, or animation style on every project. The shared Agent Skills paths make the pack available to Matrix, Claude Code, Codex, OpenCode, Pi, and other compatible runtimes running on the Matrix computer. Matrix skills do not contain provider credentials. Authenticated actions go through Matrix APIs and each provider's supported login flow. ### Complete Matrix computer catalog [#complete-matrix-computer-catalog] The catalog below lists every bundled skill. Open an entry for its selection boundary and an explicit trigger. The six Matrix foundation entries link to their public source. The thirteen motion entries are bundled-only motion guidance and intentionally do not link to their full instruction text. #### Matrix app foundation [#matrix-app-foundation] **When to use:** Build, create, fix, redesign, or publish a Matrix app. It owns the end-to-end Vite React TypeScript workflow, `matrix.json`, Matrix data access, build verification, and opening the finished app. **Explicit trigger:** `Use $matrix-app-builder to build a meal planner in Matrix and verify its production build.` [Read the complete skill text](https://github.com/HamedMP/matrix-os/blob/main/skills/matrix/app-builder/SKILL.md). **When to use:** Arrange dashboards, data views, workspaces, forms, empty states, responsive navigation, and windowed or mobile layouts. Use `matrix-design-system` for visual tokens rather than asking this skill to invent styling. **Explicit trigger:** `Use $matrix-app-ui-patterns to turn this desktop dashboard into a stable 320px mobile layout.` [Read the complete skill text](https://github.com/HamedMP/matrix-os/blob/main/skills/matrix/app-ui-patterns/SKILL.md). **When to use:** Design any Matrix system surface or user-built app. It applies the current brand as the integration frame, preserves accessibility, and derives an app-specific visual direction from the user's references and taste. **Explicit trigger:** `Use $matrix-design-system to restyle this notes app around my editorial, low-contrast references.` [Read the complete skill text](https://github.com/HamedMP/matrix-os/blob/main/skills/matrix/design-system/SKILL.md). **When to use:** Add Gmail, Calendar, Drive, GitHub, Slack, Discord, or another external service to a Matrix app or agent without copying platform credentials into the app or customer computer. **Explicit trigger:** `Use $matrix-integrations to show my upcoming Google Calendar events in this Matrix app.` [Read the complete skill text](https://github.com/HamedMP/matrix-os/blob/main/skills/matrix/integrations/SKILL.md). **When to use:** Work on Matrix, a Matrix app, or an adjacent project from a Matrix computer with hot reload, safe secret boundaries, and authenticated previews. It registers loopback servers such as `localhost:4173` in Project Preview and opens them in Matrix Browser. **Explicit trigger:** `Use $matrix-dev-vps to run this Vite app on Matrix and open its localhost preview in Matrix Browser.` [Read the complete skill text](https://github.com/HamedMP/matrix-os/blob/main/skills/matrix/dev-vps/SKILL.md). **When to use:** Investigate a blank app, `needs_build`, a missing `dist` bundle, an invalid manifest, icon 404s, console errors, CORS problems, or integration proxy failures. **Explicit trigger:** `Use $matrix-debug-app to find out why this app returns needs_build and opens blank.` [Read the complete skill text](https://github.com/HamedMP/matrix-os/blob/main/skills/matrix/debug-app/SKILL.md). #### Motion direction and discovery [#motion-direction-and-discovery] **When to use:** Make broad animation decisions or implement entrances, exits, hover and press feedback, drawers, popovers, morphs, layout transitions, SVG motion, easing, duration, and springs. It is the general motion skill when a narrower skill does not own the task. **Explicit trigger:** `Use $animate to give this command palette a crisp entrance and restrained item stagger.` **When to use:** Translate descriptions such as “the iOS rubber-band thing” or “one shape turning into another” into exact motion terms. Use it for naming and search vocabulary, not implementation. **Explicit trigger:** `Use $animation-vocabulary to name the effect where this card expands into its detail page.` **When to use:** Audit an interface before adding motion. It finds a small number of useful opportunities, explains their purpose, and names areas that should remain static. This is read-only discovery. **Explicit trigger:** `Use $find-animation-opportunities to inspect this dashboard and suggest only high-value motion.` #### Motion implementation [#motion-implementation] **When to use:** Build or fix transitions, keyframes, transforms, 3D effects, `clip-path` reveals, hover and press states, loops, marquees, spinners, or simple staggers without adding an animation library. **Explicit trigger:** `Use $css-animations to build this hover treatment and loading shimmer without a new dependency.` **When to use:** Work with `motion/react` for exit animation, layout or shared-element transitions, springs, motion values, drag, `AnimatePresence`, `layoutId`, or animated auto height—and debug the library when its abstractions misfire. **Explicit trigger:** `Use $motion-react to animate this card into the detail panel with a shared layout transition.` **When to use:** Create or repair direct-manipulation interactions that must track the pointer, remain interruptible, and settle naturally: drawers, sheets, swipe-to-dismiss, reordering, pull-to-refresh, and hold-to-confirm. **Explicit trigger:** `Use $gesture-ui to make this swipe-to-dismiss card follow the finger and snap back correctly.` **When to use:** Add or fix reveal-on-scroll, progress-linked animation, parallax, sticky storytelling, or reading progress. It also helps decide when scroll motion would hide content, retrigger annoyingly, or hijack navigation. **Explicit trigger:** `Use $scroll-animations to add a reduced-motion-safe reading progress indicator to this page.` **When to use:** Decide between CSS, WAAPI, Motion, GSAP, and React Spring, or choose accessible primitives for dropdowns, dialogs, tabs, selects, toasts, and drawers. It weighs dependencies against hand-building. **Explicit trigger:** `Use $pick-ui-library to choose an accessible drawer primitive without overloading the bundle.` #### Motion quality, accessibility, and review [#motion-quality-accessibility-and-review] **When to use:** Add or review `prefers-reduced-motion`, autoplay, loops, smooth scrolling, GIFs, video, or `useReducedMotion`. Every shipped animation should have an intentional reduced-motion result rather than merely disappearing. **Explicit trigger:** `Use $animation-accessibility to give every animation on this screen a safe reduced-motion variant.` **When to use:** Fix dropped frames or decide which properties and APIs to animate. It favors compositor-friendly work, avoids per-frame React rendering, and applies `will-change` or GPU layers only when justified. **Explicit trigger:** `Use $animation-performance to diagnose why this panel animation stutters on a mid-range phone.` **When to use:** Motion feels sluggish, robotic, cheap, flickery, lifeless, or simply “off”; elements jump or shift; an exit is skipped; or a transition does not fire. It diagnoses first, then targets the cause. **Explicit trigger:** `Use $debug-animation to explain why this popover feels wrong before editing it.` **When to use:** Audit an existing codebase's motion against the animations.dev craft bar and write a self-contained improvement plan for another agent. It is read-only on source code. **Explicit trigger:** `Use $improve-animations to audit this app and write a prioritized motion improvement plan.` **When to use:** Review a motion implementation or diff for purpose, timing, continuity, accessibility, performance, and interaction quality. It defaults to flagging concrete problems; approval is earned. **Explicit trigger:** `Use $review-animations to review this pull request's animation changes.`
## Matrix OS repository: develop the platform [#3-matrix-os-repository-develop-the-platform] The Matrix OS source repository carries its development skills under `.agents/skills/`. These are for Matrix company engineers and contributors working on the platform itself—not for operating a personal Matrix computer or building an ordinary Matrix app. This repository-scoped set covers workflows such as testing, debugging, code review, pull requests, previews, releases, native UI, authentication, and deployment. Keeping it at the repository root gives supported agents the same engineering playbooks when a contributor checks out Matrix OS. Agent Skills are reusable, on-demand workflows. [AGENTS.md](https://agents.md/) provides repository-level setup, testing, style, security, and contribution rules that coding agents read automatically. Matrix OS uses both: AGENTS.md defines the boundaries, while development skills guide specific workflows.
## Choose the right set [#choose-the-right-set] | Where the agent runs | What you want it to do | Skill source | | ------------------------- | ------------------------------------------- | --------------------------------------------- | | Your local computer | Connect to and operate your Matrix computer | `plugins/matrix-os/skills/` through skills.sh | | Your Matrix computer | Build, open, integrate, and debug apps | `skills/matrix/` | | Matrix OS source checkout | Develop and contribute to Matrix OS | `.agents/skills/` | # Matrix MCP (/docs/mcp) Give your coding agent a computer that keeps running. Matrix MCP lets it run commands, work with files, manage terminals, and read chats on your Matrix computer. Hosted MCP uses **Streamable HTTP** at `https://api.matrix-os.com/mcp`. Your coding agent connects directly and signs in through browser OAuth. This does not require installing the Matrix CLI. Commands and file operations run on the selected Matrix computer, not on the agent's local computer. Hosted MCP is not yet enabled for use. The HTTP-default plugin is also unavailable while the hosted service is disabled. The instructions below describe setup after operator activation and verified authentication. Before enablement, the operator must verify the OAuth provider's PKCE, consent, compatible client registration, resource audience, and `matrix:computer` scope, then test browser sign-in with Codex and Claude. Until then, use the [separately authenticated stdio alternative](/docs/cli#connect-a-coding-agent-over-mcp). ## Set up your local computer [#set-up-your-local-computer] If your release includes the local-setup page, open **Settings → Matrix CLI & MCP** in Web Canvas, Web Desktop, or Electron Desktop. The **Getting started** checklist also has a **Set up local CLI, MCP & skills** shortcut to that page. If this page is absent, use the [stdio setup](/docs/cli#connect-a-coding-agent-over-mcp) directly; the instructions below do not require a Settings shortcut. Install on your local computer, not your Matrix VPS. The page brings together CLI installation, direct MCP setup, and plugins that bundle workflow skills. Copy buttons only copy instructions; they do not run installers. Opening setup does not mark any onboarding step complete, and Matrix cannot detect local installations from this page. Run terminal commands in your local terminal and Claude slash commands inside Claude Code. On a phone, open these instructions on the computer you want to set up. The separate Services/Custom MCP and Skills settings manage connections and skills **inside Matrix**, not these local clients. ## Choose your coding client [#choose-your-coding-client] Once hosted MCP is enabled and browser sign-in has been verified, use **direct MCP** for tools only, or the **Matrix OS plugin** for tools plus workflow skills. Install one connection per client to avoid duplicate tools. Buttons open an installed desktop client and ask you to confirm. Browser OAuth and consent still follow; one click does not silently authorize computer access. On mobile, use the copyable setup on your desktop. End-to-end sign-in remains unverified until hosted rollout. ### Codex [#codex] ```bash codex mcp add matrix --url https://api.matrix-os.com/mcp codex mcp login matrix ``` Or add the server to your Codex configuration, then run the login command: ```toml [mcp_servers.matrix] url = "https://api.matrix-os.com/mcp" tool_timeout_sec = 60 ``` Use the server name shown by your client when logging in to a plugin-provided connection. See the [official Codex MCP guide](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). ### Claude Code [#claude-code] ```bash claude mcp add --transport http --scope user matrix https://api.matrix-os.com/mcp ``` Open Claude Code, run `/mcp`, select Matrix, and complete browser authentication. See the [official Claude Code MCP guide](https://code.claude.com/docs/en/mcp). Other clients need support for authenticated Streamable HTTP and a registration method compatible with the configured authorization server; a client-specific connector is not installed by the skills pack. ### Cursor [#cursor] Add Matrix to Cursor Confirm the server URL, then complete browser authentication when prompted. If the button does not open Cursor, merge this entry into your existing `~/.cursor/mcp.json`: ```json { "mcpServers": { "matrix": { "url": "https://api.matrix-os.com/mcp" } } } ``` [Cursor's install-link documentation](https://cursor.com/docs/mcp/install-links). ### VS Code / Copilot [#vs-code--copilot] Add Matrix to VS Code Confirm installation, start the server, and follow browser sign-in. Or run: ```bash code --add-mcp '{"name":"matrix","type":"http","url":"https://api.matrix-os.com/mcp"}' ``` [VS Code's MCP setup guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers). ### Other MCP clients [#other-mcp-clients] Choose a remote **Streamable HTTP** server, enter `https://api.matrix-os.com/mcp`, and authenticate through the client's browser OAuth flow. Client registration must be compatible with Matrix's authorization server. Do not select stdio or paste a bearer token into a config file. ## Install the Matrix OS plugin [#install-the-matrix-os-plugin] The plugin bundles the same MCP connection with setup, cloud-work, and GitHub-project skills. No separate Matrix CLI installation is needed for hosted tools. The hosted rollout warning above applies to plugin installation too. ### Codex plugin [#codex-plugin] Add Matrix's marketplace: ```bash codex plugin marketplace add HamedMP/matrix-os ``` Open `/plugins`, choose the **Matrix OS** marketplace, and install `matrix-os`. In the desktop app, select that marketplace in the Plugins directory. Start a new session and authenticate the bundled connection. Use its displayed server name if running `codex mcp login `. [Codex marketplace setup](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli). ### Claude Code plugin [#claude-code-plugin] Run these commands inside Claude Code: ```text /plugin marketplace add HamedMP/matrix-os /plugin install matrix-os@matrix-os ``` Start a new session, open `/mcp`, select the Matrix connection, and sign in. [Claude Code marketplace setup](https://code.claude.com/docs/en/discover-plugins). Matrix's own marketplace is separate from the public directories. Matrix MCP is not yet listed in the official OpenAI or Anthropic directories. Public listings require submission and approval; these commands do not publish a listing. We do not provide unverified Codex or Claude one-click install URLs. ## Consent and authentication [#consent-and-authentication] The `matrix:computer` scope grants broad remote-computer access: an agent can run arbitrary commands, change files, control terminals, and read chats on computers your account can access. Only connect clients you trust. Matrix rechecks computer access for every call; permission to use MCP does not create access to another user's computer. Do not paste access tokens, OAuth codes, or local credential files into chat or plugin configuration. HTTP OAuth and `matrix login` are separate: CLI login does not repair an HTTP authentication failure. Clients may refresh tokens when their authorization server supports it; otherwise reconnect through browser login. Local JWT verification can accept an already-issued token until expiry after provider revocation, so use short-lived access tokens for this high-privilege scope. | Response | What to check | | -------- | ------------------------------------------------------------------------------------------------ | | 401 | Missing, expired, or invalid access token. Reconnect using the client's OAuth flow. | | 403 | Required scope or browser origin was not allowed. Review consent or contact the operator. | | 429 | Request/concurrency limit reached. Wait before retrying; do not blindly retry a mutation. | | 503 | Hosted MCP is disabled, misconfigured, or temporarily unavailable. CLI re-login will not fix it. | MCP cannot disable the agent host's local shell. Configure the host's permissions separately if you require remote-only execution. ## Try it [#try-it] Use these checks after hosted activation, on a disposable Matrix computer you own. They also apply to the stdio connection, which uses CLI authentication. 1. Call `list_computers`, then choose a returned `runtimeSlot` explicitly. 2. Call `run_command` with that slot as `computer` and `"command": ["pwd"]`. Confirm the output describes the Matrix computer. 3. Create a uniquely named terminal and tab. Use the returned stable tab ID to select it, then send `pwd` followed by a newline and observe Matrix's Terminal UI. 4. Upload a uniquely named smoke-test file in an existing Matrix-home directory, read/download it, and compare content. Keep `overwrite: false`; repeating the upload must refuse replacement. 5. List/search/get chats only when that read-only context is needed. Hosted captured commands default to and cap at **45 seconds**. The HTTP request deadline is **55 seconds**. Use persistent terminals for builds, interactive programs, and longer tasks. Terminal input is fire-and-observe: there is no terminal-output reader in this release; captured output comes from `run_command`. A timeout or disconnect does not prove that a remote side effect was undone—inspect state before retrying. Text reads are capped at **256 KiB**, transfers at **1 MiB**, directory listings at 500 entries, terminal input at 60,000 bytes, and chat pages at 100 items. File tools return/accept content rather than accessing arbitrary paths on the agent's local computer. All chat tools are read-only. Both the CLI and hosted adapters expose the same 15 tools, with the shorter captured-command budget applying only to HTTP. The matching gateway release is required for stable-tab selection and cwd fixes. # Messages (/docs/messages) Messages brings Telegram and WhatsApp into Matrix OS through a private Matrix backbone running on your Matrix computer. Conversations appear in the Messages app, and [Hermes](/docs/hermes) starts with no access to any room until you grant it. ## Supported networks [#supported-networks] Text messages sync bidirectionally. Edits, deletes, reactions, receipts, typing indicators, stickers, voice notes, and full historical imports are deferred to a later phase. ## Privacy model [#privacy-model] Messages is default-deny. Connecting an account does not let Hermes read or reply to any conversation. Each room has its own access controls: * **Read** — Hermes receives new messages in the room. If mention-only is also enabled, Hermes only receives messages that explicitly address Matrix OS. * **Reply** — Hermes can send a message into the room, subject to a final permission check at send time. * **Automation** — automation rules can run for this room. Without this flag, matching rules are skipped even if read is enabled. Revoking any permission cancels queued work and prevents new delivery. Draft replies still waiting for approval remain visible in Messages until you approve or cancel them. ## Hermes and Messages [#hermes-and-messages] Hermes can do several things with messages from permitted rooms: * Summarize or classify incoming messages (read permission) * Generate draft replies (read + reply permission) * Run automation rules that create tasks or draft replies (automation permission) See [Hermes](/docs/hermes) for model setup and how Hermes is enabled. Hermes uses its configured model to generate summaries, drafts, and automation responses. Until you pick a model and add its provider credential, Hermes cannot act on any room — even if room-level permissions are enabled. See [Hermes](/docs/hermes) for setup. ## Automations [#automations] Automation rules let you act on messages without opening the app. A rule specifies a trigger (text match) and an action (create a task or draft a reply). Rules run only in rooms where automation permission is enabled. If an automation would send a reply into a room that lacks reply permission, Matrix OS creates a draft or approval request instead of sending. ## Recovery [#recovery] Messaging state is part of the owner-controlled Matrix computer backup lifecycle. Telegram and Matrix conversation mappings restore with the backup. WhatsApp may require relinking after a stale restore or when the paired-device session is no longer recognized. Messages is built on Synapse, mautrix-telegram, and mautrix-whatsapp. Real account pairing is still a production validation gate before broad enablement. # Mobile (/docs/mobile) The Matrix OS mobile app gives you a terminal and session browser that connect directly to your Matrix Matrix computer. You can run commands, pick up sessions you left open on the web shell or CLI, and switch between them — all from your phone. The native mobile app is in active development. The terminal and session browser are functional. Some features available in the web shell and CLI are not yet exposed in the native app. ## Overview [#overview] The app uses four tabs: Chat, Apps, Terminal, and Settings. The Apps launcher is the home screen — it shows your installed Matrix apps. The Terminal tab connects to your Matrix computer and gives you a full terminal. Because sessions live on your Matrix computer, not on your phone, everything you start or leave running in the terminal is also visible from the web shell and the CLI. No SSH keys or separate credentials are needed. ## Terminal on mobile [#terminal-on-mobile] Output from your Matrix computer streams directly to your phone. The terminal fits the available screen area, and line wrapping matches what you see. ### Control bar [#control-bar] The OS keyboard covers part of the screen when you type. A compact horizontal control bar sits just above the keyboard, giving you one-tap access to characters and sequences that are otherwise hard to reach on a phone keyboard. The bar contains: * **Special keys**: Esc, Tab * **Control combos**: `^C` (interrupt), `^D` (EOF), `^Z` (suspend), `^L` (clear screen), `^R` (history search), `^A` (line start), `^E` (line end), `^U` (clear line), `^K` (kill to end), `^W` (delete word) * **Arrow keys**: left, up, down, right * **Symbol shortcuts**: `|`, `~`, `/`, `-`, `_`, `*`, `$` * **Paste**: reads from the system clipboard and sends the text to the shell * **Font size**: A− and A+ to step the terminal font down or up * **Clear**: clears the local display ### Starting and ending a session [#starting-and-ending-a-session] ### Open Terminal [#open-terminal] Tap the **Terminal** tab. If you have a running session from a previous visit, the app reconnects to it automatically. If no session is running, the surface shows an empty state. ### Start a new session [#start-a-new-session] Tap the **+** button in the top-right corner. The app creates a new named shell session on your Matrix computer and attaches to it. ### Switch sessions [#switch-sessions] A chip row below the header shows all running sessions by name. Tap a chip to detach from the current session and attach to the selected one. The active chip is highlighted. ### End a session [#end-a-session] Tap the stop icon in the header and confirm. This kills the session and its processes on the Matrix computer. The action cannot be undone. Ending a session stops all processes running inside it. If you only want to leave a session running while you do something else, switch away or close the tab rather than ending the session. ### Maximize mode [#maximize-mode] Tap the expand icon in the terminal header to hide the session chip row and give the terminal surface more vertical space. Tap again to restore the normal layout. ## Sessions [#sessions] The Sessions screen lists all shell sessions on your Matrix computer grouped by status. Open it by tapping the terminal title in the header while the terminal is visible, or navigate to it from the terminal screen. ### Session groups [#session-groups] Sessions are organized into three groups: * **Needs attention** — sessions where a command is waiting for input * **Active** — sessions with a process currently running * **Background** — sessions that are idle or finished Each row shows the session name, its status, and a badge when the session is also open on the desktop. Tap a row to attach to that session in the terminal. Use the menu icon on a row to end the session. ### Creating a session from Sessions [#creating-a-session-from-sessions] Tap **+** in the top-right corner of the Sessions screen. A new session is created and the app navigates directly to the terminal attached to it. ### Cross-surface sessions [#cross-surface-sessions] Sessions are shared across the web shell, CLI, and the mobile app. A session you start on mobile shows up immediately in the web shell and vice versa. Closing the mobile app does not end your sessions. Processes keep running on your Matrix computer. When you reopen the app, the terminal reconnects to the last active session automatically. ## Related [#related] # Onboarding Launch Readiness (/docs/onboarding-launch-readiness) Matrix launch onboarding is designed to get a founder or developer to a useful workspace, not just a completed signup form. The first-run flow teaches what Matrix can do, asks which goal matters first, and then guides the user through only the setup needed for that goal. Coding users are guided through GitHub, project selection, Symphony, terminal context, and optional Claude or Codex. Assistant users are guided through approved calendar, email, and integration capabilities. Hermes remains the Matrix system agent in every setup state. Claude and Codex can add specialized capabilities, but they do not replace Hermes for Matrix-owned app-building, assistant, integration, and operating workflows. Launch readiness also includes an admin/control surface for models, agents, integrations, settings, automations, activity, and remediation. The surface uses operational patterns inspired by Finna Cloud while keeping the Matrix visual system from the website redesign. ## What The User Gets [#what-the-user-gets] Matrix onboarding is goal-based. A user can start by coding, building apps, using Matrix as an assistant, or turning Matrix into a company brain. Each path explains what Matrix can do, shows what is ready, and names the next useful setup step. For coding, Matrix can guide the user through GitHub connection, project selection, task source selection, Symphony coding runs, terminal context, and handoff summaries. For assistant work, Matrix can guide calendar, email, messaging, and work-update capabilities through explicit approval. For company-brain work, Matrix can capture and reuse product decisions, customer notes, project records, and support context with source display. Hermes is always available as the Matrix system agent. Users can bring Claude or Codex later, but those credentials upgrade capability rather than replacing Hermes or reprovisioning the workspace. ## Admin And Control Surface [#admin-and-control-surface] The Matrix admin/control surface gives users and operators one place to inspect: * model and provider status for Hermes, Claude, Codex, and future providers * integration capability approvals and revoked/missing states * setup wizard recovery after reload or interruption * settings save/reload state * automations, approvals, and recent activity * readiness remediation for setup gates that still need action This surface is operational, not a marketing page: dense enough to scan, polished enough for paid beta, and safe enough to avoid exposing provider secrets or raw internal errors. ## Operator Launch Gate [#operator-launch-gate] Operators use the launch readiness report before enabling paid access: ```text GET /api/operator/launch-readiness ``` The report must remain blocked unless every release-critical gate passes. It covers beta release promotion, fresh workspace rehearsal, existing workspace rehearsal, shell routing, onboarding education, visual QA, approved integrations, Hermes continuity, agent execution, coding handoff, company brain, support/growth drafts, admin/control surface, and entitlement behavior. Payment enforcement is now backed by Clerk Billing for the early adopter launch plan. The shell requires an active `early_adopter` subscription before mounting the Matrix desktop, and the settings surface exposes Clerk's billing table so users can start or manage access. ## Entitlement Safety [#entitlement-safety] When paid entitlement is missing, expired, disabled, or changed, Matrix must block new paid-only access without deleting or corrupting owner data. Existing owner data remains preserved and exportable. Operators must reconcile access state before restoring paid runtime behavior. ## Deferred Scope [#deferred-scope] The first paid beta does not include broad consumer onboarding, a full public app-store launch, enterprise SSO/RBAC administration, automatic provider-secret migration, organization billing, usage metering, tax/VAT handling, refunds, or custom plan management. Those are separate launch tracks after the founder/developer beta passes readiness. # Quickstart (/docs/quickstart) 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 [#choose-your-install-path] Matrix provisions the cloud computer, routing, auth, updates, backups, billing, and integrations. This is the recommended path for daily work, teams, and pilots. Run the main-domain installer on an apt-based Linux VPS you control. You operate DNS, TLS, backups, upgrades, integrations, and server security. 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 [#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: ```text 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. Use one persistent session: matrix shell connect -c setup. 5. Authenticate GitHub inside Matrix: matrix run -it --session setup -- gh auth login --hostname github.com --web. 6. For SSH repository access, use a Matrix-managed SSH key created inside the runtime. Register only the public key with GitHub. Do not use local private keys. 7. Clone the repository under ~/projects after I confirm the repo URL. 8. Start my preferred coding agent inside Matrix: matrix run -it --session setup -- claude or matrix run -it --session setup -- codex. Complete that tool's own login in the remote terminal. 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 [#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](/docs/self-host). ## Managed setup [#managed-setup] ### Create your account [#create-your-account] Go to [app.matrix-os.com](https://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-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](https://matrix-os.com/#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. 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 [#complete-billing] If this is your first primary Matrix computer, Checkout offers a **3-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 3-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. The trial applies only to your first primary computer. Additional computers, previous subscribers, and later subscriptions begin billing immediately. ### Pick your developer tools [#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 [#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. Keep the browser tab open while provisioning runs. If you close it you can return to [app.matrix-os.com](https://app.matrix-os.com) and the screen picks up where it left off. ### Land in the web shell [#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 [#authenticate-github] Inside the Terminal tab, run the GitHub CLI login flow. Matrix tunnels the browser callback through your runtime, so you never need to paste a token manually: ```bash gh auth login --hostname github.com --web ``` Follow the prompts. When asked whether to add an SSH key, let Matrix generate a Matrix-managed key inside the runtime. Only the public key leaves the computer — your laptop private key is never involved. ### Clone a repository [#clone-a-repository] ```bash mkdir -p ~/projects cd ~/projects git clone git@github.com:owner/repo.git ``` Replace `owner/repo` with your target repository. If the SSH key was registered successfully in the previous step the clone should complete without a password prompt. ## Next steps [#next-steps] Install the CLI on your laptop to attach to shell sessions, sync files, and run coding agents from your local terminal. Install Matrix OS on your own Linux VPS with the main-domain server installer. Learn Terminal tabs, Canvas mode, the app sidebar, and shell keyboard shortcuts. # Self-host (/docs/self-host) Self-host Matrix OS when you want the cloud-coding computer on infrastructure you control. The installer uses the same published host bundle shape as Matrix Cloud, then configures a standalone profile with local Postgres, systemd services, nginx, the web shell, gateway, code-server, and optional coding-agent tools. ```bash curl -fsSL https://matrix-os.com/install-server.sh | sudo bash ``` The self-host installer is for developers comfortable operating a VPS. Matrix Cloud still provides managed routing, Clerk auth, backups, updates, billing, and integrations. Self-host installs start with nginx Basic Auth and can work from the server IP address; put the host behind HTTPS, Tailscale, Cloudflare Access, or another trusted edge for long-term use. ## Requirements [#requirements] * A fresh apt-based Linux VPS with systemd. * Root or sudo access. * Ports 80 and the internal loopback service ports available. * Enough disk for the Matrix host bundle, local Postgres, projects, and coding tools. * Optional DNS record pointing at the server before install. If you skip DNS, the installer uses the server IP/default nginx vhost. ## Install [#install] ### Create or choose a VPS [#create-or-choose-a-vps] Start from a clean Ubuntu or Debian-style server. A small development host works for evaluation; use more CPU and memory if you plan to run multiple coding agents and dev servers. ### Run the main-domain installer [#run-the-main-domain-installer] ```bash curl -fsSL https://matrix-os.com/install-server.sh | sudo bash ``` No domain is required. The default `MATRIX_DOMAIN=_` makes nginx answer on the server IP address and the installer prints an `http://` URL. Optional configuration: ```bash curl -fsSL https://matrix-os.com/install-server.sh | sudo \ MATRIX_DOMAIN=matrix.example.com \ MATRIX_INSTALL_HANDLE=alice \ MATRIX_DEVELOPER_TOOLS="codex claude-code opencode" \ bash ``` ### Open the printed URL [#open-the-printed-url] The installer prints the URL, username, generated password, and code-server path. Store the initial password somewhere safe, then replace the edge auth with your preferred HTTPS and access-control setup. ### Verify services [#verify-services] ```bash systemctl status matrix-gateway matrix-shell matrix-code nginx --no-pager journalctl -u matrix-gateway -u matrix-shell -u matrix-code -n 200 --no-pager sudo -u matrix bash ``` ### Verify CLI access [#verify-cli-access] From the VPS, read the standalone gateway token and check that the terminal route lists sessions: ```bash MATRIX_TOKEN=$(sudo sed -n 's/^MATRIX_AUTH_TOKEN=//p' /opt/matrix/env/host.env) matrix shell ls --gateway http:///cli --token "$MATRIX_TOKEN" ``` For laptop access, use the canonical commands in [CLI access from your laptop](#cli-access-from-your-laptop). Browser login is for Matrix Cloud; standalone self-host CLI access currently uses this bearer token. ## Using Your Self-hosted VPS [#using-your-self-hosted-vps] ### What works automatically [#what-works-automatically] After the installer completes, the browser shell, gateway, code-server proxy, local Postgres, nginx, and the default `main` zellij shell session are started by systemd. You do not need to run extra commands for the web UI: open the printed URL, sign in with the generated nginx Basic Auth username and password, and use the shell. The CLI and direct SSH workflows are different. They are power-user access paths and currently need the standalone bearer token or the Matrix owner environment. ### CLI access from your laptop [#cli-access-from-your-laptop] Standalone self-host installs do not use the Matrix Cloud browser login flow yet. `matrix login` and Clerk device auth are for managed Matrix Cloud profiles. For self-host, point the CLI at the printed `/cli` gateway and pass the token from the VPS: ```bash export MATRIX_GATEWAY="http:///cli" export MATRIX_TOKEN="$(ssh root@ 'sudo sed -n "s/^MATRIX_AUTH_TOKEN=//p" /opt/matrix/env/host.env')" matrix shell ls --gateway "$MATRIX_GATEWAY" --token "$MATRIX_TOKEN" matrix run --gateway "$MATRIX_GATEWAY" --token "$MATRIX_TOKEN" -- echo "hello from Matrix OS" ``` If you want to avoid repeating the gateway URL, save a local profile for the URL and keep passing the token explicitly: ```bash matrix profile set selfhost \ --platform "http://" \ --gateway "http:///cli" matrix shell ls --profile selfhost --token "$MATRIX_TOKEN" ``` Treat `MATRIX_TOKEN` like a password. It grants CLI access to the standalone gateway. ### Zellij sessions over SSH [#zellij-sessions-over-ssh] The web terminal and SSH can share the same zellij sessions when both run as the `matrix` user with the Matrix owner environment. Root's zellij sessions are separate. From an SSH session as `root`, first switch to the owner user: ```bash sudo -iu matrix ``` Then run these commands inside the new `matrix` shell: ```bash source /opt/matrix/env/host.env source /opt/matrix/bin/matrix-owner-env matrix_export_owner_env export TERM=xterm-256color /opt/matrix/bin/zellij list-sessions /opt/matrix/bin/zellij attach main ``` If you are already the `matrix` user, skip `sudo -iu matrix`. The `matrix` user is not a sudoer by default. If `zellij` is not found, use `/opt/matrix/bin/zellij` or run `matrix_export_owner_env` to put `/opt/matrix/bin` on `PATH`. ### AI agent handoff prompt [#ai-agent-handoff-prompt] If you install Claude Code, Codex, or another coding agent on the VPS, you can paste this prompt into the agent from the Matrix terminal or an SSH session. It asks the agent to verify the instance without leaking secrets: ```text You are helping me finish and verify a standalone Matrix OS self-host install on this Linux VPS. Rules: - Do not print secret values. Redact MATRIX_AUTH_TOKEN, MATRIX_CODE_PROXY_TOKEN, Postgres passwords, Basic Auth passwords, private keys, and cookies. - Do not expose ports 3000, 4000, 8787, 8788, or 5432 publicly. - Do not rotate credentials, edit nginx, install TLS, or change firewall rules without asking me first. - Prefer read-only checks first, then propose the smallest safe fix if something is broken. Tasks: 1. Inspect /opt/matrix/release.json or /opt/matrix/app/BUNDLE_VERSION and tell me the installed Matrix OS version. 2. Check systemd health for matrix-gateway, matrix-shell, matrix-code, matrix-code-server, matrix-restore, docker, and nginx. 3. Verify local HTTP health: - curl http://127.0.0.1/health - curl http://127.0.0.1:4000/health 4. Read MATRIX_AUTH_TOKEN from /opt/matrix/env/host.env without printing it, then verify: - curl -H "Authorization: Bearer " http://127.0.0.1:4000/api/terminal/sessions - curl -H "Authorization: Bearer " http://127.0.0.1/cli/api/terminal/sessions 5. Verify the matrix user shell environment: - source /opt/matrix/env/host.env - source /opt/matrix/bin/matrix-owner-env - matrix_export_owner_env - /opt/matrix/bin/zellij list-sessions 6. Tell me the exact browser URL, code-server URL, CLI gateway URL, and the commands I should run from my laptop. Keep tokens redacted and show placeholders. 7. If I provide a custom domain, explain the DNS/TLS/security changes needed before making them. 8. Summarize what works, what is risky, and what still needs manual setup for mobile or desktop login. ``` ### Security hardening [#security-hardening] The preview installer is intentionally minimal: nginx Basic Auth protects the browser UI, the gateway and code-server stay loopback-only behind nginx, and `/cli` requires the bearer token. Before long-term use on the public internet: * Put the host behind HTTPS with DNS, Tailscale, Cloudflare Access/Tunnel, or another trusted edge. * Keep ports `3000`, `4000`, `8787`, `8788`, and `5432` closed to the public internet. * Rotate `/opt/matrix/env/initial-ui-password` and `MATRIX_AUTH_TOKEN` if either is exposed. * Back up `/home/matrix/home`, the local Postgres volume, and `/opt/matrix/env`. * Keep SSH limited to trusted keys and trusted networks. IP-only installs are fine for first boot and private testing, but they are plain HTTP unless you add a TLS/access layer. When rotating `MATRIX_AUTH_TOKEN`, update both the service env file and nginx's injected gateway-token include, then restart the affected services: ```bash NEW_TOKEN="$(openssl rand -hex 32)" sudo sed -i "s/^MATRIX_AUTH_TOKEN=.*/MATRIX_AUTH_TOKEN=${NEW_TOKEN}/" /opt/matrix/env/host.env printf 'proxy_set_header Authorization "Bearer %s";\n' "$NEW_TOKEN" | sudo tee /opt/matrix/env/gateway-auth-token.conf >/dev/null sudo chmod 0600 /opt/matrix/env/gateway-auth-token.conf sudo chown root:root /opt/matrix/env/gateway-auth-token.conf sudo systemctl restart matrix-gateway matrix-shell nginx ``` ### Mobile and desktop login [#mobile-and-desktop-login] Managed Matrix Cloud mobile and desktop login will use platform auth and managed routing. Standalone self-host mobile/desktop login is not enabled yet. The intended self-host direction is: * Use a custom domain with HTTPS for the self-hosted gateway. * Pair the mobile or desktop app to that domain. * Use the self-host owner token or a future standalone device flow instead of the Matrix Cloud Clerk tenant. Until that lands, use the browser shell and CLI for self-hosted instances. Do not expect the managed `app.matrix-os.com` mobile/desktop handoff to discover an arbitrary self-hosted IP address. ## What You Get [#what-you-get] * Matrix web shell on your VPS. * Gateway API and WebSocket services protected by an internal bearer token. * Local owner-controlled Postgres on `127.0.0.1`. * code-server behind the Matrix code proxy at `/code/`. * Persistent home directory at `/home/matrix/home`. * Optional Claude Code, Codex, OpenCode, and Pi CLI installs through Matrix tool packs. * Source-free install from a verified host bundle. ## What You Manage [#what-you-manage] * DNS and TLS. * Server firewalling, OS updates, and SSH access. * Backups and restore policy. * Upgrades to newer Matrix host bundles. * Edge auth hardening beyond the generated nginx Basic Auth. * Any external integration secrets. ## Differences From Matrix Cloud [#differences-from-matrix-cloud] | Capability | Matrix Cloud | Self-host preview | | -------------------------- | -------------------------------------------- | ---------------------------- | | Provisioning | Managed VPS creation | Bring your own VPS | | Auth | Clerk and platform sessions | Generated nginx Basic Auth | | Routing | `app.matrix-os.com` and `code.matrix-os.com` | Your domain or server IP | | Backups | Managed platform path | You configure backups | | Updates | Platform release fan-out | Manual installer/update path | | Integrations | Platform-owned Pipedream | Not configured by default | | Mobile and desktop handoff | Upcoming managed surfaces | Not included yet | ## Security Notes [#security-notes] The shell runs in explicit standalone mode. Public browser access is expected to go through nginx, while same-origin API, file, app, and WebSocket requests are rewritten by the shell proxy with the internal `MATRIX_AUTH_TOKEN`. code-server runs loopback-only and is reached through a token-protected Matrix proxy. IP-only installs are acceptable for first boot and private-network testing, but they are plain HTTP unless you add a trusted TLS/access layer. For a public VPS, prefer DNS plus TLS, Tailscale, Cloudflare Access/Tunnel, or another authenticated reverse proxy before storing long-lived work there. Do not expose ports `3000`, `4000`, `8787`, `8788`, or `5432` publicly. Keep them on loopback and expose only your hardened reverse proxy. The installer leaves `GET /health` open at nginx and returns only `{"ok":true}` so basic uptime monitors can check the public edge without credentials or gateway details. For deeper checks, use systemd status or local-only gateway health from the server. ## Manual Install Telemetry [#manual-install-telemetry] The installer sends lightweight, best-effort telemetry to Matrix OS so we can see how many people choose the manual path, which release channel/version they reach, whether installs finish, and where failures happen. The endpoint has a bounded request body and short-window rate limits to keep the signal useful. It records an anonymous install id, channel, installed version, IP-vs-DNS mode, default-vs-custom bundle source, selected developer-tool count, phase, status, and exit code. It does not send your Matrix handle, password, auth tokens, Postgres password, domain name, project files, shell output, or code-server URL. The website telemetry endpoint also asks PostHog to discard client IP by setting `$ip` to `0.0.0.0`. Opt out per install: ```bash curl -fsSL https://matrix-os.com/install-server.sh | sudo MATRIX_NO_TELEMETRY=1 bash ``` Or disable only installer telemetry: ```bash curl -fsSL https://matrix-os.com/install-server.sh | sudo MATRIX_INSTALL_TELEMETRY=0 bash ``` ## Next Steps [#next-steps] Install the Matrix CLI on your laptop for hosted Matrix Cloud workflows. Install and authenticate Claude, Codex, OpenCode, or Pi inside your Matrix computer. # Settings & Billing (/docs/settings-billing) Settings is where you manage the explicit parts of Matrix: billing plan, computer capacity, location, integrations, and account controls. Open it from the top-right user menu or from the sidebar in any shell mode. Plan and region selection happens during initial provisioning. See [Quickstart](/docs/quickstart) for that flow. This page covers what you can change after your Matrix computer is running. ## Billing [#billing] The Billing section shows your current computer's plan and opens the Stripe billing portal for invoices, payment methods, and plan changes. Each Matrix computer has its own Stripe subscription under your existing Stripe customer, so billing or canceling one computer does not change another computer's plan. ### Plans and compute tiers [#plans-and-compute-tiers] Each plan maps to a dedicated Matrix computer. The three available tiers are: | Plan | Monthly list price | Germany capacity | US capacity | | ------- | -----------------: | ------------------------------- | ------------------------------ | | Starter | $20 | 2 vCPU, 4 GB RAM, 80 GB disk | 3 vCPU, 4 GB RAM, 80 GB disk | | Builder | $100 | 8 vCPU, 16 GB RAM, 320 GB disk | 4 vCPU, 8 GB RAM, 160 GB disk | | Max | $200 | 12 vCPU, 24 GB RAM, 480 GB disk | 8 vCPU, 16 GB RAM, 240 GB disk | Builder is the default selection and suits most developers running a coding agent alongside a dev server. Choose Max for parallel agent workers, heavy builds, or multiple long-lived processes. The prices above come from the source-of-truth billing constants in the codebase. Confirm current pricing against the live checkout screen or the matrix-os.com pricing page before making a decision. New Checkout sessions use monthly billing. Existing annual subscriptions remain supported and keep their attached Stripe price. ### Three-day trial for your first computer [#three-day-trial-for-your-first-computer] Your first primary computer is eligible for one three-day free trial on Starter, Builder, or Max when the offer is enabled. A card is required in Stripe Checkout, but you pay $0 today. The Billing screen shows the exact recurring Stripe price when it is available, the trial-ending date, and the cancellation deadline. Eligibility belongs to the Matrix account, not an email alias, card, plan, or computer. Previous subscribers cannot start another trial. Additional computers and subsequent subscriptions begin billing immediately. Matrix may prepare the selected computer while Checkout is open, but it authorizes access only after a verified Stripe webhook projects the subscription as `trialing`. Checkout return parameters never grant runtime access. If early preparation is not available, Checkout and billing continue normally, and Matrix automatically starts or resumes provisioning after authorization. There is no second provisioning choice or start button after payment. ### Active plan view [#active-plan-view] When billing is active, the Billing section shows: * **Plan name** — Starter, Builder, or Max. * **Status** — Active, Past due, canceled, or a grace-period label with the end date. * **Billing** — the recurring price and interval attached to this subscription. Legacy customers see their legacy price, not today's list price. * **Location** — the actual provider-neutral location of the current computer, such as Ashburn, Virginia or Falkenstein, Germany. During a trial, the shared shell also shows the days remaining, upcoming price and charge date, and a link to the Stripe customer portal. The reminder becomes more prominent during the final three days. Starter, Builder, and Max each include exactly one computer. The plan controls that computer's strength; it does not grant shared slots that another computer can consume. ### Adding another computer [#adding-another-computer] Open **Runtime** and choose **New computer**. Matrix reuses the same plan, region, billing interval, and Checkout steps as first-time setup: 1. Name the computer. 2. Choose Starter, Builder, or Max and a region. 3. Review monthly billing. 4. Complete a new Stripe Checkout subscription. 5. Wait for the signed Stripe webhook to activate that runtime slot, then continue through normal provisioning. Checkout reuses your existing Stripe customer, but creates an independent full subscription for the new computer. Matrix does not purchase computer capacity through a Customer Portal subscription-update flow. Additional computers are not trial-eligible and start billing immediately. ### Billing portal [#billing-portal] In Web Desktop and Web Canvas, choose **Open billing portal**. In Electron Desktop, open **Settings → Billing** and choose **Manage billing**. Electron Desktop uses your signed-in Matrix account to open the billing portal in your default browser. From there you can: * Manage an existing Starter, Builder, or Max subscription without deleting data or machines. * View invoices and receipts. * Update your payment method or billing email. * Apply coupons. * Cancel — access stays active through the billing cycle and the configured grace window. Existing customers can still view receipts and manage payment settings when a subscription is overdue, unpaid, or canceled. Runtime access and access to billing records are separate. After making changes in the portal, return to Electron Desktop and select **Refresh** to reload your billing status. If the portal cannot open, Settings shows an error and lets you retry. Billing management remains visible while availability is checked. If a portal is not available for your account yet, the button is disabled with an explanation. Portal access follows the billing customer linked to your signed-in Matrix account. A support override or internally granted runtime plan does not remove access to your existing invoices. If no billing customer is linked, contact the Matrix team for billing help. ### Canceling [#canceling] Cancel from the Stripe billing portal, not from the shell. Canceling a trial keeps access available until Stripe's displayed `trial_end`; no charge is made when cancellation completes before that deadline. Access is gated when the trial ends, and Matrix retains the stopped VPS and its owner data rather than deleting it. For established paid subscriptions, a recoverable renewal failure keeps the existing three-day grace period. The first payment failure immediately after a trial does not receive that grace: access pauses at once, and the VPS is scheduled to power off 24 hours later. Updating the card and completing payment restores access automatically and wakes a suspended computer. ## Compute and region [#compute-and-region] When you do not yet have an active plan, or when you are re-provisioning, the Billing section shows the computer and region pickers. ### Choosing a computer [#choosing-a-computer] The computer picker shows the three tiers (Starter, Builder, Max) with their vCPU, RAM, and disk specs inline. Builder is pre-highlighted as the recommended option. ### Choosing a region [#choosing-a-region] Matrix selects the closest available location from the browser's time zone. New computers can be provisioned in four locations: * Germany — Falkenstein and Nuremberg * United States — Ashburn, Virginia and Hillsboro, Oregon Region selection determines where your Matrix computer is provisioned. You cannot change the region of an existing machine without reprovisioning. ## Other Settings sections [#other-settings-sections] The Settings nav currently shows Appearance, Integrations, Billing, and System. Agent, Channels, Skills, Security, Cron, and Plugins sections exist in the codebase but are hidden pending further development. ### Appearance [#appearance] Control the shell color theme and visual preferences. ### Integrations [#integrations] Connect external services. Matrix keeps provider credentials platform-side and requests permission before acting through a connected service. Common integrations include GitHub, Discord, Slack, Gmail, Calendar, and Drive. ### System [#system] Runtime status, restart controls, and system-level preferences for your Matrix computer. ## Next steps [#next-steps] If you have not provisioned yet, the Quickstart walks through plan selection, billing, and first boot. Attach to shell sessions and run coding agents from your local terminal. # Web Shell (/docs/shell) The web shell at `https://app.matrix-os.com` is the primary interface to your Matrix computer. It gives you Terminal, Files, Canvas, apps, integrations, and settings — all running on your persistent Matrix computer. ## Terminal and sessions [#terminal-and-sessions] The Terminal is a persistent shell that keeps running after you close the browser. Your sessions are shared across the web shell, the CLI, and the desktop app — start work in the browser and pick it up later from the CLI exactly where you left off. ### Open Terminal [#open-terminal] From the shell, click **Terminal** in the sidebar or dock. A new terminal session opens on your Matrix computer. ### Create or attach a named session [#create-or-attach-a-named-session] Named sessions let you organize work and reattach from any surface. From the CLI: ```bash matrix shell new main --attach matrix shell connect main matrix shell connect -c setup ``` Use `-c` (`--create-or-connect`) to open the session if it exists, or create it if it does not. ### Detach without closing [#detach-without-closing] To leave a session running while you switch away: ```text Ctrl-\ Ctrl-\ ``` The session stays live on your Matrix computer. Reconnect from the browser or CLI at any time. The web Terminal, `matrix shell connect`, and the desktop app all attach to the same named session model. A session you open in the browser is immediately available from the CLI and vice versa. ### Close, detach, or delete [#close-detach-or-delete] Closing the **outer Terminal window** only detaches that view. Its named sessions keep running on your Matrix computer and remain available from Web Desktop, Web Canvas, Electron Desktop, and the CLI. **Close pane** ends the focused pane's process inside the attached Zellij session. Other panes in that session keep running; closing its last pane ends the session. Closing a Matrix Terminal session tab or choosing **Delete session** stops the named session and removes its saved Terminal references. Older saved layouts can contain separate named sessions, so check the session you are closing. Use the outer window close control when you want work to continue in the background. Close a pane or delete a session only when you intend to stop that work. ### Updates and recovery [#updates-and-recovery] On releases with the supervised terminal runtime, a normal gateway update or app rollback disconnects attachments while the terminal process keeps running. Reconnect to the same named session after Matrix returns. A host reboot or runtime failure does not automatically restart your shell command or coding agent. In Web Desktop and Web Canvas, when a saved session is unavailable, Terminal shows **Session is unavailable** instead of silently creating a replacement. Choose **Recover session** explicitly, or remove the stale session reference. Recovery is not a promise to restore the previous command, viewport, or complete scrollback. Check the recovered shell before resuming work; recovery cannot bring a terminated process back to life. A deliberately deleted session is removed from saved layouts and is not offered there for recovery. Terminal history may contain commands, paths, credentials, or other printed content. Deleting a session does not guarantee that every retained copy of its output has been erased. Avoid printing secrets into terminal history or sharing output that contains them. ### Agent sign-in terminals [#agent-sign-in-terminals] In Web Desktop and Web Canvas, coding-agent installation and sign-in actions use a dedicated temporary Terminal window. That setup window does not read or overwrite your ordinary Terminal layout, and its temporary session is cleaned up when the setup window closes. Electron Desktop uses a regular named session for provider setup. Closing its outer Terminal window detaches the view; close the setup session explicitly when you are finished with it. ### Copy, paste, and selection [#copy-paste-and-selection] Terminal clipboard controls work the same way in the web shell and native desktop app, in both Canvas and Desktop layouts: | Action | macOS | Other platforms | | ----------------------------------------- | ---------------------- | ------------------------------------- | | Copy the current selection | **⌘C** or **⌘⇧C** | **Ctrl⇧C** | | Paste into the focused terminal | **⌘V** | **Ctrl⇧V** | | Select all terminal output and scrollback | **⌘A** | Right-click and choose **Select All** | Right-click a terminal selection to open its menu. **Copy** stays enabled for the complete highlighted range, including multiple rows, wrapped lines, whitespace, punctuation, and Unicode. The word beneath the pointer does not replace the selection. You can also choose **Select All** from this menu. When a coding agent or another terminal application enables mouse reporting, ordinary pointer movement does not clear a completed selection. Deliberate terminal input—typing, pasting, or beginning a new selection—returns control to the application normally. Selections and clipboard behavior are consistent between Canvas and Desktop, including after changing Canvas zoom. Clipboard failures show a generic error, leave the selection available for retry, and never partially paste text. ### Keyboard navigation and Zellij panes [#keyboard-navigation-and-zellij-panes] Web Canvas, Web Desktop, and Electron Desktop share the same terminal keyboard settings and pane controls. Click inside the terminal before using shortcuts. On macOS, the default **Mac editing** profile provides: | Action | Shortcut | | ---------------------------------------- | --------------- | | Beginning / end of the input line | **⌘← / ⌘→** | | Previous / next word | **⌥← / ⌥→** | | Delete the previous word | **⌥⌫** | | Delete back to the beginning of the line | **⌘⌫** | | Top / bottom of the pane history | **⌘↑ / ⌘↓** | | Focus a neighboring pane | **⌘⌥ + arrow** | | Resize the focused pane | **⌘⌥⇧ + arrow** | | Split right / below | **⌘D / ⌘⇧D** | | Maximize / restore the focused pane | **⌘⇧Enter** | Line editing uses the shell application's bindings. For applications with their own keymaps, select **Standard terminal** or **Pass through to application** from **Keyboard shortcuts**. The latter turns off Matrix keyboard interception for editing and pane commands; the pane toolbar remains available. On other platforms, the default pane shortcuts use **Ctrl⇧ + arrow** for focus, **CtrlAlt⇧ + arrow** for resize, **Ctrl⇧D / Ctrl⇧E** for split right / below, and **Ctrl⇧Enter** for maximize / restore. Standard terminal uses these same pane shortcuts on macOS while preserving the application's normal editing keys. #### Prefix alternative [#prefix-alternative] Browsers and operating systems reserve some shortcuts. With Mac editing or Standard terminal selected, press **CtrlG**, release it, then press one of: | Key | Action | | ------------------------------ | ------------------------------------------ | | **H / J / K / L**, or an arrow | Focus left / down / up / right | | **Shift + arrow** | Resize | | **V / S** | Split right / below | | **F** | Maximize / restore | | **T / B** | Top / bottom of pane history | | **X** | Close the focused pane and end its process | **Escape** cancels the prefix; it also expires after two seconds. The toolbar provides the same actions if the browser intercepts a key before Matrix receives it. #### Customize shortcuts [#customize-shortcuts] Open **Keyboard shortcuts**, choose a profile, edit a binding, and click **Save shortcuts**. Use names such as `Meta+ArrowLeft` (Command on macOS) or `Ctrl+Shift+D`. Clear a field to disable that command. Duplicate bindings and reserved clipboard, search, or prefix shortcuts are rejected. **Reset defaults** restores the draft defaults; click **Save shortcuts** to apply them. Settings are saved on your Matrix computer and loaded when you attach a terminal. Copy, paste, selection, and text composition keep their existing behavior. New splits are Zellij panes within the current named session. They persist with that session and are available when you reattach from another surface. Older saved layouts containing separate sessions remain readable. **Close pane** ends the focused pane's process; closing the last pane ends the session. Controls are disabled while disconnected or when this surface no longer owns terminal input. ## GitHub auth [#github-auth] Run `gh auth login` inside a terminal session to authenticate with GitHub. The credentials are stored on your Matrix computer and persist across sessions. ```bash gh auth login ``` Choose the browser-based flow and complete the login in the browser tab that opens. Once done, `git` and `gh` commands work from any terminal session without re-authenticating. When `gh auth login` generates an SSH key in the shell, choose a password (passphrase) for it — don't leave it empty. The key lives on your Matrix computer; a passphrase keeps it protected. ## File browser [#file-browser] Click **Files** in the sidebar to open the file browser. It shows your Matrix home directory and lets you navigate folders, select files, rename, copy, paste, delete, and move items to Trash. * Navigate directories with the column view or list view. * Select a file and press Space to preview it with Quick Look. * Double-click a file to open it in the Preview panel. * Right-click any file or folder for a context menu with copy, cut, paste, duplicate, rename, and delete options. Files you create or clone in the Terminal appear immediately in the file browser. Changes sync across the web shell and persist on your Matrix computer. ## Refresh and PWA cache [#refresh-and-pwa-cache] The browser and installed PWA keep a private shell snapshot on your device so refreshes can restore your theme, wallpaper, dock, launcher apps, and saved shell bootstrap before the network finishes. The snapshot is scoped to the signed-in account and runtime path, expires automatically, and is replaced after the shell revalidates with your Matrix computer. Static shell assets such as icons, fonts, bundled wallpapers, and Next.js chunks can be cached by the browser and service worker. Private APIs, auth pages, app documents, billing/provisioning routes, and owner data stay `no-store` and are never shared through the CDN cache. ## Desktop icon layout [#desktop-icon-layout] Your Desktop icon positions are durable owner state on your Matrix computer. The same layout appears in the web shell and the desktop app, and it follows you when you sign in on another device. A private, account-and-computer-scoped browser snapshot can show the last validated layout immediately during startup, then the shell reconciles it with the durable copy. New Desktops start with Chat, Terminal, Files, Editor, VS Code, Settings, Plugins, Browser, Notes, and Whiteboard. During the durable-layout upgrade, an older Desktop that had lost every icon because its layout was never initialized is restored once. Matrix OS does not add icons to a customized nonempty layout or reorder it. If you intentionally remove every icon, that empty Desktop remains valid after the one-time recovery has run. Move, add, and remove actions continue to save normally and appear on your other devices after they reconnect. ## What persists [#what-persists] * Shell sessions and terminal output. * Source repositories under `~/projects`. * GitHub credentials and agent credentials you install inside the workspace. * App state and settings under your Matrix home. ## Related [#related] # Symphony (/docs/symphony) # Symphony [#symphony] Symphony is the Matrix coding-agent operator for Linear work. On each customer VPS it runs as `matrix-symphony.service`, owned by the `matrix` user with `MATRIX_HOME=/home/matrix/home`. The service is an adapted Elixir runtime. It polls eligible Linear issues, creates Matrix-owned workspaces, starts agents through `codex app-server`, and exposes loopback state to the Matrix gateway. The browser never talks to the Elixir service directly. ## Linear Access [#linear-access] Connect Linear from Matrix settings or the Integrations app. Symphony uses that Matrix-owned connection through the platform integration bridge. You do not need to put `LINEAR_API_KEY` on the VPS. The Elixir runtime defaults to the Matrix credential bridge, which calls the platform internal integrations route using the VPS internal token. The UI only receives coarse setup or availability status, not provider tokens or raw provider errors. For local development, an explicit `SYMPHONY_LINEAR_API_KEY` or `SYMPHONY_LINEAR_CREDENTIAL` can still override the bridge. ## Runtime Paths [#runtime-paths] Symphony workspaces live under the owner home: ```txt /home/matrix/home/projects/matrix-os/symphony-workspaces/ ``` Runtime logs live under: ```txt /home/matrix/home/system/symphony/logs ``` Updates replace `/opt/matrix/app` only. They must not overwrite owner data under `/home/matrix/home`. ## Matrix App [#matrix-app] Open Symphony from Matrix to see the Elixir runtime state. The app shows: * Queue, Running, Needs Attention, and Done/Handoff groups * active issue identifier * Codex app-server session ID and turn count * latest event and message * workspace path * workpad link when available * recent logs Use **Refresh** to ask the Elixir runtime to poll and reconcile now. Use **Stop** to terminate the active issue session through the gateway proxy. ## Service Operations [#service-operations] The host bundle installs and starts: ```bash systemctl status matrix-symphony.service journalctl -u matrix-symphony.service -f ``` The service binds to `127.0.0.1:4766`. Matrix gateway proxies authenticated requests from `/api/symphony/*` to that loopback API with validation, body limits, timeouts, and generic error mapping. ## Migration Notes [#migration-notes] The old in-gateway TypeScript Symphony runner is no longer the runtime source of truth for the Matrix app. Gateway routes now proxy the Elixir service instead of maintaining a separate run table. Existing docs or workflows that mention manual Symphony API-key setup should be moved to Matrix Integrations. # Workspace Canvas (/docs/workspace-canvas) # Workspace Canvas [#workspace-canvas] Workspace Canvas turns a project, pull request, task, or review loop into a durable spatial workspace. The canvas document is stored in the user's Matrix OS Postgres database on their VPS. Files are only written for export, backup materialization, and recovery artifacts. ## Concepts [#concepts] * Canvas documents contain visual nodes, visual edges, view state, and display options. * Nodes reference source-of-truth records such as terminal sessions, pull requests, tasks, files, app windows, issues, and review loops. * Edges are visual by default. Changing a real task, project, or review relationship requires a separate confirmed action. * Optimistic revisions protect concurrent edits. A stale save reloads the latest document instead of overwriting it. ## PR Review Workflows [#pr-review-workflows] PR canvases start with PR summary, review-loop, and terminal summary nodes. Review controls can start, stop, advance, approve, or refresh the loop from the canvas while provider-specific errors stay server-side. ## Terminal Nodes [#terminal-nodes] Terminal nodes attach to existing Matrix OS terminal sessions or create a durable session through the gateway session registry. Reloading the browser keeps the canvas node identity separate from the terminal session identity, so the same session can be reattached from another surface. ## Custom Nodes [#custom-nodes] Notes, files, previews, app windows, issues, and custom nodes use typed metadata with size caps. Unsafe file paths, unsafe URL schemes, invalid custom versions, and oversized payloads are rejected before persistence. Missing renderers degrade into fallback nodes rather than deleting user data. ## Ownership, Export, And Delete [#ownership-export-and-delete] Canvas data is scoped to the authenticated user and stored in Postgres. Delete is a soft delete so recovery/export workflows can inspect the document until cleanup. Export writes a temporary bundle with crash-safe temp-file plus rename behavior and cleanup policies. ## VPS Recovery [#vps-recovery] On startup, Matrix OS can reconcile canvas references against available terminal sessions, projects, and review loops. Missing references become recoverable nodes with recovery metadata, preserving spatial context while making broken links visible. # Chat conversations in Electron Desktop (/docs/desktop/chat-conversations) Open **Chat** in Electron Desktop to find conversations on your selected Matrix computer. Chat uses the available agent harness and model selected in the composer. Saved conversations belong to the computer, so reopening the app does not start a separate history. ## Find and resume a chat [#find-and-resume-a-chat] Select a chat title to load its saved messages and continue the conversation. The chat list shows recent activity so you can find your latest work. Open **Search chats**, enter words from a message, and press **Enter**. Search runs on your Matrix computer against committed message text and returns matching conversations. It is not a complete list of every conversation or an exact phrase search. Close the search field to clear the query and return to the recent chat list. Select **New chat** to open a draft. Choose an available harness and model, optionally add a project, then send your first message to create the saved conversation. Starting another draft does not delete an existing chat. Switching Matrix computers loads that computer's conversations. If a chat is missing, check that you are connected to the computer where you created it. If loading fails, reconnect and reopen Chat before assuming the conversation was deleted. ## Delete a chat [#delete-a-chat] ### Reveal Delete [#reveal-delete] Point to a row in the chat list, or move keyboard focus to its **Delete** action. ### Review the confirmation [#review-the-confirmation] Select **Delete**, then review the conversation title and permanent-deletion warning. Select **Cancel** to leave the chat unchanged. ### Confirm the deletion [#confirm-the-deletion] Select **Delete chat** to permanently remove that conversation and its messages from the selected Matrix computer. The row disappears only after the computer confirms the deletion. A chat cannot be deleted while it has an active run. Stop the run or wait for it to finish before trying again. If deletion fails, the dialog shows an error; reconnect or refresh the conversation and retry. Closing a chat tab is separate from deleting its saved conversation. Delete permanently removes the selected chat and its messages. Keep any information you need before confirming. ## Related [#related] * [Project context for Chat](/docs/desktop/chat-project-context) * [Desktop App](/docs/desktop) * [Web Shell](/docs/shell) # Project context for Electron Desktop Chat (/docs/desktop/chat-project-context) A Chat conversation can belong to one project. The saved association determines the workspace directory used for future turns, whether the project is a folder, scratch workspace, or GitHub repository. Choosing a project does not change the existing transcript. ## Add a project [#add-a-project] Open **Chat** and select a conversation, or choose **New chat** . Open the **Add to project** control in the composer. In a compact composer, this is a folder icon. Choose an active project. GitHub projects also show their repository label. For a new draft, send your first message to save the conversation with that project. For an existing conversation, selecting a project saves the change immediately. The selected project appears in the composer; open that control to choose another project or select **Remove project context**. Wait for an active run to finish, or stop it, before changing context. The change applies to future turns and does not move or rewrite project files. ## When a project is unavailable [#when-a-project-is-unavailable] The Matrix computer validates the saved project and its workspace before starting a turn. If the workspace is unavailable, the turn fails with an error; Chat does not silently fall back to your home directory. Your saved conversation remains available. Check the connection and project availability, then retry. You can also choose another active project or select **Remove project context**. If the selected harness requires a project, choose a valid project before sending again. If saving a project change fails, Chat shows an error and reloads the saved conversation. Check the project shown in the composer before retrying. While disconnected, the picker cannot load projects; reconnect first. If the list fails to load, use **Retry projects**. Switching to another Matrix computer loads that computer's conversations and projects. Choose context from the computer where you intend to run the chat. ## Scope of the project picker [#scope-of-the-project-picker] The picker associates one project with the conversation. It does not select branches or worktrees, show Git status, or combine several repositories into one workspace. The Matrix computer resolves the saved project to its workspace directory; the app does not supply an arbitrary local path. ## Related [#related] * [Chat conversations](/docs/desktop/chat-conversations) * [Desktop App](/docs/desktop) # Agent Matrix Skills (/docs/developer/agent-skills) Matrix ships one canonical skill pack under `skills/matrix/`. Runtime sync projects every skill directory with a `SKILL.md` into the tool-specific locations for Matrix, Claude Code, Codex, Hermes, and Agent-compatible runtimes. The pack currently contains 19 skills: the six Matrix app skills below plus thirteen animations.dev-derived motion skills. Builders load the Matrix foundation first, derive a taste brief from the user's references and app domain, and then load only the motion guidance relevant to the interface. Matrix skills follow the portable `SKILL.md` model described by the [Agent Skills specification](https://openagentskills.dev/docs/specification). The specification requires a skill directory with a `SKILL.md` file and supports optional scripts, references, and assets. Anthropic describes the same progressive-disclosure pattern: agents discover lightweight metadata first and load full instructions only when a skill is relevant ([Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)). ## Skills [#skills] | Skill | Purpose | | ------------------------ | ----------------------------------------------------------------------------------------------------- | | `matrix-app-builder` | Build Matrix apps as Vite React TypeScript projects with `matrix.json` and verified `dist/` output. | | `matrix-app-ui-patterns` | Build stable app interiors for windowed, mobile, dashboard, data, and canvas contexts. | | `matrix-design-system` | Apply Matrix theme, shadcn-style component patterns, icon quality rules, and iframe-safe app layouts. | | `matrix-integrations` | Use platform-owned integrations without copying provider secrets into agents or customer VPSes. | | `matrix-dev-vps` | Develop Matrix from inside a user/dev VPS with hot reload, previews, and auth-aware tunnels. | | `matrix-debug-app` | Fix `needs_build`, manifest problems, bundle/icon 404s, console errors, and integration proxy issues. | The motion set covers animation decisions, vocabulary, CSS and Motion React recipes, gestures, scroll motion, accessibility, performance, debugging, opportunity discovery, improvement audits, review standards, and UI-library selection. ## Sync targets [#sync-targets] ```bash MATRIX_SKILL_TARGETS=matrix,claude,codex,hermes ./scripts/sync-matrix-agent-skills.sh skills/matrix ``` | Consumer | Runtime path | | ------------- | ---------------------------------------------- | | Matrix kernel | `$MATRIX_HOME/.agents/skills//SKILL.md` | | Codex | `$HOME/.agents/skills//SKILL.md` | | Claude Code | `$HOME/.claude/skills//SKILL.md` | | Hermes | `$HERMES_HOME/skills//SKILL.md` | ## Matrix OS marketplace plugin [#matrix-os-marketplace-plugin] Local Codex users can install one complete **Matrix OS** marketplace product from a Matrix OS repository checkout: ```bash codex plugin marketplace add "$(pwd)" ``` The marketplace name and plugin ID are **Matrix OS** (`matrix-os`), its category is Productivity, and its description is “Run development work on your Matrix cloud computer.” If you installed an unpublished preview under the old `matrix-onboarding` namespace, remove it and install the renamed plugin once: ```bash codex plugin remove matrix-onboarding@matrix-os codex plugin add matrix-os@matrix-os ``` The product bundles three skills: | Skill | Purpose | | ----------------------- | --------------------------------------------------------------------- | | `matrix-onboarding` | Set up, authenticate, diagnose, and recover a Matrix computer. | | `matrix-cloud-run` | Run bounded commands and sandboxed coding-agent tasks on Matrix. | | `matrix-github-project` | Clone, verify, reuse, change, and validate GitHub projects on Matrix. | Try a starter prompt: ```text Build a new app on my Matrix computer. Clone this GitHub repo on Matrix and make a change. Run this command on my Matrix computer. ``` Matrix, Codex, Claude, and GitHub use their own browser or device login flows. The plugin does not scan, read, or upload local credential files. If an agent or GitHub CLI is missing, it asks before installing a global tool and prefers Matrix's visible developer-tool installation path. ### Run commands and coding work [#run-commands-and-coding-work] The plugin checks the hosted `cloud` profile, `matrix doctor`, identity, status, instance readiness, and the selected agent's remote version and authentication status. If `matrix instance info --json` reports `ready: true` with `source: execution_probe`, command execution is healthy even though the management plane is degraded; the workflow continues and reports the degraded metadata path. It stops only when both checks fail. Every remote command runs in a unique session created by the Matrix CLI. The workflows never create or use tabs. Each additional command, terminal, or concurrent task gets a separate session whose name and `matrix shell connect` command are reported immediately. The plugin normalizes a safe relative destination under the Matrix home and inspects existing contents before running work. For a new app, it creates `apps/` before selecting it. `-C` only selects an existing directory; it never creates one. ```bash matrix run -it --session create-app-- -- mkdir -p -- apps/ matrix run -it --session task-- -C apps/ -- matrix shell connect task-- ``` Coding tasks use the same unique named-session policy: ```bash matrix run -it --session task-- -C -- codex --ask-for-approval never --sandbox workspace-write exec -- matrix shell connect task-- ``` Codex uses `read-only` for inspection and narrow `workspace-write` for changes. The plugin never uses `danger-full-access` without explicit direction. Claude Code uses `claude --permission-mode auto -p ` in its own named session so it can proceed without repetitive permission questions while retaining Claude's safety classifier. If auto mode is unavailable, the workflow stops and reports the limitation instead of using a permission bypass. ### Work on a GitHub project [#work-on-a-github-project] GitHub authentication runs on the Matrix computer with remote `gh auth status` and a unique `auth-github-` browser-login session. Ordinary repositories live under `projects/`; only checkouts meant to run directly as Matrix apps use `apps/`. ```bash matrix run -it --session clone-- -- gh repo clone / projects/ matrix run -it --session inspect-status-- -C projects/ -- git status --porcelain=v1 --branch matrix run -it --session inspect-origin-- -C projects/ -- git remote get-url origin ``` An existing checkout is reused only when its normalized GitHub owner/repository matches the request. The workflow stops on non-Git collisions, mismatched origins, and dirty or mid-operation worktrees. It never resets, cleans, stashes, or overwrites user changes automatically. It reads repository instructions, README files, lockfiles, and environment examples before setup or validation, and pushes or opens a PR only when explicitly requested. ## Agent bootstrap [#agent-bootstrap] ```bash matrix login matrix run -it --session auth-claude-a1b2 -- claude matrix run -it --session auth-codex-c3d4 -- codex login matrix run -it --session auth-github-e5f6 -- gh auth login --hostname github.com --web matrix shell connect auth-github-e5f6 ``` Use a separate uniquely named session for each setup workflow so the user, Matrix web terminal, Claude, Codex, or Hermes can observe and reattach each VPS task. Never use tabs to multiplex work. ## Security boundary [#security-boundary] Skills contain instructions only. They should not carry secrets, and they should prefer Matrix gateway/platform APIs for authenticated actions. # Architecture (/docs/developer/architecture) ## Architecture At A Glance [#architecture-at-a-glance] Matrix OS has two major runtime layers: * **Platform control plane**: shared services for auth, routing, provisioning, integrations, host-bundle publication, and recovery orchestration. * **Customer VPS runtime**: one VPS per independently billed runtime slot, running that computer's Matrix gateway, shell, code editor, app assets, local Postgres, sync, and backup services. One user may own multiple runtime slots. ## Platform Control Plane [#platform-control-plane] `packages/platform/` owns shared platform concerns: * Clerk/session auth for `app.matrix-os.com` and `code.matrix-os.com`. * Session-based routing from the signed-in Clerk user to that user's active customer VPS. * `user_machines` registry for customer VPSes. * Hetzner provisioning, registration, deletion, and recovery flows. * Host-bundle serving through `/system-bundles/*`. * Pipedream integration credentials and user-scoped integration routes. * Platform Postgres for control-plane records. The platform does not run the user's gateway, shell, code-server, apps, or app database in production. It resolves who the user is and proxies to that user's VPS. ## Customer VPS Runtime [#customer-vps-runtime] Each customer VPS is bootstrapped by cloud-init and the Matrix host bundle. Runtime files: * `/opt/matrix/env/host.env`: machine identity, handle, Clerk user id, `DATABASE_URL`, `PLATFORM_INTERNAL_URL`, and per-host tokens. * `/opt/matrix/env/r2.env`: R2 credentials for backup/sync. * `/opt/matrix/app`: gateway, shell, packages, and bundled default apps. * `/opt/matrix/runtime`: Node, code-server, and bundled coding-agent CLIs. * `/opt/matrix/bin`: launchers for gateway, shell, code, sync, and update. * `/home/matrix/home`: user-owned Matrix home. Services: * `matrix-gateway.service` runs the Hono gateway. * `matrix-shell.service` runs the Next.js shell. * `matrix-code.service` runs code-server. * `matrix-sync-agent.service` keeps sync flows moving. * `matrix-db-backup.timer` uploads Postgres snapshots. * Nginx terminates local HTTPS and routes to shell/gateway/code. Each customer VPS has its own local Postgres endpoint at `127.0.0.1:5432`. The current bootstrap starts it as a single machine-local `postgres:16` service container named `matrix-postgres` with a local volume. This is not the legacy shared user-runtime container model. ## Gateway [#gateway] `packages/gateway/` is the user runtime API. It runs on the customer VPS and owns: * chat/WebSocket routes; * file serving from the Matrix home; * app discovery, build, launch, and proxying; * app data bridge routes; * canvas routes and realtime subscriptions; * terminal/workspace/session routes; * sync and home-mirror integration; * social and channel adapters where configured; * integration proxying back to platform-owned routes. When `DATABASE_URL` is set, the gateway connects to the customer-local Postgres database, bootstraps app/workspace tables, and registers app manifests with `storage.tables`. ## Shell [#shell] `shell/` is the primary visual renderer. It is a Next.js 16 + React 19 web shell. Canvas mode is the primary product surface; Desktop remains a compatibility shell. The shell handles: * app windows and built-ins; * Canvas layout and spatial workspaces; * chat surfaces; * file/app preview; * terminal/code entry points; * settings and integrations UI. Built-in paths such as `__workspace__`, `__terminal__`, `__file-browser__`, `__preview-window__`, and `__chat__` must be wired in every renderer so they never fall through to normal app file routing. ## Kernel [#kernel] `packages/kernel/` is the AI kernel layer. Current implementation uses Claude Agent SDK V1 `query()` with `resume`. Important pieces: * `spawnKernel()` starts or resumes kernel turns. * `buildSystemPrompt()` assembles identity, SOUL, skills, context, and rules. * IPC/MCP tools expose controlled system capabilities. * Hooks protect files, snapshot changes, and persist state. * Agent definitions and skills live as files so the OS can expand itself. The product principle is "AI is the kernel," but the runtime still has conventional services for routing, auth, storage, and UI. ## Apps [#apps] First-party and polished apps are Vite + React apps under the Matrix home. Bundled default apps are built by `scripts/build-default-apps.mjs` before host-bundle publication and copied into the user's home on gateway startup. App manifests use `matrix.json`. Apps that need structured data declare: ```json { "runtime": "vite", "build": { "command": "pnpm build", "output": "dist" }, "storage": { "tables": { "tasks": { "columns": { "text": "text", "done": "boolean" } } } } } ``` The gateway creates schema-per-app Postgres tables and exposes scoped CRUD through `/api/bridge/query`. App child processes intentionally do not receive raw `DATABASE_URL`. ## Request Flow [#request-flow] ### App Domain [#app-domain] 1. Browser requests `https://app.matrix-os.com`. 2. Cloudflare sends the request to the platform tunnel. 3. Platform verifies Clerk/session identity. 4. Platform finds the user's `running` `user_machines` row. 5. Platform proxies to `https://:443`. 6. Customer nginx routes shell/gateway/code requests to local services. ### App Data [#app-data] 1. App calls `/api/bridge/query`. 2. Gateway validates app/table/action payload. 3. Gateway uses Kysely against the customer-local Postgres database. 4. Gateway broadcasts generic data-change events after mutations. ## Data Boundaries [#data-boundaries] | Data | Owner | Location | | ------------------------------------------- | -------------------- | -------------------------- | | Platform users, machine rows, routing state | Platform | Platform Postgres | | Clerk sessions and auth verification | Platform/Clerk | Clerk + platform | | Pipedream provider credentials | Platform | Platform integration store | | User files and apps | User | Customer VPS Matrix home | | App/workspace data | User | Customer VPS Postgres | | Canvas documents | User | Customer VPS Postgres | | DB snapshots and VPS metadata | User/system recovery | R2 prefix | ## Developer Rules [#developer-rules] * Use Postgres/Kysely for new persistence. * Use Zod 4 from `zod/v4`. * Use Vite + React for first-party apps. * Use `/api/bridge/query` for app data, not direct app `DATABASE_URL`. * Keep platform secrets off customer VPSes unless they are explicitly per-host runtime tokens. * Add body limits, validation, timeouts, resource caps, and generic client errors on new routes. * Build and publish a customer host bundle when shell/gateway/default-app/runtime code changes. Older docs and specs may mention shared per-user Docker containers. Current production user runtime is per-user VPS with host services and local Postgres. Treat `/containers/*` as legacy/local-development compatibility unless you are explicitly working on that path. # Browser Automation (/docs/developer/browser-automation) Matrix OS can expose an in-process browser MCP server to the kernel when browser automation is enabled in `~/system/config.json`. ```json title="~/system/config.json" { "browser": { "enabled": true, "headless": true, "defaultProfile": "default", "timeout": 30000, "idleTimeout": 300000 } } ``` The kernel registers the `mcp__matrix-os-browser__browser` tool. Agents use it to navigate pages, inspect accessibility snapshots, fill forms, manage tabs, capture screenshots, save PDFs, and read browser console output. ## Persistent Profiles [#persistent-profiles] The browser tool launches Chromium with a Playwright persistent context. Cookies, local storage, and login state are stored under the owner-controlled Matrix home: ```text ~/data/browser-profiles/{profile}/ ``` Use the `profile` argument to keep independent login lanes: ```json { "action": "navigate", "profile": "github-work", "url": "https://github.com/login" } ``` Profile names are lowercase slugs such as `default`, `work`, or `github-work`. Matrix keeps one active browser session at a time; switching profiles closes the active browser before opening the requested profile. ## Security [#security] * Navigation only accepts `http` and `https`. * Local, private, link-local, multicast, documentation, and internal host targets are blocked before navigation. * Page and tab network requests run through the same guard, so public pages cannot use the agent browser to request private/internal resources. * Hostname targets are DNS-preflighted. This is not DNS pinning, so DNS rebinding remains a residual risk until Matrix routes browser traffic through a dispatcher that pins resolved addresses. * Screenshot and PDF output paths are confined to `~/data/screenshots/`. * Browser page text, snapshots, console output, and evaluate output are wrapped as untrusted external content before they reach the agent. Prefer `WebSearch` or `WebFetch` for simple public information retrieval. Use the browser tool when a task needs dynamic UI interaction, login state, screenshots, or JavaScript-rendered content. ## Design Notes [#design-notes] Matrix follows the local persistent-profile path from OpenClaw's browser design: a dedicated agent browser profile instead of the user's daily browser profile, with deterministic actions and screenshots. Hermes adds useful future directions such as cloud provider routing, Browser Use, Camofox persistence, CDP attach, VNC live view, and private-URL routing, but Matrix's default runtime starts with local owner-controlled Playwright profiles. # Contributing (/docs/developer/contributing) ## Getting Set Up [#getting-set-up] ### Fork and clone [#fork-and-clone] ```bash git clone https://github.com/hamedmp/matrix-os.git cd matrix-os ``` ### Install dependencies [#install-dependencies] ```bash corepack enable && corepack prepare pnpm@latest --activate pnpm install ``` ### Verify your environment [#verify-your-environment] ```bash bun run test # Should pass 993+ tests bun run dev # Gateway on :4000, Shell on :3000 ``` ## Development Rules [#development-rules] * **TDD**: Write failing tests first, then implement (Red -> Green -> Refactor) * **TypeScript strict mode**: No `any` types, full type safety * **ES modules**: `"type": "module"` everywhere * **Minimal comments**: Code should be self-documenting * **Production topology**: customer runtime is per-user VPS with host services and local Postgres, not the legacy shared user-container path * **No emojis** in code or docs unless explicitly requested * **Kysely/PostgreSQL** for all database access * **pnpm** for installing, **bun** for running scripts ## Commit Conventions [#commit-conventions] All commits and PR titles use [Conventional Commits](https://www.conventionalcommits.org/): | Prefix | Use | | ----------- | --------------------------------------- | | `feat:` | New feature | | `fix:` | Bug fix | | `test:` | Adding or updating tests | | `refactor:` | Code restructuring (no behavior change) | | `chore:` | Dependencies, tooling, config | | `ci:` | CI/CD changes | | `docs:` | Documentation | | `perf:` | Performance improvement | Commit messages should be concise and focus on **why**, not **what**. ## Spec-Driven Development [#spec-driven-development] Major features start with a spec in `specs/`. Each spec directory contains: * **`spec.md`** -- architecture document describing the design * **`tasks.md`** -- task breakdown with IDs (e.g., T100-T105) The spec numbering follows a sequential scheme: ``` specs/003-architecture/ # Phase 3 (archive) specs/004-concurrent/ # Phase 7: Multiprocessing specs/005-soul-skills/ # Phase 9: SOUL + Skills specs/006-channels/ # Phase 10: Multi-channel ... specs/031-desktop-customization/ # Desktop theming ``` Read existing specs to understand the pattern before proposing new features. ## Coordination Rules [#coordination-rules] When working on a spec: * Avoid modifying files outside your spec scope without lead approval * **Shared files** (`ipc-server.ts`, `config.json`, `prompt.ts`, `server.ts`) -- new additions should be additive, never modify existing structures * All tests must pass before declaring a task complete * Commit after each completed task group with descriptive messages The kernel system prompt must stay under 7K tokens. Use skills (demand-loaded) and knowledge files instead of bloating the base prompt. ## Project Structure [#project-structure] ``` packages/kernel/ # AI kernel (Agent SDK, agents, IPC, hooks, SOUL, skills) packages/gateway/ # Hono HTTP/WebSocket gateway + channels + cron + heartbeat packages/platform/ # Control plane: Clerk auth, VPS provisioning/routing, integrations shell/ # Next.js 16 web desktop (one of many shells) www/ # matrix-os.com website home/ # File system template (copied on first boot) tests/ # Vitest test suites (993+ tests) specs/ # Architecture specifications distro/ # customer VPS, cloudflared, systemd, and local dev configs ``` ## Environment Variables [#environment-variables] | Variable | Default | Description | | ------------------------- | ------------------------ | ------------------------------- | | `ANTHROPIC_API_KEY` | -- | Required for kernel AI features | | `MATRIX_HOME` | `~/matrixos/` | Home directory path | | `MATRIX_AUTH_TOKEN` | -- | Bearer token for web shell auth | | `PORT` | `4000` | Gateway port | | `NEXT_PUBLIC_GATEWAY_WS` | `ws://localhost:4000/ws` | Shell WebSocket URL | | `NEXT_PUBLIC_GATEWAY_URL` | `http://localhost:4000` | Shell HTTP URL | ## Releases [#releases] Tags follow SemVer with `v` prefix (`v0.1.0`, `v0.2.0`). Pre-1.0: minor = features, patch = fixes. ```bash bun run test # verify git tag -a v0.X.0 -m "Description" # tag git push origin v0.X.0 # push tag ``` # Dev VPS (/docs/developer/dev-vps) The dev VPS workflow treats a Matrix computer as the development machine. This is the same shape as production customer runtime: a user-owned home directory, local services, shell sessions, previews, and agent CLIs. ## What lives on the VPS [#what-lives-on-the-vps] * Source repositories under `~/projects`. * Runtime state and owner files under the Matrix home. * Terminal sessions backed by zellij. * Shell, gateway, code-server, sync, and agent CLIs from the host bundle. * A local owner-controlled Postgres endpoint for app/workspace data. ## Recommended workflow [#recommended-workflow] ```bash matrix login matrix shell connect -c dev matrix run -it --session dev -- gh auth login matrix run -it --session dev -- codex ``` Clone work into `~/projects`, run dev servers inside Matrix, and expose previews through the Matrix-authenticated routes instead of ad hoc public tunnels when possible. ## Development rules [#development-rules] * Keep platform-owned secrets on the platform. Do not copy Pipedream, Clerk, Gmail, GitHub, Slack, or provider secrets into customer VPS env files. * Use Matrix gateway/platform APIs for authenticated integration actions. * Prefer named sessions so the web shell, CLI, and agents can reattach predictably. * If zellij session creation fails, run `matrix shell ls` and connect to an existing session instead of retrying blindly. Customer-facing Matrix OS does not ship through Docker Compose or rolling container restarts. Shell/gateway changes for existing customers need a host-bundle rebuild, publish, and VPS refresh. ## Related [#related] * [Cloud Coding](/docs/guide/cloud-coding) * [Releases](/docs/developer/releases) # Contributor Overview (/docs/developer) This section covers Matrix OS for contributors who want to understand the architecture, contribute to the project, build apps, operate dev VPSes, or extend the agent/skill system. For a comprehensive, always-up-to-date reference generated from the source code, see the [Matrix OS DeepWiki](https://deepwiki.com/HamedMP/matrix-os/). ## Tech Stack [#tech-stack] | Layer | Technology | | --------------- | ------------------------------------------------------------------------ | | Language | TypeScript 5.5+ (strict mode, ES modules) | | Runtime | Node.js 24+ | | AI | Claude Agent SDK V1 (`query()` + `resume`) with Opus 4.6 | | Frontend | Next.js 16, React 19 | | Backend | Hono (platform control plane + customer gateway) | | Channels | node-telegram-bot-api, @whiskeysockets/baileys, discord.js, @slack/bolt | | Federation | Matrix protocol (matrix-js-sdk) | | Database | PostgreSQL via Kysely for platform and customer-local app/workspace data | | Validation | Zod 4 (`zod/v4` import) | | Scheduling | node-cron + native timers | | Testing | Vitest (99-100% coverage target, `@vitest/coverage-v8`) | | Package Manager | pnpm (install), bun (scripts) | ## Key Concepts [#key-concepts] ### Kernel = Agent SDK [#kernel--agent-sdk] The `spawnKernel()` function in `packages/kernel/src/spawn.ts` is the entry point. It calls `query()` for initial prompts and `resume` for multi-turn conversations. The `kernelOptions()` function in `packages/kernel/src/options.ts` configures the kernel with the system prompt, IPC servers, agent definitions, and hooks. ### Platform + Customer VPS Runtime [#platform--customer-vps-runtime] Production Matrix OS has a shared platform control plane and one customer VPS per independently billed computer. A user can own multiple computers, each identified by a runtime slot and protected by its own subscription. The platform owns Clerk auth, routing, provisioning, integrations, and host-bundle publication. Each customer VPS runs that computer's gateway, shell, code editor, apps, local Postgres, sync, and backups. ### Apps = Vite + React By Default [#apps--vite--react-by-default] First-party and polished apps should be Vite + React projects with `runtime: "vite"` and `build.output: "dist"` in `matrix.json`. Apps that need structured data declare `storage.tables`; the gateway creates schema-per-app Postgres tables and exposes access through `/api/bridge/query`. App processes should not receive raw `DATABASE_URL`. The bridge API is the intended scoped route into the user's local Postgres database. ### IPC via MCP [#ipc-via-mcp] The kernel communicates with the system through 26 IPC tools exposed as an in-process MCP server via `createSdkMcpServer()`. Each tool is defined with `tool()`, a Zod schema for input validation, and an async handler. ### Hooks [#hooks] Hooks intercept agent actions at defined lifecycle points. `PreToolUse` hooks run before tool execution (safety guards, protected files). `PostToolUse` hooks run after (git snapshots, state updates, shell notifications). A `Stop` hook persists the session. ### Dispatch Queue [#dispatch-queue] The gateway's dispatcher manages a serial FIFO queue by default, ensuring only one kernel call runs at a time to prevent file system corruption. It can be configured for concurrent dispatch with `maxConcurrency`, where each process registers in the PostgreSQL `tasks` table. ## Developer Resources [#developer-resources] # IPC Tools & Hooks (/docs/developer/ipc-tools) ## IPC Tool System [#ipc-tool-system] The kernel interacts with the system through IPC tools exposed as an in-process MCP server. The `createIpcServer()` function in `packages/kernel/src/ipc-server.ts` creates a server named `matrix-os-ipc` using `createSdkMcpServer()`. Each tool is defined with: * **Name** -- the tool identifier (e.g., `list_tasks`) * **Description** -- what the tool does (helps the agent decide when to use it) * **Zod schema** -- input validation * **Handler** -- async function that executes the tool's logic ## Available IPC Tools [#available-ipc-tools] ### Task Management [#task-management] | Tool | Description | | --------------- | -------------------------------------------------- | | `list_tasks` | List tasks with optional status/assignee filtering | | `create_task` | Create a new task for an agent | | `claim_task` | Claim an unassigned pending task | | `complete_task` | Mark a task as completed with output | | `fail_task` | Mark a task as failed with error details | ### Messaging [#messaging] | Tool | Description | | --------------- | --------------------------------------- | | `send_message` | Send a message (inter-agent or to user) | | `read_messages` | Read messages from the message queue | | `read_state` | Read the current system state | ### Skills & Knowledge [#skills--knowledge] | Tool | Description | | ------------ | ----------------------------------------------- | | `load_skill` | Load a skill's full body into context on demand | ### Identity & Sync [#identity--sync] | Tool | Description | | ------------ | ------------------------------------------------ | | `set_handle` | Set the user's federated handle | | `sync_files` | Git commit, push, and pull for cross-device sync | ### Scheduling [#scheduling] | Tool | Description | | ------------- | ------------------------------------------ | | `manage_cron` | Create, update, delete, and list cron jobs | ### Integrations [#integrations] | Tool | Description | | ----------------- | -------------------------------------------------------------------------------------- | | `connect_service` | Connect an external service (Gmail, Calendar, Drive, GitHub, Slack, Discord) via OAuth | | `call_service` | Call a connected service action (send email, list events, post message, etc.) | See the [Integrations guide](/docs/guide/integrations) for the full action reference. ### Onboarding [#onboarding] | Tool | Description | | ------------------------- | ----------------------------------- | | `get_persona_suggestions` | Get persona-based setup suggestions | | `write_setup_plan` | Write a personalized setup plan | ### File Tools (SDK Built-in) [#file-tools-sdk-built-in] In addition to IPC tools, agents have access to standard file tools via the Agent SDK: | Tool | Description | | ------- | --------------------------- | | `Read` | Read file contents | | `Write` | Write/create files | | `Edit` | Edit existing files | | `Glob` | Search for files by pattern | | `Grep` | Search file contents | | `Bash` | Execute shell commands | These are tracked by the `FILE_TOOLS` constant and controlled per-agent via `allowedTools` and `disallowedTools`. ## Hook System [#hook-system] Hooks intercept agent actions at specific lifecycle points. They're configured in `kernelOptions()` and defined in `packages/kernel/src/hooks.ts`. ### PreToolUse Hooks [#pretooluse-hooks] Run **before** a tool executes. Can block or modify the tool call. | Hook | Applied To | Purpose | | -------------------- | ----------------- | --------------------------------------------- | | `safetyGuardHook` | Bash, Write, Edit | Prevents dangerous commands (rm -rf, etc.) | | `protectedFilesHook` | Write, Edit | Blocks modifications to critical system files | ### PostToolUse Hooks [#posttooluse-hooks] Run **after** a tool executes. Can observe or react to the result. | Hook | Applied To | Purpose | | ----------------- | ----------- | ------------------------------------------- | | `gitSnapshotHook` | Write, Edit | Creates a git commit after file changes | | `updateStateHook` | Write, Edit | Updates system state after file operations | | `notifyShellHook` | Write, Edit | Sends file:change event to connected shells | | `logActivityHook` | Bash | Logs shell command execution | ### Lifecycle Hooks [#lifecycle-hooks] | Hook | Event | Purpose | | -------------------- | ------------ | --------------------------------------------- | | `persistSessionHook` | Stop | Saves the conversation session on kernel exit | | `onSubagentComplete` | SubagentStop | Logs completion of sub-agent tasks | | `preCompactHook` | PreCompact | Runs before context window compaction | ## Permission Model [#permission-model] The kernel uses two mechanisms to control tool access: ### allowedTools [#allowedtools] A baseline allow-list set in `kernelOptions()` for the main kernel agent. Includes file tools, task management, web tools, and all IPC tools. In the Agent SDK, `allowedTools` controls which tools are auto-approved (skip user confirmation). It does NOT filter which tools are available. Use `tools` or `disallowedTools` to restrict access. ### Per-Agent Restrictions [#per-agent-restrictions] Each `AgentDefinition` can specify: * **`tools`** -- explicit allow-list (only these tools are available) * **`disallowedTools`** -- deny-list (these tools are blocked, all others allowed) For example, the Builder agent has access to `FILE_TOOLS` plus `claim_task`, `complete_task`, `fail_task`, and `send_message` from IPC tools -- but not `manage_cron` or `set_handle`. ### Permission Bypass [#permission-bypass] The kernel runs with `permissionMode: "bypassPermissions"` which propagates to all sub-agents. This means tool access control relies entirely on `allowedTools`/`disallowedTools` lists and `PreToolUse` hooks, not on a separate permission prompt. # Logging & Usage (/docs/developer/logging) Matrix OS provides structured logging for every kernel operation: dispatches, tool calls, agent spawns, file mutations, and costs. This data powers debugging, billing, security auditing, and usage dashboards. ## Interaction Logs [#interaction-logs] Every kernel dispatch is logged as a JSONL entry in `~/system/logs/`. Daily rotation is built in (one file per day). ### Log Entry Fields [#log-entry-fields] | Field | Type | Description | | ---------------- | ------- | -------------------------------------------------------- | | `timestamp` | string | ISO 8601 timestamp | | `senderId` | string | User or channel that triggered the dispatch | | `conversationId` | string | Session ID for conversation threading | | `model` | string | Claude model used (e.g., `claude-opus-4-6`) | | `agentName` | string | Which agent handled the request | | `tokensIn` | number | Input tokens consumed | | `tokensOut` | number | Output tokens generated | | `cost` | number | Dollar cost of the dispatch | | `durationMs` | number | Wall-clock time | | `tools` | array | Tool executions (see below) | | `status` | string | `success` or `error` | | `error` | object | Error details if failed (name, message, truncated stack) | | `batch` | boolean | Whether this was a batch dispatch entry | | `batchId` | string | Correlation ID for batch entries | ### Tool Execution Logging [#tool-execution-logging] Each tool call within a dispatch is recorded: ```json { "tools": [ { "name": "Write", "durationMs": 45, "inputPreview": "Write to ~/apps/chess/index.html (2.3KB)", "status": "success" }, { "name": "Bash", "durationMs": 3200, "inputPreview": "cd ~/apps/chess && pnpm install", "status": "success" } ] } ``` Tool outputs are not logged (too large). Only errors are captured from tool results. ### Structured Errors [#structured-errors] On dispatch failure, the error is captured with full context: ```json { "error": { "name": "ToolExecutionError", "message": "pnpm install failed with exit code 1", "stack": "Error: pnpm install failed...\n at runBuild (/packages/...)", "tool": "Bash", "turn": 3 } } ``` ## Usage Tracking [#usage-tracking] The usage tracker aggregates costs and token consumption per user: ### How It Works [#how-it-works] On each dispatch completion, cost and token data is recorded per `senderId`. Data is aggregated by user, model, and day, and persisted to `~/system/logs/usage.jsonl`. ### Usage API [#usage-api] ``` GET /api/usage?userId=hamed&startDate=2026-03-01&endDate=2026-03-31&groupBy=day ``` Response: ```json { "totalCost": 12.45, "totalTokensIn": 1250000, "totalTokensOut": 320000, "entries": [ { "date": "2026-03-01", "cost": 0.85, "tokensIn": 95000, "tokensOut": 24000, "dispatches": 12 } ] } ``` The usage endpoint requires a valid session or admin token. ### Cost Limits [#cost-limits] Per-user cost limits are configurable in `~/system/config.json`: ```json { "costLimits": { "daily": 10.00, "monthly": 100.00 } } ``` When a user exceeds their limit, the dispatcher rejects new dispatches with HTTP 429 and a message: "Daily cost limit reached." Set a limit to 0 for unlimited. ## File Audit Trail [#file-audit-trail] A lightweight audit log tracks all file mutations performed by the kernel. Written to `~/system/logs/audit.jsonl`. ### Audit Entry Format [#audit-entry-format] ```json { "timestamp": "2026-03-04T10:30:00Z", "op": "write", "path": "apps/chess/index.html", "sizeBytes": 2340, "actor": "builder", "agentName": "builder" } ``` | Field | Description | | ----------- | ------------------------------------------------------ | | `op` | Operation: `write`, `delete`, `mkdir` | | `path` | Relative path within `~/matrixos/` | | `sizeBytes` | Size of the written file | | `actor` | Agent or system component that performed the operation | | `agentName` | Name of the kernel agent | ### Instrumentation [#instrumentation] File mutations are detected via `PreToolUse` and `PostToolUse` hooks on the `Write`, `Edit`, and `Bash` tools. Read operations are not audited (too noisy). The audit logger (`packages/kernel/src/audit.ts`) uses async buffered writes to avoid blocking kernel operations. ## Log Rotation [#log-rotation] | Log File | Rotation | Retention | | ---------------- | --------------------------------------------- | --------- | | `activity.log` | Daily (rename to `activity-{YYYY-MM-DD}.log`) | 30 days | | `audit.jsonl` | Daily (rename to `audit-{YYYY-MM-DD}.jsonl`) | 30 days | | Interaction logs | Already daily by filename | 30 days | Rotation runs in the heartbeat service (daily check). Files older than 30 days are deleted automatically. ## Log Files Summary [#log-files-summary] | File | Location | Format | Contents | | ---------------- | ----------------------------------------- | ------ | ---------------------------------------- | | Interaction logs | `~/system/logs/interactions-{date}.jsonl` | JSONL | Dispatch events with tokens, cost, tools | | Activity log | `~/system/logs/activity.log` | Text | General system activity | | Audit log | `~/system/logs/audit.jsonl` | JSONL | File mutation events | | Usage log | `~/system/logs/usage.jsonl` | JSONL | Per-user cost aggregation | | Storage log | `~/system/logs/storage.jsonl` | JSONL | Daily storage measurements | | Backup log | `~/system/logs/backup.jsonl` | JSONL | Postgres backup status | # Releases (/docs/developer/releases) Production Matrix OS runtime is VPS-native per user. Releases publish immutable host bundles, register release metadata, promote channels, and update customer VPSes in place. ## Release shape [#release-shape] * R2 stores immutable host bundle bytes at `system-bundles//matrix-host-bundle.tar.gz`. * Platform Postgres stores release metadata and channel pointers. * Each VPS records its installed version at `/opt/matrix/release.json`. * The gateway captures its running version once at process startup from `/opt/matrix/app/BUNDLE_VERSION`. * Updates replace `/opt/matrix/app` and runtime bundle contents, not owner data under the Matrix home. ## Installed versus running identity [#installed-versus-running-identity] Installed release metadata and running process identity answer different questions. The release file records which artifact an update installed; it does not prove that systemd replaced the old gateway process. `/api/system/info` reports both values, while `/health` reports the startup-captured running version used by update verification. The updater must stop all runtime services before replacing `/opt/matrix/app`. After the new services start, it waits for the gateway to report the exact candidate version. Only then may it commit installed release metadata. A missing or mismatched running version fails verification and restores the previous app tree instead of leaving a release that looks installed while old code is still serving requests. ## Channels [#channels] | Channel | Typical source | | -------- | ------------------------------------------------------- | | `dev` | Main branch host-bundle workflow. | | `canary` | Version tags or manual dispatch for early verification. | | `beta` | Wider pre-stable validation. | | `stable` | Production promotion after live verification. | ## Golden snapshot trigger [#golden-snapshot-trigger] Golden VPS snapshots are a forward-only acceleration for new machine creation. Promoting an eligible immutable host bundle to `stable` records the stable pointer, eligibility, and exact snapshot build request in one platform transaction. Stable promotions default to eligible and can explicitly opt out; other channels do not automatically enqueue snapshot builds. The worker does not scan historical releases for missing snapshots. A newer stable promotion supersedes unfinished older build work, while historical release and audit records remain intact. Provisioning selects a ready snapshot only when its immutable bundle SHA-256 exactly matches the requested release; otherwise it uses the clean Ubuntu path. Snapshot building and snapshot selection remain separately controlled. A stable promotion can record durable work while build workers or customer selection are disabled for rollout safety. ## Local emergency build [#local-emergency-build] ```bash set -a source .env set +a HOST_BUNDLE_VERSION= HOST_BUNDLE_CHANNEL= MATRIX_BUILD_SHA=$(git rev-parse HEAD) MATRIX_BUILD_REF=main ./scripts/build-host-bundle.sh ``` ## Publish [#publish] ```bash ./scripts/publish-release.sh --channel ``` ## Verify [#verify] For every target VPS, verify: * `/opt/matrix/app/BUNDLE_VERSION` * `/opt/matrix/release.json` * `/health` reports the same running version as the installed candidate * `matrix-gateway` * `matrix-shell` * `matrix-sync-agent` * local health Never overwrite user-owned Matrix home data during an update: desktop state, themes, wallpapers, icons, identity, profile, sessions, logs, memory, conversations, app data, and project files must remain owner-controlled. # Review Pipeline (/docs/developer/review-pipeline) Matrix OS uses a strict review pipeline because the project mixes kernel, gateway, platform, shell, docs, and customer VPS runtime changes. ## Pre-PR checklist [#pre-pr-checklist] ```bash bun run typecheck bun run check:patterns bun run test npx react-doctor@latest ``` Run React Doctor whenever a `.tsx` or `.jsx` file changes in `shell/`, `home/apps/**`, `packages/ui/`, or `www/`. ## Review passes [#review-passes] 1. **Mechanical sweep**: run the pattern scanner and fix bare catches, fetches without timeout signals, sync file I/O in request paths, and unbounded in-memory collections. 2. **Trust-boundary sweep**: classify changed files as route handler, filesystem, database, WebSocket/IPC, or UI state, then trace external input from entry to use. 3. **Atomicity and failure-mode review**: identify source of truth, lock/transaction scope, partial failure states, shutdown behavior, and explicitly deferred scope. ## Common hard rules [#common-hard-rules] * Every related multi-write database mutation needs a transaction or one targeted SQL statement. * Every external `fetch()` needs `signal: AbortSignal.timeout(ms)`. * Mutating endpoints need body limits and route-boundary validation. * Never expose provider names, raw database errors, filesystem paths, or raw Zod issues to clients. * Every long-lived `Map` or `Set` needs a cap and eviction policy. * Browser WebSocket auth needs explicit query-token support because browsers cannot set `Authorization` headers on upgrades. ## PR discipline [#pr-discipline] All changes ship from a manual git worktree through a PR. Conventional Commit titles are required. Backend PRs should include source of truth, lock/transaction scope, acceptable orphan states, auth source of truth, and deferred scope. See the internal reference: `docs/dev/review-pipeline.md`. # Skills System (/docs/developer/skills) The skills system enables demand-loaded capabilities for the AI kernel. Matrix-shipped coding skills use the Agent Skills directory format: `SKILL.md` plus optional supporting files. The canonical Matrix pack lives in `skills/matrix/` and is synced into runtime discovery paths for Matrix, Claude Code, Codex, and Hermes. ## Skill Format [#skill-format] ```md title="~/.agents/skills/matrix-app-builder/SKILL.md" --- name: matrix-app-builder description: Build Matrix OS apps as Vite React TypeScript projects with matrix.json manifests, Matrix theme integration, Postgres-backed app data, and production build verification. license: MIT metadata: version: 1.0.0 author: Matrix OS platforms: [linux, macos] agent: tags: [Matrix OS, apps, Vite, React, TypeScript] related_skills: [matrix-design-system, matrix-integrations, matrix-debug-app] --- Default to Vite, React 19, TypeScript, `runtime: "vite"`, and Matrix/Postgres bridge APIs. ... ``` ## Frontmatter Schema [#frontmatter-schema] Skills are validated at boot time with a Zod schema in `packages/kernel/src/skills.ts`: | Field | Type | Required | Description | | ----------------------------------------- | --------- | -------- | --------------------------------------------------------------------------------------------- | | `name` | string | Yes | Unique skill identifier | | `description` | string | Yes | Short description (shown in skills TOC) | | `license` | string | No | Skill license | | `metadata` | object | No | Agent Skills-compatible metadata such as version, author, platforms, tags, and related skills | | `triggers`, `examples`, `composable_with` | string\[] | No | Matrix legacy extensions still accepted | ### Validation Behavior [#validation-behavior] * Missing `name` or `description`: error logged, skill skipped * Unknown fields: ignored (forward-compatible) * Malformed YAML: skill file skipped with a warning * All validation happens in `loadSkills()` at kernel boot ## Skill Loading Flow [#skill-loading-flow] 1. **Sync**: `scripts/sync-matrix-agent-skills.sh` projects `skills/matrix/` into runtime skill folders. 2. **Boot**: `loadSkills()` reads `~/.agents/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md`, and legacy flat files if present. 3. **TOC injection**: `buildSkillsToc()` creates a concise table of contents injected into the system prompt. 4. **On-demand load**: the `load_skill` IPC tool fetches the full skill body into the agent's context. 5. **Composable loading**: if the loaded skill has `composable_with`, companion skills are auto-loaded too. The skill loader tracks which skills have already been loaded in the current session. Circular `composable_with` references are detected and skipped. ## Skill Caching [#skill-caching] To avoid redundant disk reads: * **Memory cache**: an in-memory `Map` stores skill bodies after first read * **Cache invalidation**: the file watcher clears a cache entry when a skill file changes on disk Knowledge files (e.g., `app-generation.md`) are also cached at kernel boot via `getKnowledge(name)`. ## Matrix App-Building Pack [#matrix-app-building-pack] Matrix OS ships 19 internal skills in three functional groups: | Group | Skills | Covers | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Matrix app foundation | `matrix-app-builder`, `matrix-app-ui-patterns`, `matrix-design-system`, `matrix-integrations`, `matrix-dev-vps`, `matrix-debug-app` | Vite React apps, manifests, Postgres bridge access, integrations, current Matrix brand, user-taste adaptation, localhost previews, builds, and debugging | | Motion decisions and implementation | `animate`, `css-animations`, `motion-react`, `gesture-ui`, `scroll-animations`, `animation-vocabulary` | Purpose, vocabulary, CSS/WAAPI, Motion React, gestures, layout/shared-element transitions, and scroll motion | | Motion quality | `animation-accessibility`, `animation-performance`, `debug-animation`, `find-animation-opportunities`, `improve-animations`, `review-animations`, `pick-ui-library` | Reduced motion, performance, debugging, opportunity discovery, audits, review standards, and library choice | `skills/matrix/` is the source of truth. `scripts/sync-matrix-agent-skills.sh` projects it into supported runtime paths and records Matrix-owned entries in `.matrix-os-managed-skills`. A later sync can replace or retire those managed entries without deleting a user's own skills. The builder loads the foundation skills explicitly before app work. It treats Matrix's palette and typography as the shell/system frame, creates a short taste brief from the user's references and app domain, and loads only the motion skills the interface actually needs. ## Public skills.sh Pack [#public-skillssh-pack] The user-installable pack is intentionally smaller than the Matrix-computer pack. `plugins/matrix-os/skills/` exposes `matrix-onboarding`, `matrix-cloud-run`, and `matrix-github-project`; it does not copy internal app-generation policy onto the user's local computer. The repository pins skills.sh `1.5.23` in `scripts/install-public-matrix-skills.sh`: ```bash ./scripts/install-public-matrix-skills.sh ``` That script installs the GitHub subdirectory globally with `--all`. Keep the CLI version exact and review a newer release against the repository's dependency-age policy before updating it. ## Build Pipeline [#build-pipeline] Generated user-facing apps default to Vite + React. Plain HTML apps are only for explicit throwaway requests. ### Offline-First Builds [#offline-first-builds] * pnpm store path configured in `~/system/.pnpm-store` * `pnpm install --prefer-offline` skips registry checks when packages are cached * Common dependencies (react, react-dom, vite, typescript) pre-populated in the store ### Template Projects [#template-projects] Pre-built scaffolds in `~/templates/react-app/` are copied and modified (only `App.tsx` + `App.css` change). Skips `pnpm install` when `node_modules` already exist. ### Build Error Recovery [#build-error-recovery] On build failure: 1. Parse the error 2. Attempt a single fix 3. Rebuild (max 2 retries) 4. If still failing: report the blocker with the exact failing command and keep the Vite project intact ## Publishing and Installing Skills [#publishing-and-installing-skills] Skills are shareable through the [App Store](/docs/guide/app-store): | IPC Tool | Description | | --------------- | -------------------------------------------------------------------------- | | `publish_skill` | Validates and pushes a local skill to the platform registry | | `install_skill` | Downloads a skill from the registry to `~/.agents/skills//SKILL.md` | See the [App Store docs](/docs/guide/app-store) for store UI and browsing. # Testing (/docs/developer/testing) ## TDD is Non-Negotiable [#tdd-is-non-negotiable] Matrix OS follows strict Test-Driven Development. Every feature starts with a failing test: 1. **Red** -- write a failing test that describes the desired behavior 2. **Green** -- write the minimum code to make it pass 3. **Refactor** -- clean up while keeping tests green If a test can't be written for a feature, its necessity is questioned. This is a core development principle. ## Coverage Target [#coverage-target] **99-100%** across kernel and gateway packages. Current state: **993+ tests** across 85+ test files. ## Running Tests [#running-tests] ```bash bun run test # Unit tests (~993 tests, ~11s) bun run test:watch # Watch mode for development bun run test:coverage # Generate coverage report bun run test:integration # Integration tests (needs ANTHROPIC_API_KEY) ``` ## Test Structure [#test-structure] Tests live in `tests/` at the project root, organized by package: ``` tests/ kernel/ # Kernel unit tests spawn.test.ts # spawnKernel() tests options.test.ts # kernelOptions() tests prompt.test.ts # buildSystemPrompt() tests ipc-server.test.ts # IPC tool tests agents.test.ts # Agent loading and parsing tests hooks.test.ts # Hook behavior tests soul.test.ts # SOUL identity tests gateway/ # Gateway unit tests dispatcher.test.ts # Dispatch queue tests watcher.test.ts # File watcher tests channels/ # Channel adapter tests cron.test.ts # Cron service tests heartbeat.test.ts # Heartbeat tests shell/ # Shell component tests integration/ # Integration tests (real API calls) e2e/ # End-to-end tests (101 tests across 13 files) ``` ## Test Categories [#test-categories] ### Unit Tests [#unit-tests] Pure function tests with mocked dependencies. Use `vi.mock()` for external services. One test file per source module. ### Integration Tests [#integration-tests] Make real API calls to Claude. Requirements: * `ANTHROPIC_API_KEY` environment variable set * Uses Claude Haiku model to keep costs under **$0.10 per run** * Run separately: `bun run test:integration` ### Contract Tests [#contract-tests] Verify IPC tool schemas match their implementations. Ensure Zod schemas correctly validate inputs and tools return expected shapes. ### E2E Tests [#e2e-tests] Full system tests covering 101 scenarios across 13 files. Test the complete flow from user input through the gateway to kernel response. ## Spike Before Spec [#spike-before-spec] For undocumented SDK behavior, write a throwaway spike test against the real SDK before committing to an approach. Spike files go in `spike/` and are excluded from the main test suite. This prevents building on unverified assumptions. ## Writing Tests [#writing-tests] Conventions: * Descriptive `describe` blocks matching module structure * Test names describe the expected behavior, not the implementation * Use `vi.mock()` for external dependencies (API calls, file system) * Keep tests focused -- one assertion per `it` block when practical * Integration tests are clearly separated and use Claude Haiku # Agent System (/docs/guide/agents) The kernel doesn't handle everything itself. It delegates to five specialized sub-agents, each with its own prompt, tools, and personality. The kernel selects which agent to spawn based on the user's request. This architecture follows a broader shift toward agents that can work through complete tasks instead of only suggesting code. GitHub documents coding agents that research a repository, change code on a branch, and open a pull request for review ([GitHub Docs](https://docs.github.com/en/copilot/get-started/features)). Claude Code likewise supports resumable sessions and explicit turn limits for unattended commands ([Anthropic CLI reference](https://docs.anthropic.com/en/docs/claude-code/cli-usage)). Matrix applies those patterns inside its own kernel and persistent workspace. ## Core Agents [#core-agents] The five core agents are defined in `packages/kernel/src/agents.ts` and their prompts live in `home/agents/custom/` as markdown files. Generates software from natural language. Creates HTML apps in `~/apps/` or React modules in `~/modules/`. Has access to file tools and task management IPC tools. Investigates problems, reads docs, gathers context from the web or local files. Uses web fetch and search tools to find information. Ships code to production. Manages module deployment including starting, stopping, and validating services. Handles infrastructure provisioning. Detects and repairs broken modules autonomously. Often spawned by the heartbeat system without user intervention. Restores files from git snapshots. Grows the OS's capabilities. Writes new agent prompts, skills, and knowledge files. Modifies the system's own interface and behavior. ## How Agent Selection Works [#how-agent-selection-works] ``` User message | +---> Kernel (main agent) | +---> Reads agent descriptions from AgentDefinition records +---> Selects the best agent based on request +---> Spawns sub-agent via Agent SDK Task tool +---> Sub-agent executes with its own tools and prompt +---> Result flows back to kernel -> user ``` The `kernelOptions()` function in `packages/kernel/src/options.ts` assembles the agent set by calling `getCoreAgents()` for built-in agents and `loadCustomAgents()` for user-defined agents from `~/agents/custom/`. ## AgentDefinition [#agentdefinition] Each agent is represented by an `AgentDefinition` object with: * **`description`** -- used by the kernel to decide when to spawn this agent * **`prompt`** -- the agent's system prompt (from the markdown file body) * **`tools`** -- explicit allow-list of tools the agent can use * **`disallowedTools`** -- tools to deny (alternative to `tools`) * **`model`** -- which Claude model to use (defaults to Opus) * **`maxTurns`** -- maximum conversation turns before stopping ## Custom Agents [#custom-agents] Create your own agent by adding a markdown file to `~/matrixos/agents/custom/`: ```md title="~/matrixos/agents/custom/analyst.md" --- name: analyst description: Analyzes data files and produces reports with visualizations model: claude-sonnet-4-6 maxTurns: 10 --- You are a data analyst agent. When given data files, you: 1. Read and understand the data structure 2. Identify patterns and anomalies 3. Create visualizations as HTML files 4. Write a summary report Always save outputs to ~/data/reports/. ``` Custom agents override core agents if they share the same name. The `parseFrontmatter()` function extracts YAML metadata and the prompt body. ## SOUL Identity [#soul-identity] The SOUL system defines your AI's personality. Three files in `~/matrixos/system/` shape every interaction: | File | Purpose | | ------------- | ------------------------------------------------------------------------------------------------------ | | `soul.md` | Core personality, values, and behavior rules. Injected into every kernel prompt at the L0 cache level. | | `identity.md` | Public identity: name, avatar, nature. Defines how the AI presents itself. | | `user.md` | Your profile and context. Helps the AI understand who it's talking to. | These are loaded by `buildSystemPrompt()` in `packages/kernel/src/prompt.ts` and injected into the system prompt for every kernel invocation. Change `~/matrixos/system/soul.md` to alter your AI's tone, style, and values. Changes take effect on the next message. ## Skills System [#skills-system] Skills are directory-based Agent Skills in `~/.agents/skills//SKILL.md` that extend what the kernel can do. They use a demand-loading pattern to keep the context window lean. The open specification recommends keeping the main `SKILL.md` below 500 lines and loading supporting references only when needed. It describes three disclosure levels: compact metadata at startup, full instructions on activation, and supporting resources on demand ([Agent Skills specification](https://openagentskills.dev/docs/specification)). ### How Skills Work [#how-skills-work] 1. **TOC in prompt** -- `buildSkillsToc()` generates a table of contents listing all skills. This is injected into the system prompt so the kernel knows what's available. 2. **Trigger matching** -- each skill has a `description` in its frontmatter that helps the model choose when to load it. 3. **On-demand loading** -- when a request matches, the kernel calls the `load_skill` IPC tool to fetch the full skill body into context. ### Skill File Format [#skill-file-format] ```md title="~/.agents/skills/matrix-app-builder/SKILL.md" --- name: matrix-app-builder description: Build Matrix OS apps as Vite React TypeScript projects with matrix.json manifests, Matrix theme integration, Postgres-backed app data, and production build verification. version: 1.0.0 author: Matrix OS license: MIT --- Default to Vite, React 19, TypeScript, `runtime: "vite"`, and Matrix/Postgres bridge APIs. ``` ### Built-in Skills [#built-in-skills] Matrix OS ships a canonical coding pack under `skills/matrix/`: `matrix-app-builder`, `matrix-design-system`, `matrix-integrations`, `matrix-dev-vps`, and `matrix-debug-app`. Runtime startup syncs that pack into Matrix, Claude Code, Codex, and Hermes skill folders. ## Onboarding [#onboarding] The onboarding system uses a persona engine with 7 roles (developer, student, creative, etc.) to customize the initial setup. The `get_persona_suggestions` and `write_setup_plan` IPC tools drive this process, provisioning skills and configuring the system based on the user's needs. # App Store (/docs/guide/app-store) The App Store lets users discover, install, publish, and fork apps. Every published app gets a public URL that anyone can try without signing up. ## Browsing the Store [#browsing-the-store] Open the App Store from the dock or Cmd+K command palette. The store has three tabs: * **Apps** -- productivity tools, utilities, creative apps * **Games** -- playable games with leaderboards * **Skills** -- AI skills that teach your agent new capabilities ### Discovery [#discovery] * **Featured** -- curated apps picked by the platform * **Popular** -- sorted by installs in the last 7 days * **New** -- recently published * **Categories** -- game, productivity, utility, social, dev, creative * **Search** -- full-text search across names, descriptions, and tags * **Top Rated** -- sorted by user ratings (1-5 stars) ## Installing Apps [#installing-apps] Click "Install" on any app in the store. The app files download to `~/apps/{slug}/` and appear in your dock. Your data stays on your OS -- the publisher provides code, you provide storage. ## Publishing Apps [#publishing-apps] Publish your app by saying "publish my app" in chat or clicking "Publish" in the app settings. ### What Happens [#what-happens] 1. The AI validates your app (checks `matrix.json`, runs it, looks for errors) 2. The AI generates a description, screenshots, and tags if you haven't provided them 3. Files upload to the platform registry 4. Your app gets a public URL: `matrix-os.com/store/@handle/slug` 5. The app appears in the store (automated validation, no manual review for sandboxed apps) ### Publish Validation [#publish-validation] * `matrix.json` must include `name` and `description` * The app must start and pass a health check * Source code is scanned for leaked secrets (API keys, tokens) * Size limit: 50MB per app (configurable) * Rate limit: 10 publishes per day ### Publishing via IPC [#publishing-via-ipc] The `publish_app` IPC tool is available to agents: ``` publish_app({ appName: "chess", description?: "...", tags?: ["game", "strategy"] }) -> { url: "matrix-os.com/store/@hamed/chess", slug: "chess", version: "1.0.0" } ``` ## Public App URLs [#public-app-urls] Every published app gets two public URLs: | URL | Purpose | | ---------------------------------- | ------------------------------------------------------------- | | `matrix-os.com/store/@author/slug` | Store page: description, screenshots, ratings, install button | | `matrix-os.com/run/@author/slug` | Run page: try the app immediately in a sandbox | ### Run Page Behavior [#run-page-behavior] * **Anonymous visitor**: app runs in a temporary sandbox with no data persistence. Banner: "Sign up to save your progress." * **Logged-in user (not installed)**: app runs with data saved to the viewer's `~/data/{app}/` * **Logged-in user (installed)**: redirects to their own instance Data always lives on the viewer's OS, never the publisher's. The publisher provides code; the viewer provides storage. ## Forking Apps [#forking-apps] Click "Fork" on any public app to get your own editable copy: 1. App files are copied to `~/apps/{slug}/` 2. `forked_from` metadata is added to your local `matrix.json` 3. The app registers locally and appears in your dock 4. You can modify it freely -- it is just files 5. You can re-publish your fork (with attribution to the original author) Fork graphs are tracked in the registry. "Forked from @alice/chess" appears on the store page. The `fork_app` and `install_app` IPC tools are available to agents: ``` fork_app({ author: "alice", slug: "chess" }) install_app({ author: "alice", slug: "chess" }) ``` ## Ratings and Reviews [#ratings-and-reviews] After installing an app, you can rate it 1-5 stars. Ratings are averaged and displayed on the store page. Ratings drive the "Top Rated" sort order. ``` POST /api/store/apps/:id/rate { "rating": 5, "review": "Great chess AI!" } ``` ## Profiles [#profiles] Every user gets a Matrix profile surfaced through Matrix social/profile views: * **Signed in as owner**: edit your profile and published apps from Matrix. * **Signed in as another user**: view the public profile information that user has shared. ### Profile Customization [#profile-customization] The profile is backed by the Matrix profile app (`~/apps/profile/`). Customize it via chat: > Make my profile page dark and add my GitHub link Pre-built profile themes are available: minimal, developer, creative, gamer. ### Custom Domains [#custom-domains] Point your own domain to Matrix OS: 1. Set `custom_domain` in your profile settings 2. Add a CNAME record pointing to `matrix-os.com` 3. The platform generates a TLS certificate automatically ## Skills Store [#skills-store] Skills are publishable and installable alongside apps: | IPC Tool | Description | | --------------- | ------------------------------------------------------------------------- | | `publish_skill` | Push a local skill to the registry | | `install_skill` | Download a skill from the registry to `~/.agents/skills//SKILL.md` | Browse skills in the "Skills" tab of the App Store. Each skill shows name, description, author, and install count. One-click install. ## Store API Reference [#store-api-reference] | Endpoint | Method | Description | | ------------------------------- | ------ | --------------------------------------------- | | `/api/store/apps` | GET | List apps (pagination, category filter, sort) | | `/api/store/apps/:author/:slug` | GET | Single app detail | | `/api/store/apps/search?q=...` | GET | Full-text search | | `/api/store/apps/featured` | GET | Curated list | | `/api/store/apps` | POST | Create/update registry entry (auth required) | | `/api/store/apps/:id/rate` | POST | Submit rating (auth required) | | `/api/store/apps/:id/install` | POST | Track install | | `/api/store/skills` | GET | List skills | | `/api/store/skills/:name` | GET | Skill detail | | `/api/store/categories` | GET | Category list with counts | # Apps (/docs/guide/apps) Matrix OS apps are tools inside your workspace. Some are built in. Others can be created by Matrix when you describe what you need. You do not need to write code to get a useful app. Ask for the outcome, review what Matrix builds, and keep using or improving it. First-party and polished Matrix apps are Vite + React apps. They can have multiple screens, forms, tables, charts, saved state, and data stored in your Matrix database. ## What You Can Build [#what-you-can-build] Habits, budgets, subscriptions, workouts, medications, books, recipes, home inventory, travel plans, and routines. Lightweight CRMs, task boards, invoice trackers, meeting follow-ups, project dashboards, checklists, and internal request forms. Content calendars, script planners, moodboards, portfolio managers, campaign trackers, idea libraries, and publishing checklists. Flashcards, study planners, reading notes, spaced repetition helpers, class dashboards, and quiz apps. Chore boards, shared plans, event lists, meal planning, school reminders, moving checklists, and emergency info. Simple games, puzzles, party tools, scorekeepers, interactive stories, and custom dashboards for hobbies. ## Built-In Apps [#built-in-apps] Matrix ships with a growing set of default apps, including: * Notes and writing tools. * Task and board-style planning. * Profile and social surfaces. * Calculator, clock, weather, Pomodoro, and utility apps. * Games such as Solitaire, Chess, Backgammon, Snake, 2048, Minesweeper, and Tetris. * Whiteboard and visual workspace tools. These default apps are bundled into the Matrix host bundle so every user starts with a useful workspace. ## Asking Matrix To Build An App [#asking-matrix-to-build-an-app] Good app requests include: * what the app is for; * what information it should track; * what views you want; * whether it should be simple or polished; * any style preferences; * whether it should use connected services. Examples: > "Build me a budget tracker with monthly totals, categories, recurring expenses, and a simple chart." > "Create a CRM for my wedding photography leads. Track client name, event date, budget, status, notes, and next follow-up." > "Make a study planner for my biology exam with flashcards, topics, confidence ratings, and a review schedule." > "Build a family chore board with recurring tasks, assignees, points, and a weekly summary." ## App Data [#app-data] Apps can save structured data in your Matrix database. You do not need to manage the database yourself. When an app needs tables, Matrix records them in the app manifest and the gateway creates schema-per-app tables in the Postgres database inside your Matrix environment. Apps access that database through Matrix's bridge API, not by handling database passwords directly. This means: * app data persists across reloads; * apps can have real lists, records, filters, and charts; * recovery can restore app data from snapshots; * app permissions and access can be enforced by Matrix. ## Improving An App [#improving-an-app] You can keep iterating in plain language: * "Add a dark mode." * "Make the mobile layout cleaner." * "Add a status filter." * "Import this CSV." * "Add charts by month." * "Make it easier for my team to use." * "Change the labels to match my business." Matrix can inspect the app it created, update the files, rebuild it, and keep the app in your workspace. ## Sharing And Installing [#sharing-and-installing] Matrix apps are meant to be shareable. You can: * install apps from the app store; * fork an app and customize it; * share an app with another person; * publish your own app when it is ready; * keep your own app data separate from the original creator's data. ## For Developers [#for-developers] Developers can still inspect and edit app files directly. First-party apps live under the Matrix home as Vite + React projects with `matrix.json`, `index.html`, `src/main.tsx`, and `vite.config.ts`. For most users, Matrix handles those details automatically. # Multi-Channel Support (/docs/guide/channels) ## Headless Core, Multi-Shell [#headless-core-multi-shell] Matrix OS is headless by design. The web workspace is the primary shell, and the same AI can also be reached through connected channels such as Telegram, Discord, WhatsApp, Slack, Matrix protocol, and developer tools as those surfaces are enabled. ``` Web Workspace Telegram Bot Discord Bot Slack | | | | +--- WebSocket /ws ---+ | | | | | | | Matrix Gateway | Dispatcher -> Kernel ``` ## Channel Architecture [#channel-architecture] The `ChannelManager` in `packages/gateway/src/channels/` manages the lifecycle of all channel adapters. Each adapter implements the `ChannelAdapter` interface: * **`start()`** -- begin listening (polling, webhooks, or WebSocket connections) * **`stop()`** -- gracefully shut down * **`send()`** -- format and send a message to the channel Messages from any channel flow through the dispatcher to the kernel. The kernel's response is formatted for the originating channel via `formatForChannel()`. ## Available Channels [#available-channels] | Channel | Status | Transport | Configuration | | ----------- | -------- | ----------------- | ------------------------------------------ | | Web Desktop | Built-in | WebSocket | Automatic | | Telegram | Adapter | Long polling | `config.json` -> `channels.telegram.token` | | Discord | Adapter | Gateway WebSocket | `config.json` -> `channels.discord.token` | | Slack | Adapter | Socket Mode | `config.json` -> `channels.slack.token` | | WhatsApp | Adapter | Baileys (Web) | `config.json` -> `channels.whatsapp` | | CLI | Built-in | stdin/stdout | `bin/matrixos.ts` | ## Configuring Channels [#configuring-channels] Channel setup is handled from Matrix settings when available. Under the hood, channel configuration lives in the user's Matrix system configuration so it can be backed up and restored with the rest of the workspace. ```json { "channels": { "telegram": { "token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11", "allowFrom": [123456789] } } } ``` The `allowFrom` field restricts which user IDs can interact with the bot, providing basic access control. Channel config changes are detected by the file watcher. Add a new channel token and the adapter starts automatically -- no restart needed. ## Channel-Aware Dispatch [#channel-aware-dispatch] The dispatcher uses a `DispatchContext` that includes the originating channel. This context flows through to the kernel, so agents can tailor their responses. For example, Telegram messages are formatted with Markdown, while Discord uses embeds. The `formatForChannel()` function handles platform-specific formatting: * **Telegram**: Markdown with inline code and bold * **Discord**: Rich embeds with fields * **Slack**: Block Kit with sections and actions * **WhatsApp**: Plain text with limited formatting ## Proactive Channels [#proactive-channels] Channels aren't just for receiving messages. The **CronService** and **HeartbeatRunner** can proactively send messages through any channel: * **Cron jobs** defined in `~/matrixos/system/cron.json` trigger kernel invocations on a schedule * **Heartbeat** periodically invokes the kernel during active hours to check for tasks, health, and notifications * Proactive messages are sent back through the channel that the user most recently interacted with # CLI (/docs/guide/cli) The Matrix OS CLI is a single binary — `matrix` (also installed as `matrixos` and `mos`) — for everything you do against your Matrix OS instance from outside the browser: signing in, syncing files, opening terminal sessions, and (soon) driving the upcoming VSCode extension. ## Run Without Installing [#run-without-installing] For coding-agent tools, prefer the [Streamable HTTP MCP connection](/docs/mcp) once the hosted rollout is enabled. It uses browser OAuth without installing Matrix CLI. The [stdio MCP alternative](/docs/cli#connect-a-coding-agent-over-mcp) retains its separate CLI login. The CLI is published as `@finnaai/matrix` on npm. `npx` and `pnpm dlx` run the same CLI entrypoint as an installed `matrix` binary, and profile/auth files are stored in `~/.matrixos/` so later installs reuse the same login. ```bash # npm package runner npx --yes @finnaai/matrix login --profile cloud npx --yes @finnaai/matrix whoami # pnpm package runner pnpm dlx @finnaai/matrix login --profile cloud pnpm dlx @finnaai/matrix whoami ``` If you do not have a Matrix account yet, `login --profile cloud` keeps waiting while the browser walks you through signup, plan selection, Stripe Checkout, and provisioning your Matrix computer. When setup finishes, approve the CLI in that same browser tab and return to your terminal. The package runner requires Node.js 20 or newer. If your shell uses an older Node runtime, use the install script below to install the standalone binary instead. ## Install Permanently [#install-permanently] ```bash # Homebrew (macOS / Linux) brew install finnaai/tap/matrix # npm npm install -g @finnaai/matrix # Standalone binary, no Node.js required curl -fsSL https://get.matrix-os.com | sh # Inside the matrix-os repo (development) pnpm install pnpm exec matrix --help ``` Verify: ```bash matrix --version matrix doctor ``` ## Upgrade [#upgrade] Use the same channel you installed with, then verify the resolved binary: ```bash # Homebrew brew update brew upgrade finnaai/tap/matrix # npm npm install -g @finnaai/matrix@latest # Install script curl -fsSL https://get.matrix-os.com | sh ``` Verify: ```bash matrix --version matrix doctor which matrix ``` If `matrix --version` still prints an older version after upgrading, start a new terminal or refresh your shell command cache with `hash -r` in bash/zsh. If Homebrew says the formula is already current but you still see an old binary, run `brew reinstall finnaai/tap/matrix` and check `which matrix` for a stale npm-installed copy earlier in `PATH`. ## First run [#first-run] ```bash matrix login --profile cloud # opens a browser, completes the hosted device flow matrix whoami # confirms handle, gateway, token expiry matrix shell new main # creates your "main" session matrix shell new main --attach # creates and attaches in one step ``` `Ctrl-\ Ctrl-\` detaches from a session without killing it. Reattach any time with `mos shell attach main`. ## Profiles [#profiles] Profiles let you point the same CLI at different stacks. Two are pre-configured: | Profile | Platform URL | Gateway URL | | ------- | --------------------------- | --------------------------- | | `cloud` | `https://app.matrix-os.com` | `https://app.matrix-os.com` | | `local` | `http://localhost:9000` | `http://localhost:4000` | ```bash matrix profile ls matrix profile use local matrix profile show # One-shot matrix --profile local shell ls # Sugar for --profile local matrix --dev shell ls ``` Profiles are stored at `~/.matrixos/profiles.json`. Auth tokens are scoped per-profile under `~/.matrixos/profiles//auth.json`. `matrix login` writes auth into the active profile. `matrix login --profile local` (or `matrix login --dev`) skips the OAuth device flow and writes a long-lived dev stub — the local gateway in dev mode accepts any bearer. The success line always names the profile that was just written, so you always know where you are. ## Shell sessions [#shell-sessions] Every Matrix OS instance ships with [zellij](https://zellij.dev) pre-installed. The CLI treats zellij sessions as the source of truth — the same sessions you see in the web shell are the ones you list and attach from the terminal. ```bash matrix shell ls # list sessions matrix shell new code # create a session matrix shell new code --attach # create + attach matrix shell new code --layout dev # create with a saved layout matrix shell new agent --cmd "claude" # create with an inline command mos shell attach code # reattach to an existing session mos shell attach -c review # create if missing, then attach matrix shell rm code --force # destroy a session ``` **Detaching.** Press `Ctrl-\` twice in quick succession to leave the session running and return to your shell — the same combo whether you're in `attach`, `connect`, or just created a session with `new --attach`. To kill it instead, exit the shell normally inside the session or run `matrix shell rm `. ### Tabs [#tabs] Tabs may be anonymous (zellij assigns an index) but **named tabs are recommended** so you can address them from scripts and the VSCode extension. ```bash matrix shell tab ls --session code matrix shell tab new --session code --name editor --cwd ~/projects/site matrix shell tab go --session code --tab 1 matrix shell tab close --session code --tab 1 ``` ### Panes [#panes] ```bash matrix shell pane split --session code --direction right --cmd "claude" matrix shell pane split --session code --direction down --cmd "pnpm dev" --cwd shell matrix shell pane close --session code --pane pane-2 ``` Panes are addressed by focus in the current release: split or close operates on the focused pane. ### Layouts [#layouts] Layouts are KDL files stored in your instance at `~/.config/matrix-os/layouts/`. Save the structure of an active session and apply it later (or to a fresh session). ```bash matrix shell layout ls matrix shell layout save --name dev --kdl "$(matrix shell layout dump --session code --json | jq -r '.data.layout.kdl')" matrix shell layout apply --session code --name dev matrix shell layout show --name dev # print the KDL matrix shell layout rm --name dev ``` ## Port forwarding [#port-forwarding] Forwarding opens a listener on your local machine and connects it to a service listening on your Matrix computer. V1 supports local-to-Matrix-computer forwarding only. Reverse tunnels and public/shareable HTTPS URLs are not part of this command yet. ```bash # Local 127.0.0.1:3000 -> Matrix computer 127.0.0.1:3000 matrix port forward 3000 # Local 127.0.0.1:8080 -> Matrix computer 127.0.0.1:3000 matrix port forward 8080:127.0.0.1:3000 # Top-level alias matrix forward 3000 matrix forward 8080:127.0.0.1:3000 ``` The local listener always binds to `127.0.0.1`. The remote target must be loopback on the Matrix computer: `127.0.0.1:`, `localhost:`, or `[::1]:`. To forward a dev server, start that server on the Matrix computer first, then run the CLI command from your local terminal. ```bash matrix port forward 5173 open http://127.0.0.1:5173 ``` With `--json`, port forwarding emits NDJSON. The first event is `ready`, then connection lifecycle events follow until the command exits. ```bash matrix port forward 3000 --json {"v":1,"type":"ready","data":{"localHost":"127.0.0.1","localPort":3000,"remoteHost":"127.0.0.1","remotePort":3000,"profile":"cloud","gatewayUrl":"https://app.matrix-os.com"}} {"v":1,"type":"connection_open","data":{"localHost":"127.0.0.1","localPort":3000,"remoteHost":"127.0.0.1","remotePort":3000,"connectionId":1}} ``` ## File sync [#file-sync] The sync daemon mirrors a local folder against your instance's home directory. It runs as a background service installed by `matrix sync start`. ```bash matrix sync ~/matrixos # initialize and start matrix sync status matrix sync pause matrix sync resume ``` Scope sync to a subtree of your instance with `--folder`: ```bash matrix sync ~/work-projects --folder projects ``` ## Single-file transfer [#single-file-transfer] Use `matrix upload` and `matrix download` for one-off files that should not start the sync daemon or touch R2 sync state. ```bash matrix upload ./README.md projects/demo/README.md matrix upload --force ./config.json system/config.json matrix download projects/demo/README.md ./README.remote.md matrix download --force projects/demo/README.md ./README.remote.md ``` Regular downloads are written with standard user-readable file permissions. ## Tool authentication [#tool-authentication] For GitHub and coding agents, prefer browser/device login inside the Matrix VPS instead of moving credential files from the local machine. ```bash matrix run -it --session setup -- gh auth login matrix run -it --session setup -- claude matrix run -it --session setup -- codex ``` Agents should not scan local machines for credential files or transfer local secret files as part of setup. If the human explicitly asks to migrate an existing credential, stop and confirm the exact provider, source path, destination path, and reason before running any transfer command. ## Instance ops [#instance-ops] ```bash matrix instance info # handle, region, image, last restart matrix instance restart # graceful restart of your Matrix services matrix instance logs ``` ## Peers [#peers] ```bash matrix peers # list connected sync peers (machines) ``` ## Machine-readable output [#machine-readable-output] Every command supports `--json` for scripting and integration with the upcoming VSCode extension. Streams (terminal output, sync events, log follow) emit NDJSON, one event per line. ```bash matrix shell ls --json matrix sync status --json matrix port forward 3000 --json matrix shell tab ls main --json | jq '.[] | .name' ``` The schema is documented at [`docs/cli-json-schema.md`](https://github.com/HamedMP/matrix-os/blob/main/docs/cli-json-schema.md). Every payload includes `"v": 1` for forward compatibility. ## Global flags [#global-flags] ``` --profile Use a named profile (default: profiles.json:active) --platform Override platform URL (also $MATRIXOS_PLATFORM_URL) --gateway Override gateway URL (also $MATRIXOS_GATEWAY_URL) --token Override auth (also $MATRIXOS_TOKEN; useful in CI) --json Machine-readable output (NDJSON for streams) --no-color Disable ANSI colors -q, --quiet -v, --verbose --dev Sugar for --profile local ``` ## Diagnostics [#diagnostics] `matrix doctor` checks every layer of the stack and prints fix-it hints when something looks wrong. Run it before opening an issue. ``` $ matrix doctor Profile cloud (active) Auth ok logged in as @hamed, expires in 47m Daemon running pid 4821, sync resumed Sync ok manifest v412, 184 files, last sync 12s ago Gateway ok https://app.matrix-os.com (87ms) Zellij ok v0.44.1 on customer VPS Disk ok 23G available ``` ## Shell completions [#shell-completions] ```bash matrix completion zsh > ~/.zfunc/_matrix matrix completion bash > ~/.local/share/bash-completion/completions/matrix matrix completion fish > ~/.config/fish/completions/matrix.fish ``` ## Troubleshooting [#troubleshooting] **`Cannot connect to daemon. Is it running?`** The sync daemon is installed but not running. Start it with `matrix sync start`. If `matrix doctor` says the daemon is running but the socket is unreachable, remove the stale socket: `rm ~/.matrixos/daemon.sock` then `matrix sync start`. **`401 Unauthorized` on any command** Your token expired. Run `matrix login` again. Tokens are valid for the duration set by the platform (typically a few hours). **`mos shell attach` shows a blank screen** Usually means the zellij session exited on your instance. Check `matrix shell ls` — if the session is in the `exited` state, recreate it with `matrix shell new `. **`session "foo" not found` when connecting** The session does not exist on your instance. `mos shell attach` is intentionally strict unless you pass `-c`. Use `mos shell new foo` or `mos shell attach -c foo` to create it. **`matrix port forward` returns `invalid_forward_spec`** Check the spec shape and port ranges. Valid examples are `3000`, `8080:127.0.0.1:3000`, `8080:localhost:3000`, and `8080:[::1]:3000`. Ports must be integers from 1 through 65535. **`matrix port forward` connects but the browser shows connection refused** The target service must be running on the Matrix computer loopback interface, not on your laptop. Attach with `mos shell attach ` and verify the service is listening on `127.0.0.1:` inside the Matrix computer. **Local stack returns connection refused** `matrix --profile local` expects the gateway on `localhost:4000` and the platform on `localhost:9000`. Run `pnpm dev` in the `matrix-os` repo to boot both. # Cloud Coding (/docs/guide/cloud-coding) 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 authentication [#github-authentication] Connect GitHub inside your Matrix workspace with the GitHub CLI. SSH keys and GitHub credentials are stored under your Matrix home, so terminal panes, agents, and the browser IDE see the same authenticated identity. ```bash gh auth login 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. ## Local CLI launch [#local-cli-launch] Run the Matrix CLI from your laptop without a global install: ```bash npx --yes @finnaai/matrix login --profile cloud npx --yes @finnaai/matrix run -it -- claude ``` With pnpm: ```bash 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: ```bash npx --yes @finnaai/matrix forward 5173 open http://127.0.0.1:5173 ``` ## Installing tools [#installing-tools] Your Matrix VPS is your own Linux machine. The `matrix` user has passwordless `sudo`, so you can install operating-system packages directly: ```bash 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: ```bash 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 [#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 [#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. ```bash 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 [#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] 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 [#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] 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. # Design System (/docs/guide/design-system) Matrix OS has a warm, organic visual language built on CSS custom properties. Every app -- whether a single HTML file or a full React project -- uses the same design tokens to stay cohesive with the desktop shell. ## Philosophy [#philosophy] Matrix OS is not a cold developer tool. The palette draws from natural materials: terracotta accents, lavender backgrounds, warm blacks. Glass-morphism and subtle blur create depth without heaviness. The aesthetic is warm, approachable, and refined. ## CSS Variables [#css-variables] The shell injects `--matrix-*` variables into app iframes via the OS bridge. Apps that reference these variables automatically adapt when the user changes their theme. ### Core Colors [#core-colors] | Variable | Default | Usage | | ----------------------- | --------- | --------------------------------- | | `--matrix-bg` | `#ece5f0` | Page/canvas background (lavender) | | `--matrix-fg` | `#1c1917` | Primary text (warm black) | | `--matrix-card` | `#ffffff` | Card/panel surfaces | | `--matrix-card-fg` | `#1c1917` | Text on cards | | `--matrix-primary` | `#c2703a` | Primary accent (terracotta) | | `--matrix-primary-fg` | `#ffffff` | Text on primary elements | | `--matrix-secondary` | `#f0eaf4` | Secondary surfaces | | `--matrix-secondary-fg` | `#44403c` | Text on secondary | | `--matrix-muted` | `#f0eaf4` | Muted/subtle backgrounds | | `--matrix-muted-fg` | `#78716c` | De-emphasized text | | `--matrix-border` | `#d8d0de` | Borders and dividers | | `--matrix-input` | `#d8d0de` | Input field borders | | `--matrix-ring` | `#c2703a` | Focus ring color | | `--matrix-accent` | `#f0eaf4` | Hover/highlight backgrounds | | `--matrix-accent-fg` | `#44403c` | Text on accent | ### Semantic Colors [#semantic-colors] | Variable | Default | Usage | | ---------------------- | --------- | ---------------------- | | `--matrix-destructive` | `#ef4444` | Errors, delete actions | | `--matrix-success` | `#22c55e` | Positive states | | `--matrix-warning` | `#eab308` | Warnings | ### Typography and Radius [#typography-and-radius] | Variable | Default | Usage | | -------------------- | ------------------------------------------ | ------------------ | | `--matrix-font-sans` | `"Instrument Sans", system-ui, sans-serif` | Body text | | `--matrix-font-mono` | `"JetBrains Mono", monospace` | Code, data | | `--matrix-radius` | `0.75rem` | Base border-radius | ## Color Palette [#color-palette] The palette is warm and organic: * **Background**: Cream `#f6f4ed` -- the canvas around navigation and secondary surfaces * **Primary**: Forest `#434e3f` -- the stable brand color for primary UI and emphasis * **Accent**: Ember `#d06f25` -- the signature accent, used for active states, links, and focus rings * **Foreground**: Warm black `#1c1917` -- softer than pure black, matching the organic feel * **Cards**: White `#ffffff` -- clean surfaces with subtle shadow for depth * **Border**: Warm stone `#d6d3c8` -- barely visible structure ### Surface Hierarchy [#surface-hierarchy] Three levels of elevation: 1. **Background** (`--matrix-bg`): The lowest surface. Cream canvas. 2. **Card** (`--matrix-card`): Content panels with subtle shadow. 3. **Elevated** (`--matrix-popover`): Floating elements with backdrop blur and pronounced shadow. ## Typography [#typography] ### Scale [#scale] | Name | Size | Weight | Usage | | ----------- | ---- | ------- | ---------------------- | | `text-xs` | 12px | 400 | Timestamps, metadata | | `text-sm` | 14px | 400-500 | Labels, secondary text | | `text-base` | 16px | 400 | Body text | | `text-lg` | 18px | 500 | Card titles | | `text-xl` | 20px | 600 | Section subheadings | | `text-2xl` | 24px | 600-700 | Section headings | | `text-3xl` | 30px | 700 | Page headings | ### Font Choices [#font-choices] The shell uses Instrument Sans for UI text and JetBrains Mono for code. Apps should inherit via `var(--matrix-font-sans)` rather than redeclaring fonts. For display headings in standalone apps, distinctive alternatives are encouraged: DM Serif Display, Space Grotesk, Sora, Fraunces, or Outfit. Do not use Inter, Roboto, Arial, Helvetica, or Open Sans as deliberate font choices in apps. These produce generic, undifferentiated UI. Inherit the OS font or choose something distinctive. ## Spacing [#spacing] All spacing follows a 4px grid: | Token | Value | Usage | | ----- | ----- | --------------------------------------- | | `xs` | 4px | Icon-to-label gaps, badge padding | | `sm` | 8px | Between related elements, input padding | | `md` | 16px | Card padding, section spacing | | `lg` | 24px | Between cards, section padding | | `xl` | 32px | Page margins, major sections | | `2xl` | 48px | Hero spacing | ## Component Patterns [#component-patterns] ### Buttons [#buttons] ```css /* Primary */ background: var(--matrix-primary); color: var(--matrix-primary-fg); border-radius: var(--matrix-radius-md); padding: 8px 20px; font-weight: 600; /* Secondary */ background: transparent; border: 1px solid var(--matrix-border); color: var(--matrix-fg); /* Ghost */ background: transparent; color: var(--matrix-fg); /* hover: background: var(--matrix-accent) */ /* Destructive */ background: var(--matrix-destructive); color: #ffffff; ``` ### Cards [#cards] ```css .card { background: var(--matrix-card); border: 1px solid var(--matrix-border); border-radius: var(--matrix-radius-lg); padding: 16px; box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08); } ``` ### Glass-morphism [#glass-morphism] For floating elements: ```css background: rgba(255, 255, 255, 0.8); backdrop-filter: blur(8px); border: 1px solid var(--matrix-border); border-radius: var(--matrix-radius-xl); ``` ### Empty States [#empty-states] Every view must handle zero items: ```html

No items yet

Get started by creating your first item.

``` ## Animation [#animation] | Type | Duration | Easing | | ---------------------- | --------- | ----------- | | Micro (button, toggle) | 100ms | ease-out | | Enter (panel, tooltip) | 150ms | ease-out | | Exit (dismiss) | 100ms | ease-in | | Move (reposition) | 200-300ms | ease-in-out | Only animate `transform` and `opacity`. Always respect `prefers-reduced-motion`. ### Orchestrated Page Load [#orchestrated-page-load] Stagger child element entrances: ```css .card { animation: fadeUp 0.3s ease-out backwards; } .card:nth-child(1) { animation-delay: 0ms; } .card:nth-child(2) { animation-delay: 60ms; } .card:nth-child(3) { animation-delay: 120ms; } @keyframes fadeUp { from { opacity: 0; transform: translateY(12px); } to { opacity: 1; transform: translateY(0); } } ``` ## @matrix-os/ui Package [#matrix-osui-package] The `@matrix-os/ui` package provides themed React components for Vite apps: ```tsx import { Button, Card, CardContent, Input, Badge, Dialog } from '@matrix-os/ui'; import '@matrix-os/ui/styles.css'; ``` Components use `--matrix-*` CSS variables and accept `className` and `style` props for customization. They are lightweight (no Radix dependency) and React 19 compatible. ### Available Components [#available-components] | Component | Description | | -------------------------------------------------------------- | ----------------------------------------------- | | `Button` | Primary, secondary, ghost, destructive variants | | `Card`, `CardHeader`, `CardTitle`, `CardContent`, `CardFooter` | Card container with sections | | `Input` | Text input with label and error state | | `Dialog`, `DialogTitle`, `DialogFooter` | Modal dialog with overlay | | `Badge` | Status badge (default, success, warning, error) | | `Tooltip` | Hover tooltip with configurable position | ## AI Design Resources [#ai-design-resources] The AI uses two files when building UI: * **Knowledge file**: `~/agents/knowledge/matrix-design-system.md` -- full CSS variable reference, patterns, and anti-patterns * **Skill**: `~/.agents/skills/matrix-design-system/SKILL.md` -- Matrix theme variables, shadcn-style controls, iframe-safe layouts, icon rules Both are loaded automatically when the AI builds apps, ensuring consistent visual output. # Developer Workflow (/docs/guide/developer-workflow) AI coding has moved from autocomplete to agents that can read repositories, edit files, run tests, open pull requests, and work in the background. Matrix OS gives those agents a persistent place to work: your own cloud computer, your files, your shell sessions, your project context, and your review history. Use Matrix when you want the speed of Claude Code, Codex, Cursor, Copilot, Gemini CLI, Cline, Jules, Devin, or another agent without rebuilding your setup for every tool. Matrix is the shared development workspace. Your AI tools are interchangeable workers that can attach to it. ## Quick Agent Setup [#quick-agent-setup] Paste this into Claude, Codex, Cursor, Cline, or another coding agent: ````md # Set Up Matrix OS For My Dev Workflow Set up Matrix OS so I can use my own cloud computer for coding agents, terminal sessions, and project work. If your runtime supports file skills, install it: ```bash npx skills add HamedMP/matrix-os --skill matrix-os ``` Then show me this checklist: 1. Install or update the Matrix CLI 2. Run `matrix login --profile cloud` and wait for my Matrix instance to be ready 3. Verify with `matrix doctor` and `matrix whoami` 4. Start my preferred coding agent on Matrix with `matrix run` 5. Let me complete that tool's browser/device login inside the remote terminal 6. Explain the reconnect and recovery commands only after the main path works Then proceed step by step. Keep the happy path small: ```bash matrix login --profile cloud matrix doctor matrix whoami matrix run -it --session setup -- claude ``` Use `codex`, `gemini`, or another terminal agent instead of `claude` if I ask for it. ## Step 1: Install or update the Matrix CLI From the current project root, check whether the Matrix CLI is available: ```bash command -v matrix && matrix --version ``` If `matrix` is missing, install it: ```bash npm install -g @finnaai/matrix ``` If the user prefers another package manager, use the equivalent global install command from `skills.md`. ## Step 2: Sign in to Matrix Run: ```bash matrix login --profile cloud ``` Pause while I complete the browser login flow. If Matrix says no instance exists yet, send me to: ```text https://app.matrix-os.com ``` Wait for provisioning, then run `matrix login --profile cloud` again. ## Step 3: Configure and run agents inside Matrix Use browser/device login inside the Matrix VPS. Do not scan the local machine for credential files, and do not transfer local secret files as part of onboarding. For GitHub: ```bash matrix run -it --session setup -- gh auth login ``` For a coding agent, run one command at a time: ```bash matrix run -it --session setup -- claude ``` or: ```bash matrix run -it --session setup -- codex ``` Use the selected agent only; do not launch multiple agents unless I explicitly ask. ## Step 4: Verify or recover only if needed If setup fails, use: ```bash matrix status matrix doctor matrix instance info matrix shell ls ``` If I detach from a named setup session later, reconnect with: ```bash matrix shell attach setup ``` ## Step 5: Finish Summarize: - whether `matrix login --profile cloud` succeeded; - whether the Matrix instance is ready; - the exact command to start Claude, Codex, or my preferred agent in Matrix. ```` This pattern keeps the human in the login loop while still letting the coding agent do the install, verification, and setup work. ## Why Matrix Helps [#why-matrix-helps] Most AI coding tools are optimized around one surface: * an editor agent that edits the open project; * a terminal agent that runs commands where you start it; * a cloud task agent that clones a repository into a temporary environment; * a pull request agent that works through GitHub issues or PRs. Those surfaces are useful, but they fragment your workflow. Setup scripts, secrets, terminals, task notes, screenshots, logs, and review findings spread across machines and products. Matrix gives you a stable home for the work: * **One always-on development machine** - your Matrix instance keeps projects, terminals, files, and tools available after you close your laptop. * **Shared shell sessions** - open a zellij session once, then reconnect from the web workspace, CLI, or an agent. * **Agent choice** - run Claude Code, Codex CLI, Gemini CLI, Cline, or another terminal agent in the same environment. * **Durable context** - keep repository notes, AGENTS.md, skills, task plans, transcripts, and review results where future agents can find them. * **Human control** - agents can do the repetitive work, but you keep review, merge, deployment, and account decisions explicit. ## Common AI Coding Workflows [#common-ai-coding-workflows] ### Editor Pairing [#editor-pairing] Use this when you are actively reading code and want fast local edits. Examples include Cursor Agent, GitHub Copilot agent mode, Windsurf Cascade, Cline in VS Code or JetBrains, and similar IDE agents. These tools are best for targeted refactors, UI iteration, "explain this code", and changing files while you stay in the editor. Matrix adds value by keeping the remote shell, running services, test commands, and project state available even when the editor changes. ### Terminal Agent Sessions [#terminal-agent-sessions] Use this when the agent needs to run commands, inspect the repo, install tools, execute tests, or drive a local browser. Examples include Claude Code, Codex CLI, Gemini CLI, Cline CLI, and Devin for Terminal. Terminal agents pair naturally with Matrix because `matrix run` starts them on your Matrix instance from your local terminal. ```bash npm i -g @finnaai/matrix matrix login --profile cloud matrix run -it -- claude ``` Use the agent you prefer: ```bash matrix run -it -- codex matrix run -it -- gemini ``` ### Async Cloud Tasks [#async-cloud-tasks] Use this when the work is well-scoped and can run while you do something else. Examples include Codex cloud tasks, GitHub Copilot coding agent, Google Jules, Devin cloud sessions, and other agents that open a draft pull request for review. These are good for dependency upgrades, documentation passes, test additions, simple bug fixes, and isolated feature slices. Matrix adds value before and after the async work: * prepare a clear task brief from your project context; * keep setup commands and repository instructions in files; * compare the agent PR against your local Matrix workspace; * run follow-up checks in your persistent shell; * hand the next round to another agent if the first one stalls. ### Review And Repair Loops [#review-and-repair-loops] Use this when code exists but needs hardening. A strong loop is: 1. Ask one agent to implement the slice. 2. Run tests and pattern checks in Matrix. 3. Ask another agent or reviewer to inspect the diff. 4. Fix only actionable findings. 5. Repeat until the PR is boring. This works especially well when Matrix keeps the terminal output, review notes, and source tree in one workspace instead of scattering them across separate browser tabs. ## Recommended Matrix Setup [#recommended-matrix-setup] ### Sign in [#sign-in] Create your Matrix account in the browser, then authenticate the CLI: ```bash npm i -g @finnaai/matrix matrix login --profile cloud matrix whoami ``` ### Install your preferred agents [#install-your-preferred-agents] Install the coding agents you use on the Matrix instance, then start them with `matrix run -it -- `. Keep each agent's project instructions in repository files so the next tool gets the same context. ### Keep project context in files [#keep-project-context-in-files] Store working notes, command recipes, setup steps, and review criteria in the repository. Agents are much more useful when the expected architecture, test commands, and safety rules are written down. ### Use PRs as the boundary [#use-prs-as-the-boundary] Let agents edit, test, and propose. Keep merge authority with a human review path. Matrix is the workspace; Git remains the audit trail. ## What To Delegate [#what-to-delegate] Update docs, add tests, fix small bugs, rename APIs, improve empty states, clean up types, and explain unfamiliar code. Implement a narrow feature behind tests, refactor one subsystem, build a prototype branch, reproduce a bug, or prepare a PR summary. Product direction, schema migrations with data risk, auth design, secrets, billing, destructive production actions, and final merge decisions. ## Prompt Pattern [#prompt-pattern] Give agents the same shape of request each time: ```md Goal: Fix the bug where ... Context: - The relevant files are ... - The expected behavior is ... - The current behavior is ... Constraints: - Do not change ... - Keep data migration safe ... - Use the existing pattern in ... Verification: - Run ... - Add or update tests for ... - Summarize remaining risk. ``` For bigger work, ask Matrix to turn a rough idea into a task brief first. Then give that brief to the agent that is best for the job. ## How Matrix Fits With Popular Agents [#how-matrix-fits-with-popular-agents] | Tool | Best at | Matrix role | | ---------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Claude Code | Deep terminal work, multi-file edits, debugging, command-driven workflows | Start it with `matrix run -it -- claude` and keep repo instructions available in Matrix | | OpenAI Codex | Local and cloud coding tasks, refactors, tests, PR-sized changes | Use Matrix for setup, validation, handoff, and follow-up iteration | | Cursor | Editor-native agent work and fast multi-file changes | Keep services, tests, and terminal state running in Matrix while editing in Cursor | | GitHub Copilot | IDE agent mode and GitHub PR/issue workflows | Use Matrix to prepare issue briefs, reproduce results, and validate PRs | | Windsurf Cascade | Agentic IDE workflows with chat, code mode, terminal, and checkpoints | Use Matrix as the persistent backend workspace behind editor sessions | | Gemini CLI | Terminal agent work with Gemini from a shell | Start it with `matrix run -it -- gemini` and keep outputs with the project | | Cline | Editor or CLI agent with browser, terminal, and MCP-style tool workflows | Use Matrix for shared remote runtime, services, and long-lived project state | | Jules or Devin | Async tasks on separate managed environments | Use Matrix to write better briefs, compare results, and continue work after handoff | ## Practical Weekly Workflow [#practical-weekly-workflow] 1. Start the week in Matrix and ask for a project status summary. 2. Pick two or three small tasks that can become PRs. 3. Start the right agent with `matrix run -it -- `. 4. Let one agent implement while you use another for review or documentation. 5. Run tests and checks in Matrix before pushing. 6. Keep useful prompts, failures, and commands in the project so the next agent has better context. ## Further Reading [#further-reading] * [Claude Code docs](https://code.claude.com/docs/en) * [OpenAI Codex docs](https://platform.openai.com/docs/codex/overview) * [Cursor docs](https://docs.cursor.com/) * [GitHub Copilot coding agent docs](https://docs.github.com/en/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot) * [Windsurf Cascade docs](https://docs.windsurf.com/windsurf/cascade) * [Gemini CLI docs](https://developers.google.com/gemini-code-assist/docs/gemini-cli) * [Cline docs](https://docs.cline.bot/introduction/overview) * [Jules docs](https://jules.google/docs/) * [Devin docs](https://docs.devin.ai/) # File System (/docs/guide/file-system) ## Everything Is a File [#everything-is-a-file] The core philosophy of Matrix OS is that all state lives on the file system. Applications, configuration, agent definitions, SOUL identity, themes, and user data are all stored as files. This means you can: * **Inspect** anything by reading a file * **Back up** your entire OS by copying `~/matrixos/` * **Share** an app by sending an HTML file * **Version** everything with git (automatic snapshots on every change) * **Sync** across devices with peer-to-peer git ## Home Directory Structure [#home-directory-structure] All persistent state resides under `~/matrixos/` (configurable via `MATRIX_HOME`): ``` ~/matrixos/ +-- apps/ # Generated HTML applications | +-- expense-tracker.html | +-- notes.html | +-- .agents/ | +-- skills/ # Agent Skills directories (matrix-app-builder/SKILL.md, ...) | +-- agents/ | +-- custom/ # Agent prompt files (builder.md, researcher.md, ...) | +-- knowledge/ # Knowledge files loaded into agent context | +-- system/ | +-- soul.md # AI personality and values | +-- identity.md # AI public identity (name, avatar) | +-- user.md # Human user profile | +-- config.json # Channel tokens, heartbeat, approval policies | +-- cron.json # Scheduled tasks (interval, once, cron expressions) | +-- theme.json # Active theme (colors, background, dock config) | +-- handle.json # Federated handle registry | +-- conversations/ # Multi-session conversation history (JSON files) | +-- data/ # App-specific data (scoped per app name) | +-- expenses/items.json | +-- notes/store.json | +-- modules/ # Deployed module services (React apps on ports 3100-3999) +-- logs/ # Activity and interaction logs (JSONL daily rotation) +-- .backup/ # Git-managed snapshots ``` ## First-Boot Template [#first-boot-template] On first boot, the gateway copies the `home/` directory from the repository to `~/matrixos/` and initializes a git repository. This template includes default agents, starter skills, SOUL identity, and configuration. ## Config File [#config-file] `~/matrixos/system/config.json` is the central configuration: ```json { "channels": { "telegram": { "token": "bot-token-here", "allowFrom": [123456789] }, "discord": { "token": "discord-bot-token" } }, "heartbeat": { "enabled": true, "intervalMinutes": 30, "activeHours": { "start": 8, "end": 22 } } } ``` New configuration sections are added additively -- existing sections are never modified by the system. ## Theme System [#theme-system] The active theme is defined in `~/matrixos/system/theme.json`. The shell's `useTheme` hook reads this file via the file watcher and applies CSS custom properties. Theme changes propagate instantly. Matrix OS ships with 6 theme presets and supports custom backgrounds (patterns, solid colors, gradients, wallpapers), dock configuration (position, size, auto-hide), and full color customization. ## Git Snapshots [#git-snapshots] Every file change triggers a git commit via the `gitSnapshotHook`. This provides: * **Version history** -- roll back any file to any previous state * **Self-healing** -- the Healer agent restores broken files from git history * **Sync** -- the `sync_files` IPC tool can commit, push, and pull for cross-device sync * **Audit trail** -- every change is tracked with timestamps You never need to manually save or commit. The `gitSnapshotHook` fires after every `Write` and `Edit` operation, creating atomic git commits automatically. ## File Serving [#file-serving] The gateway serves files from `~/matrixos/` through several endpoints: | Endpoint | Purpose | | ------------------ | -------------------------------------------------------------- | | `/files/*` | Static file serving from the home directory (path-sandboxed) | | `/modules/*` | Reverse proxy to deployed module web servers (ports 3100-3999) | | `/api/theme` | Current theme JSON | | `/api/bridge/data` | Scoped read/write for app data (`~/data/{appName}/`) | Markdown previews render referenced SVG image assets inline. Local SVG paths are resolved through the same path-sandboxed `/files/*` serving route, while unsafe or broken SVG references degrade to a readable placeholder instead of interrupting the document. ## File Watcher [#file-watcher] A `chokidar`-based file watcher in `packages/gateway/src/watcher.ts` monitors `~/matrixos/` for changes. When files change, it broadcasts `file:change` events over WebSocket. The shell's `useFileWatcher` hook consumes these events to render updates in real time -- new apps appear as windows, theme changes apply instantly, and the dock updates automatically. ## PostgreSQL Database [#postgresql-database] While most state is file-based, PostgreSQL managed through Kysely handles structured durable data: | Table | Purpose | | ---------- | ---------------------------------------------------------------------------------------------------- | | `tasks` | Workflow queue and kernel process registry. Replaces `processes.json` for tracking active processes. | | `messages` | Inter-agent IPC messaging | | `memories` | RAG storage with FTS5 full-text search | PostgreSQL provides concurrent access, transactions, and recovery for structured kernel and app state. # Getting Started (/docs/guide/getting-started) Matrix OS is designed for normal people first. You should not need to install packages, run servers, or understand databases to use it. Start with your account, your tools, and the outcome you want. ## First Five Minutes [#first-five-minutes] ### Sign up [#sign-up] Create your Matrix OS account and choose a handle. Your handle identifies your workspace and becomes the name other people can recognize when you share, message, or publish. ### Open your workspace [#open-your-workspace] After signup, Matrix opens your personal workspace. This is where you chat with your AI, open apps, manage files, use Canvas, and connect services. ### Connect the tools you already use [#connect-the-tools-you-already-use] Open Integrations and connect the services you want Matrix to help with, such as Gmail, Google Calendar, Google Drive, GitHub, Slack, or Discord. ### Ask Matrix for a concrete outcome [#ask-matrix-for-a-concrete-outcome] Use plain language. Good first requests are specific and useful: * "What needs my attention today?" * "Summarize my unread important emails." * "Make a task board for planning my move." * "Build me a simple budget tracker." * "Draft a polite reply to this message." Matrix can read, draft, organize, and build with connected tools, but sensitive actions should be permissioned and visible. Treat Matrix like a capable assistant: give it goals, review important outputs, and approve actions that matter. ## Getting Started Checklist [#getting-started-checklist] Open **Getting started** from the toolbar to see your setup progress in Web Desktop, Web Canvas, or Electron Desktop. Click the same button again to close the checklist. The checklist temporarily hides when you open the app launcher, a command palette, or a modal dialog. It also yields to full-screen Settings in the web app and to lock or boot screens. If it was open, it returns after those overlays close, without moving keyboard focus away from your work. A checklist you closed stays closed when the overlay ends. Switching between Desktop and Canvas preserves whether the checklist is open for that computer session. Ordinary app windows and menus do not dismiss it. ## What To Try First [#what-to-try-first] Ask Matrix to combine calendar events, emails, reminders, and notes into a short plan with priorities. Ask for an app that fits your life: budget tracker, habit tracker, trip planner, recipe book, medication log, CRM, or study planner. Give Matrix a goal and ask it to create tasks, notes, files, timelines, and a workspace canvas. Paste messy notes, upload files, or point Matrix at connected data and ask it to summarize, classify, and turn it into next steps. Draft replies, prepare meeting notes, write follow-ups, or summarize long threads before you respond. Tell Matrix preferences, recurring routines, people, projects, and decisions so it can use them later. ## The Main Parts Of Matrix [#the-main-parts-of-matrix] ### Chat [#chat] Chat is the fastest way to ask for work. You can ask Matrix to answer questions, create apps, summarize files, use integrations, organize projects, or explain what it is doing. ### Apps [#apps] Apps are tools inside your Matrix workspace. Some come pre-installed, and Matrix can create new apps when you describe what you need. First-party apps are built as Vite + React apps and can store structured data in your Matrix database through the bridge API. ### Canvas [#canvas] Canvas is the main workspace surface. Use it to arrange apps, files, tasks, notes, terminals, projects, and review loops spatially so you can return to the same context later. ### Integrations [#integrations] Integrations connect Matrix to the services you already use. Once connected, Matrix can search, summarize, draft, schedule, post, or organize through those services. ### Files And Data [#files-and-data] Your files live in your Matrix home. Your app and workspace data lives in your Matrix Postgres database. You do not need to manage this manually; Matrix uses it so your work survives reloads, upgrades, and recovery. ## Example Requests [#example-requests] ### Personal Life [#personal-life] * "Create a weekly meal plan and grocery list for two adults." * "Make a moving checklist and track what is done." * "Build a habit tracker with streaks and notes." * "Summarize this PDF into plain English." * "Plan a weekend trip under this budget." ### Work [#work] * "Summarize what happened in Slack while I was away." * "Find the emails I need to respond to and draft replies." * "Create a lightweight CRM for these leads." * "Turn this meeting transcript into decisions, owners, and due dates." * "Make a dashboard for invoices and follow-ups." ### Creative [#creative] * "Plan a month of content ideas." * "Turn these notes into a script outline." * "Make a portfolio tracker for projects and links." * "Build a moodboard app for this campaign." ### Technical [#technical] * "Create a project canvas for this repository." * "Find failing tests and explain the cause." * "Draft GitHub issues from this plan." * "Build an internal tool for this workflow." ## Good Prompts [#good-prompts] Matrix works best when you include: * the outcome you want; * any important constraints; * where the relevant information lives; * how polished or rough the result should be; * whether Matrix should ask before taking external actions. Examples: > "Build me a personal budget tracker. I want categories, monthly totals, recurring expenses, and a simple chart. Keep it clean and mobile-friendly." > "Look at my calendar and unread email. Give me a 5-item priority list for today. Do not send anything without asking." > "Create a task board for launching my newsletter. Include writing, design, publishing, and sponsor outreach." ## Next Steps [#next-steps] # Guide (/docs/guide) ## What Is Matrix OS? [#what-is-matrix-os] Matrix OS is a personal AI operating system. It gives you a web workspace where an AI can understand your context, use connected services, create apps, organize files, remember preferences, and help you get real work done. You do not use Matrix by configuring infrastructure. You use it by asking for outcomes. Matrix is your AI workspace: chat with it, connect your tools, ask it to build what you need, and keep everything organized in one place. ## What Matrix Helps With [#what-matrix-helps-with] Plan your day, summarize information, make checklists, track habits, organize files, and turn messy thoughts into clear next actions. Work across Gmail, Calendar, Drive, GitHub, Slack, Discord, and other services without jumping between tabs. Ask Matrix to create apps for your life or business: trackers, planners, dashboards, CRMs, games, study tools, and internal tools. Install apps, fork them, customize them, share them with others, or publish your own. Use Matrix through the web workspace and, as channels come online, through messaging surfaces. Keep files, app data, memories, and workspace state in your own Matrix environment. Give Claude, Codex, Cursor, Cline, or another coding agent a persistent Matrix computer to work from. ## Example Workflows [#example-workflows] ### "Help Me Run My Day" [#help-me-run-my-day] Connect calendar and email, then ask Matrix: > "What should I focus on today? Pull from my calendar, unread email, and existing tasks." Matrix can summarize what matters, create tasks, draft replies, and build a plan. ### "Build Me A Tool" [#build-me-a-tool] Ask: > "Build a clean app to track subscriptions, renewal dates, monthly cost, and cancellation notes." Matrix creates a real app in your workspace and stores its data in your Matrix database. ### "Organize This Project" [#organize-this-project] Ask: > "Create a workspace for launching my podcast. Include episodes, guests, sponsors, publishing checklist, and files." Matrix can create apps, tasks, notes, and a Canvas layout for the project. ### "Use My Connected Services" [#use-my-connected-services] Ask: > "Find the last email from my accountant, summarize it, and draft a response. Ask before sending." Matrix uses integrations to read context and prepare work while keeping you in control. ### "Remember How I Work" [#remember-how-i-work] Tell Matrix: > "When I ask for a daily plan, keep it under five bullets and separate urgent from optional." Matrix can use preferences and context in later conversations. ## Where To Go Next [#where-to-go-next] # Integrations (/docs/guide/integrations) Matrix OS connects to external services through secure OAuth flows. You authorize once, then Matrix can help read, search, draft, organize, schedule, post, and summarize through connected services. You do not need to manage API keys or developer credentials. Connect the service, then ask Matrix for the result you want. ## Available Services [#available-services] | Service | What your agent can do | | ------------------- | ------------------------------------------------------------------------------------------------------- | | **Gmail** | Read, search, send emails. List and create labels; explicitly archive or mark individual messages read. | | **Google Calendar** | List, create, update events. | | **Google Drive** | List, read, upload, share files. | | **GitHub** | List repos, issues, PRs. Create issues. Get notifications. | | **Slack** | Send messages, list channels, search, add reactions. | | **Discord** | Send messages, list servers and channels. | | **Granola** | Search, list, and read meeting notes, folders, transcripts, and account details. | | **X** | Read profiles and recent posts, search the last seven days, and publish posts or replies with approval. | ## Connecting a Service [#connecting-a-service] There are two ways to connect: ### From Settings [#from-settings] Open **Settings > Integrations**. You'll see all available services with a **Connect** button. Click it, authorize in the popup, and the connection appears automatically. ### From Conversation [#from-conversation] Tell your agent what you need: > "Connect my Gmail" The agent will give you an authorization link. Click it, authorize, done. The agent confirms once the connection is active. You can also label connections for multiple accounts: > "Connect my work Gmail as Work Gmail" ## Using Connected Services [#using-connected-services] Once connected, just ask naturally: > "What are my unread emails?" > "Create a meeting with Alice tomorrow at 3pm" > "Post 'deploy complete' to #engineering in Slack" > "List my open GitHub issues in myorg/myrepo" Matrix is useful because it can prepare and take action, but sensitive actions should stay visible. Ask it to draft before sending, summarize before deleting, and confirm before posting when the result matters. ## Service Actions Reference [#service-actions-reference] ### Gmail [#gmail] | Action | Description | Required Params | | ---------------- | -------------------------------- | --------------------------------------- | | `list_messages` | List emails matching a query | -- | | `get_message` | Read a specific email | `messageId` | | `send_email` | Send an email | `to`, `subject`, `body` | | `search` | Search emails | `query` | | `list_labels` | List email labels/folders | -- | | `list_history` | Read a page of mailbox changes | `startHistoryId` (string) | | `create_label` | Create a Gmail label | `name` | | `modify_message` | Add/remove labels on one message | `messageId` and a nonempty label change | Optional params: `query` (Gmail search syntax like `is:unread`, `from:alice`), `maxResults`, `cc`. List/search and history calls accept `pageToken`. Pass the returned `nextPageToken` unchanged to read the next page while keeping the same filters. Gmail pages allow 1–500 results. Keep `startHistoryId` as a string: converting it to a JavaScript number can lose precision. Expired history IDs require a full resync, not an empty successful import. For `modify_message`, use `addLabelIds` and/or `removeLabelIds`. Removing `INBOX` archives one message; removing `UNREAD` marks it read. Label creation and message changes are write actions covered by native agent approval. Empty, duplicate, conflicting, and `TRASH` label changes are rejected. No batch deletion is provided. These additions require a release containing the personal-brain integration foundation. Check the connected runtime's available actions before using them. This is not a complete inbox application: historical ingestion, receipt and people extraction, durable sync cursors, and scheduled jobs require additional application and worker implementation. Connecting Gmail does not enable them. ### Google Calendar [#google-calendar] | Action | Description | Required Params | | -------------- | ------------------------ | ------------------------- | | `list_events` | List upcoming events | -- | | `create_event` | Create a new event | `summary`, `start`, `end` | | `update_event` | Update an existing event | `eventId` | Date params use ISO 8601 format: `2026-04-06T09:00:00Z`. ### Google Drive [#google-drive] | Action | Description | Required Params | | ------------- | ------------------- | ----------------- | | `list_files` | List files in Drive | -- | | `get_file` | Get file metadata | `fileId` | | `upload_file` | Upload a file | `name`, `content` | | `share_file` | Share a file | `fileId`, `email` | ### GitHub [#github] | Action | Description | Required Params | | ------------------- | ---------------------- | --------------------------- | | `list_repos` | List your repositories | -- | | `list_issues` | List issues for a repo | `repo` (e.g., `owner/name`) | | `create_issue` | Create a new issue | `repo`, `title` | | `list_prs` | List pull requests | `repo` | | `get_notifications` | Get notifications | -- | ### Slack [#slack] | Action | Description | Required Params | | --------------- | --------------------------- | ------------------------------- | | `send_message` | Send a message to a channel | `channel`, `text` | | `list_channels` | List available channels | -- | | `list_messages` | List messages in a channel | `channel` | | `search` | Search messages | `query` | | `react` | Add emoji reaction | `channel`, `timestamp`, `emoji` | ### Discord [#discord] | Action | Description | Required Params | | --------------- | -------------------------- | ---------------------- | | `send_message` | Send a message | `channelId`, `content` | | `list_servers` | List servers the bot is in | -- | | `list_channels` | List channels in a server | `serverId` | | `list_messages` | List messages in a channel | `channelId` | ### Granola [#granola] | Action | Description | Required Params | | ---------------- | --------------------------------------------------------------- | --------------- | | `search_notes` | Ask a natural-language question across meeting notes | `query` | | `list_folders` | List accessible meeting folders | -- | | `list_notes` | List meeting notes, optionally filtered by folder or time range | -- | | `get_note` | Read a meeting note | `noteId` | | `get_transcript` | Read a meeting transcript when available on your plan | `noteId` | | `get_account` | Read the connected account and active workspace | -- | Granola connects through its official MCP endpoint and browser OAuth. Matrix registers a public OAuth client automatically, so you do not need an API key or developer credentials. Matrix shows only the actions supported by your connection; some search, folder, and transcript capabilities depend on your Granola plan and workspace access. ### X [#x] | Action | Description | Required Params | | ------------------------ | -------------------------------------------------- | -------------------------------- | | `get_authenticated_user` | Read the connected X account profile | -- | | `get_user_by_username` | Read an X profile by username | `username` (without `@`) | | `list_user_posts` | List recent posts from an X user ID | `userId` | | `search_recent_posts` | Search X posts from the last seven days | `query` | | `create_post` | Publish a post or reply from the connected account | `text`; optional `replyToPostId` | X connects through managed browser OAuth and the official X API v2, so you do not need an API key or developer credentials. Usernames contain up to 15 letters, numbers, or underscores and should be passed without `@`. Keep user and post IDs as strings so they do not lose precision. `list_user_posts` accepts `maxResults` from 5–100. Recent search accepts 10–100 results per request; pass the returned `nextToken` unchanged to continue the same query. X may further limit results and publishing based on the connected account's API access. Posts and replies require native agent approval before Matrix sends them. This integration does not expose direct messages, follows, likes, reposts, or deletion. ## Reading Beyond the First Page [#reading-beyond-the-first-page] * Calendar and Drive accept `pageToken`; continue with `nextPageToken`. Drive also returns `incompleteSearch`, which must not be treated as a complete search. * GitHub repository, issue, pull-request, and notification lists accept `page` and `per_page`. Link response headers are not exposed by this increment; continue numbered pages until an empty page rather than assuming one page is all results. * Slack channel/message lists accept `cursor`; continue with `response_metadata.next_cursor`. Slack search uses `page` and `count`. * Discord server/message lists accept either `before` or `after`, plus `limit`. Keep these IDs as strings, not JavaScript numbers. * X recent search accepts `nextToken`; pass the returned token unchanged with the same query to continue beyond the first page. Service actions return one provider page. Your app or worker must retain its filters and checkpoint progress. Pipedream action/account discovery separately walks SDK pages with limits of 20 pages, 2,000 entries, 10 seconds per request, and a shared 30-second deadline. A later-page failure or exceeded bound rejects the inventory; it is not reported as a complete partial list. Account discovery does not request credentials. ## Multiple Accounts [#multiple-accounts] You can connect multiple accounts for the same service. For example, a Work Gmail and a Personal Gmail. Use labels to differentiate: > "Send from my Work Gmail: email [alice@company.com](mailto:alice@company.com) about the Q2 report" The agent uses the `label` parameter to target the right account. If no label is specified, the most recently connected account is used. ## Managing Connections [#managing-connections] ### View connections [#view-connections] > "What services are connected?" Or open **Settings > Integrations** to see all active connections with status indicators. ### Disconnect a service [#disconnect-a-service] > "Disconnect my GitHub" Or click **Disconnect** in Settings. This revokes the connection's OAuth credentials when the provider supports revocation and removes the connection from your account. ## Building Apps with Integrations [#building-apps-with-integrations] Apps you build can use connected services. When the agent creates an app that needs Gmail or Slack, the platform tracks which services each app requires: ```json { "name": "Morning Briefing", "integrations": { "required": ["gmail", "google_calendar"], "optional": ["slack"] } } ``` If a required service isn't connected, the platform tells you what's missing and how to connect it. ## How It Works [#how-it-works] ``` User -> Shell (Settings UI / Conversation) | Matrix Gateway | Platform-owned Integration Layer - OAuth token management - Action execution - Credential storage | External Service APIs (Gmail API, GitHub API, Slack API, etc.) ``` Integration provider credentials stay on the platform. Customer workspaces call the platform integration layer through scoped Matrix routes, so apps and customer VPSes do not need raw provider secrets. ## Error Handling [#error-handling] | Error | What it means | What to do | | ------------------------------- | --------------------------------------------------- | --------------------------------------------------------------- | | "Service not connected" | The service hasn't been authorized yet | Connect it first via Settings or conversation | | "Rate limited" (429) | Too many requests to the service | Wait and try again (the `retry_after` field tells you how long) | | "Timed out" (504) | The service took too long to respond | Try again or simplify the request | | "Service unavailable" (503) | The integration provider is temporarily unavailable | Try again in a few minutes | | "Missing required params" (400) | The action is missing required input | Check the action reference above | ## Common Workflows [#common-workflows] "Give me my morning briefing" -- agent reads unread emails, today's calendar, and summarizes both. "Summarize open GitHub issues and post to #standup in Slack" -- agent reads from GitHub, formats, and posts to Slack. "Email alice about the meeting and add it to my calendar" -- agent sends the email and creates the event in one conversation. "Share the Q2 report with the marketing team" -- agent finds the file in Drive and shares it with specified emails. # Mobile (/docs/guide/mobile) Matrix OS has a phone-first shell for quick daily use. On a small screen, Matrix opens to Apps instead of dropping you into the desktop workspace. ## What Opens First [#what-opens-first] On mobile, the launcher is the first usable surface. It shows your apps in a simple grid, plus shortcuts for recent work. From there you can: * open an app full screen; * return home with the Home button; * continue the last app you used; * open Terminal without managing SSH keys; * enter Canvas only when you choose it. ## Apps On Mobile [#apps-on-mobile] Apps open as full-screen views so the available space goes to the tool, not desktop window chrome. Returning home keeps the app recoverable when Matrix can restore it. If an app cannot be opened, Matrix shows a safe recovery message and lets you go back to the launcher. ## Terminal On Mobile [#terminal-on-mobile] Terminal is available from the launcher. It connects through your authenticated Matrix session, so normal users do not need SSH keys. The mobile Terminal screen includes: * visible current folder; * command input; * session resume choices; * touch controls for Escape, Tab, arrows, Control, paste, and font size; * a safe message when a previous terminal session already ended. ## Canvas On Mobile [#canvas-on-mobile] Canvas is still available, but it is not the default phone home screen. Open it from the launcher when you want the spatial workspace, whiteboard, or visual app layout. When entering Canvas on mobile, Matrix resets stale pan and zoom state so the workspace is not trapped off screen. ## Testing On A Real Phone [#testing-on-a-real-phone] For the most realistic check, install or open Matrix on the phone, sign in, then test: 1. Hard refresh or reopen Matrix and confirm Apps is first. 2. Open Notes, Terminal, Chat, Files, Whiteboard, and a game from the launcher. 3. Use Home to return after each app. 4. Reopen Matrix and confirm the Continue action points to recent work. 5. Open Terminal, run a command, detach or leave, then resume. 6. Open Canvas explicitly and return home. # Matrix recipes (/docs/guide/recipes) A **Matrix recipe** is a reusable task brief. It describes the inputs an agent needs, the work to perform, the expected result, and what you should review. [Browse Matrix recipes](/recipes) for research, weekly reports, bug fixes, campaign briefs, meeting follow-ups, and software spend reviews. ## Use a recipe today [#use-a-recipe-today] 1. Open a recipe and expand **View instructions**. 2. Choose **Copy recipe**. If your browser blocks copying, select and copy the visible instructions. 3. Open your agent in Matrix and paste the instructions. 4. Provide the requested files or source material. Connect required tools through their supported authentication flows. 5. Review the result and its sources before using it or approving an external action. These are manually started task briefs. They do not install a bot, connect an account, or create a schedule. Results depend on the agent, tools, and inputs you provide. Missing access should be reported as a blocker. One-click recipe installation in the web app and desktop app is planned. The website catalog is not a claim that the in-product recipe manager is available. ## Repeat a successful task [#repeat-a-successful-task] Start with a single run. Refine the instructions after reviewing the output, then save your preferred brief in your workspace. Scheduling is a separate setup and requires an eligible plan and runtime capability. Builder and Max support always-on work; Starter sleeps when inactive and excludes scheduled and always-running agents. ## Recipes, agents, skills, and schedules [#recipes-agents-skills-and-schedules] * A **recipe** describes a job and the result you want. * An **agent** does the work using the tools available to it. * A **skill** supplies reusable instructions for a capability. * A **schedule** determines when a recurring task runs. A recipe can reference skills and be used for recurring work, but copying its text does not grant permissions or enforce a security policy. Review the chosen agent's permissions and approve external actions deliberately. Keep credentials out of recipe text. Share reusable instructions without private source files, account tokens, or previous run results. # Social (/docs/guide/social) Matrix OS has a built-in social network powered by the Matrix protocol. Follow other users, see what they are building, share your work, and message anyone -- including their AI. ## Matrix Protocol [#matrix-protocol] Matrix OS runs a Conduit homeserver (lightweight Rust implementation of the Matrix protocol): * Each user gets two Matrix IDs: `@handle:matrix-os.com` (human) and `@handle_ai:matrix-os.com` (AI) * User-to-user messaging is E2E encrypted via Matrix rooms * AI-to-AI communication uses custom event types (`m.matrix_os.ai_request`, `m.matrix_os.ai_response`) * Federation: Matrix OS users can message anyone on the Matrix network (Element, FluffyChat, etc.) Conduit is a single Rust binary using \~50MB RAM (vs Synapse's 500MB+). It runs as a shared service on the platform, not per-user. ## Social App [#social-app] The social app is pre-installed at `~/apps/social/` with four main sections: Feed, Explore, Messages, and Profile. ### Feed [#feed] A chronological timeline of posts from people you follow: * **Text posts**: up to 500 characters * **Image posts**: photos with captions * **App shares**: embedded app preview with "Try it" button linking to the [app runner](/docs/guide/app-store) * **Activity posts**: auto-generated from your actions (app publishes, game scores, forks) Interactions: like (heart), comment (threaded), share/repost, and "Try this app" on app shares. ### Explore [#explore] Discover new content and users: * Trending posts (most liked in last 24 hours) * Trending apps (most installed in last 7 days) * Suggested users to follow * Unified search across users, posts, and apps ### Profiles [#profiles] **User profile**: avatar, name, bio, handle, followers/following counts, published apps, recent posts. Edit inline from your own profile. **AI profile**: personality summary from SOUL, skills list, capabilities, recent AI activity. Other users can visit your AI's profile to see what it can do. ### Follow System [#follow-system] * Follow users and their AIs separately * Following someone's AI shows what it builds and its public conversations * Follow suggestions based on shared interests and similar app usage | Endpoint | Method | Description | | ------------------------------- | ------ | ------------------- | | `/api/social/follow` | POST | Follow a user or AI | | `/api/social/unfollow` | DELETE | Unfollow | | `/api/social/followers/:handle` | GET | List followers | | `/api/social/following/:handle` | GET | List following | ## Activity Sharing [#activity-sharing] Control which activities auto-post to your feed via `~/system/social-config.json`: ```json { "share_app_publishes": true, "share_app_forks": true, "share_game_scores": false, "share_ai_activity": true, "share_profile_updates": true, "auto_post_frequency": "weekly_summary" } ``` All activity sharing defaults to off (opt-in). Toggle each type in the social app settings. ### Auto-Generated Posts [#auto-generated-posts] * **App publish**: "Published \[app name] -- try it!" with app preview * **App fork**: "Remixed @author's \[app name]" * **Weekly summary**: "This week I built 3 apps and played 2 hours of chess" (opt-in, posted Sundays) * **AI summary**: "My AI helped with 12 tasks this week" All auto-posts can be previewed and edited before publishing. ## Messaging [#messaging] Direct and group messaging between Matrix OS users, powered by the Matrix protocol. The Messages app (`~/apps/messages/`) provides: * **DMs**: 1-on-1 encrypted conversations * **Group chats**: multi-user Matrix rooms with member management * **AI messaging**: message someone's AI (`@alice_ai:matrix-os.com`) -- the AI responds with sandboxed context * **Federation**: message anyone on the Matrix network * **Rich messages**: text, images, files, app links * **Live features**: read receipts, typing indicators, E2E encryption indicators External messages to an AI go through the "call center" model: the AI only sees the sender's public profile, not their full account. Rate limit: 10 external AI messages per hour per sender. ### IPC Tool [#ipc-tool] Agents can send Matrix messages: ``` send_matrix_message({ to: "@alice:matrix-os.com", content: "Meeting at 3pm?" }) ``` ## External Platform Connections [#external-platform-connections] Connect external social accounts to aggregate everything in one feed: ### Supported Platforms [#supported-platforms] | Platform | Read | Cross-Post | Auth | | ----------- | ------------------- | ------------------------ | --------------------------- | | X (Twitter) | Recent tweets | 280-char formatted posts | OAuth 2.0 + PKCE | | Instagram | Recent media | Image + caption | Instagram Basic Display API | | GitHub | Commits, PRs, stars | N/A | OAuth | | Mastodon | Toots | 500-char formatted posts | OAuth via instance URL | ### Setup [#setup] Connect accounts in the social app settings. OAuth tokens are stored in `~/system/social-connections.json`. External posts appear in your feed with provider branding and a "View on \[platform]" link. Cross-posting (write once, publish everywhere) formats content per platform. ## Social API Reference [#social-api-reference] | Endpoint | Method | Description | | -------------------------------- | ------ | ---------------------------------- | | `/api/social/feed?cursor=...` | GET | Paginated feed from followed users | | `/api/social/follow` | POST | Follow a user or AI | | `/api/social/unfollow` | DELETE | Unfollow | | `/api/social/followers/:handle` | GET | Follower list | | `/api/social/following/:handle` | GET | Following list | | `/api/social/posts` | POST | Create a new post | | `/api/social/posts/:id/like` | POST | Like a post | | `/api/social/posts/:id/comments` | POST | Comment on a post | # Storage (/docs/guide/storage) Matrix OS keeps your workspace durable and recoverable without asking you to manage infrastructure. Your Matrix environment has two main kinds of state: * **Files**: apps, documents, settings, agent instructions, exports, icons, and project files. * **Database records**: app tables, canvas documents, social data, task data, and structured workspace state. Files are for things you can inspect and move around. Postgres is for structured app and workspace data that needs search, filters, relationships, and reliable updates. ## Where Your Data Lives [#where-your-data-lives] In production, each independently billed Matrix computer gets a customer VPS. A user with multiple computers has multiple isolated runtime slots, and each VPS has: * your Matrix home at `/home/matrix/home`; * your apps under `/home/matrix/home/apps`; * your system files under `/home/matrix/home/system`; * a local Postgres database endpoint at `127.0.0.1:5432`; * backup and recovery scripts that upload database snapshots and metadata to R2. The platform keeps control-plane data such as authentication, routing, provisioning status, and integration metadata. Your personal app and workspace data is stored in your Matrix environment. ## What Uses Files [#what-uses-files] Files are used for: * app source and built app assets; * settings and preferences; * icons, images, documents, and exports; * agent instructions and skills; * project files and workspace material; * recovery artifacts and snapshots. You can ask Matrix to find, summarize, organize, rename, export, or transform files for you. ## What Uses Postgres [#what-uses-postgres] Postgres is used for data that needs structure: * app records such as notes, tasks, expenses, leads, habits, and saved items; * workspace canvas documents and references; * social and collaboration state; * app registry metadata; * key-value app state migrated from older file storage. Apps do not need to handle database credentials directly. Matrix's gateway connects to the local Postgres database and exposes scoped app access through `/api/bridge/query`. ## App Data [#app-data] When Matrix builds or installs an app with structured storage, the app declares tables in `matrix.json`. The gateway creates those tables in the user's local Postgres database using a schema-per-app model. For example, a task app can declare a `tasks` table. The app then uses the Matrix bridge to create, list, update, and delete tasks. You experience this as a normal app; Matrix handles the database behind the scenes. Benefits: * app data survives reloads and upgrades; * lists and dashboards can filter, sort, and count records; * multiple apps can use reliable structured data; * recovery can restore data from Postgres snapshots; * the platform does not need to own your app data. ## Backups And Recovery [#backups-and-recovery] Customer VPSes run scheduled database backups. The backup flow uploads a timestamped Postgres snapshot before updating the `system/db/latest` pointer used for recovery. If a VPS has to be replaced, Matrix can provision a new one, restore the latest database snapshot, reload the host bundle, and bring the workspace back online. Recovered: * structured app and workspace data from the latest successful Postgres snapshot; * machine metadata needed for routing and recovery; * files and app assets that are part of the Matrix home and backup materialization flow. Not recovered: * unsaved in-memory process state; * changes made after the last successful backup; * data from external services that lives outside Matrix unless it is synced or imported. ## Privacy And Control [#privacy-and-control] Matrix is designed so user data is not casually mixed into the platform: * personal files live in the user's Matrix home; * app/workspace records live in the user's Matrix database; * platform-owned integrations keep provider credentials on the platform; * customer VPSes call platform integration routes through a per-host token; * apps use scoped APIs instead of raw platform secrets. ## What Users Need To Do [#what-users-need-to-do] Most users do not need to do anything technical. Use Matrix normally: * create apps; * connect services; * organize files; * ask Matrix to save important information; * export or delete data when needed. For power users and developers, Matrix can expose more detail through files, app manifests, and developer tooling, but that is optional. ## Related Guides [#related-guides] # Activity Monitor (/docs/guide/system-activity-monitor) # Activity Monitor [#activity-monitor] Activity Monitor is a first-party Matrix OS app for inspecting the current Matrix computer. It shows the machine identity, installed release, uptime, CPU pressure, memory, disk usage, service health, top processes, and safe cleanup suggestions from the gateway running on that computer. Cleanup actions are typed and server-issued. The shell can only submit an opaque cleanup candidate and confirmation token returned by the gateway; it cannot send arbitrary PIDs or filesystem paths. The gateway revalidates the target before any mutation and records cleanup history in the owner's Matrix home. Automatic cleanup remains opt-in. In v1, automation is limited to conservative high-confidence stale app servers, approved cache scopes, and inactive non-rollback bundles. Terminal sessions and code-server restarts stay manual-only. # Billing (/docs/developer/deployment/billing) Matrix OS hosted runtime billing is backed by Stripe Billing. Clerk remains the identity provider, but subscription checkout, coupons, tax, the customer portal, and webhooks are handled by Stripe. ## Hosted Runtime Plans [#hosted-runtime-plans] | Plan | Monthly list price | Included machines | | ------- | -----------------: | ----------------: | | Starter | $20 | 1 | | Builder | $100 | 1 | | Max | $200 | 1 | The first primary computer on a Matrix account can use Stripe's native **3-day trial** for subscriptions. With the product default, Checkout sends `trial_period_days: 3`, requires a card, and charges $0 initially. Stripe automatically attempts the selected recurring price when the trial ends unless the user cancels first. Coupons remain independent marketing discounts and never implement the trial. The offer is limited to one trial per Matrix account and excludes previous subscribers, additional computers, and subsequent subscriptions. The persisted checkout attempt records the eligibility decision and duration so an idempotent retry sends identical Stripe parameters. The `MATRIX_CARD_TRIALS_ENABLED` rollout flag controls only new offers; disabling it does not alter trials already underway. ## Entitlements [#entitlements] Stripe subscription webhooks project every subscription independently into `billing_subscriptions`. Each row carries the Clerk user id and runtime slot from signed Stripe metadata. Provisioning and routing authorize that exact `(clerk_user_id, runtime_slot)` projection rather than a user-wide slot count. `billing_entitlements` remains a derived coarse summary for legacy and account-level views; it is not the authorization source for one computer. The platform allows runtime proxying and provisioning while that computer's subscription is `trialing` or active. A first post-trial payment failure gates access immediately and schedules VPS suspension 24 hours later. Established paid renewal failures retain the three-day grace period. Successful recovery cancels a pending suspension or wakes an already stopped machine. Suspension powers the VPS off but does not delete its disk or owner data. Internal engineers can receive a production or staging override entitlement for testing plan changes without paying. Overrides are audit records with an expiry or revocation path; they must not delete, downgrade, or recreate a user's existing machines. Machine resize uses the same entitlement allowlist as provisioning. A running VPS may move only to a server type currently allowed by the effective entitlement. The resize path changes the Hetzner server type in place with disk growth disabled, so billing downgrades can move CPU/RAM down without replacing the machine or deleting owner data. ## Additional Computers [#additional-computers] Every additional computer purchases one standard Starter, Builder, or Max subscription through Stripe Checkout under the user's existing Stripe customer. Checkout and subscription metadata include `clerk_user_id`, `matrix_runtime_slot`, and the selected region. The Customer Portal manages existing subscriptions but does not purchase another computer. Do not configure an extra-runtime Price or a focused Customer Portal subscription-update flow. Storage and future Hetzner-backed add-ons remain separate product decisions. Do not hardcode Hetzner prices into Stripe plan names; keep provider cost data in the Matrix runtime catalog so Hetzner price changes can be updated without renaming public plans. ## Stripe Setup [#stripe-setup] Create recurring monthly Stripe Prices for the three plans. New first-time and additional-computer Checkout sessions use those Prices. Keep existing yearly Price IDs configured only so legacy annual subscriptions remain recognizable. Configure promotion codes in Stripe for launch discounts, time-limited percentage discounts, pay-X-get-Y campaigns, and referrals. Required platform environment: | Variable | Notes | | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `MATRIX_BILLING_PROVIDER=stripe` or `MATRIX_STRIPE_BILLING_ENABLED=true` | Enables Stripe-backed entitlement enforcement. | | `MATRIX_CARD_TRIALS_ENABLED=true` | Enables the card-required trial for eligible first primary computers. | | `MATRIX_CARD_TRIAL_DAYS=3` | Controls new trial duration; the product default is 3 days and the accepted range is 1 through 30. | | `STRIPE_SECRET_KEY` | Restricted key with checkout, portal, customer, subscription, and webhook needs. | | `STRIPE_WEBHOOK_SECRET` | Webhook signing secret for `/billing/webhooks/stripe`. | | `STRIPE_PRICE_MATRIX_STARTER_MONTHLY` / `STRIPE_PRICE_MATRIX_STARTER_ANNUAL` | Starter Price IDs. | | `STRIPE_PRICE_MATRIX_BUILDER_MONTHLY` / `STRIPE_PRICE_MATRIX_BUILDER_ANNUAL` | Builder Price IDs. | | `STRIPE_PRICE_MATRIX_MAX_MONTHLY` / `STRIPE_PRICE_MATRIX_MAX_ANNUAL` | Max Price IDs. | | `PLATFORM_PUBLIC_URL` | Used to build checkout and portal return URLs. | Production Cloud Run deployments read the Price IDs from Secret Manager. The required secret names are: | Environment variable | Secret Manager name | | ------------------------------------------------------------------------------ | ------------------------------------- | | `STRIPE_PRICE_MATRIX_STARTER_MONTHLY` | `stripe-price-matrix-starter-monthly` | | `STRIPE_PRICE_MATRIX_STARTER_ANNUAL` | `stripe-price-matrix-starter-annual` | | `STRIPE_PRICE_MATRIX_BUILDER_MONTHLY` | `stripe-price-matrix-builder-monthly` | | `STRIPE_PRICE_MATRIX_BUILDER_ANNUAL` | `stripe-price-matrix-builder-annual` | | `STRIPE_PRICE_MATRIX_MAX_MONTHLY` | `stripe-price-matrix-max-monthly` | | `STRIPE_PRICE_MATRIX_MAX_ANNUAL` | `stripe-price-matrix-max-annual` | | The signed-in pre-VPS path defaults to Builder monthly checkout. Missing price | | | secret access should block deployment rather than letting new users reach a | | | broken billing gate. | | Webhook events to subscribe: * `customer.subscription.created` * `customer.subscription.updated` * `customer.subscription.deleted` * `customer.subscription.trial_will_end` * `checkout.session.completed` * `checkout.session.expired` * `invoice.paid` * `invoice.payment_failed` Enable Stripe's trial-ending customer email as well. Stripe emits `customer.subscription.trial_will_end` three days before the deadline; Matrix uses that verified event for its reminder telemetry. Stripe Checkout uses automatic tax, promotion codes, and an idempotency key derived from the persisted checkout attempt. Eligible trial Checkout also sets `payment_method_types: ['card']` and `payment_method_collection: always`; immediate-payment sessions keep Stripe's normal dynamic-method behavior. Subscription and invoice webhooks remain the authorization source of truth; a Checkout redirect never grants access. The customer portal should remain enabled so users can update payment methods, apply supported coupons, and manage existing subscriptions through Stripe-hosted flows. ## Billing FAQ [#billing-faq] ### How long is the Matrix OS trial? [#how-long-is-the-matrix-os-trial] Eligible first primary computers receive a three-day, card-required trial. Stripe charges the selected monthly price when the trial ends unless the user cancels first. ### Can one Matrix account receive more than one trial? [#can-one-matrix-account-receive-more-than-one-trial] No. The offer is limited to one trial per Matrix account. Previous subscribers, additional computers, and later subscriptions are not eligible. ### What happens after a payment failure? [#what-happens-after-a-payment-failure] A first post-trial payment failure gates access immediately and schedules VPS suspension 24 hours later. An established paid renewal receives a three-day grace period. Suspension powers off the VPS without deleting its disk or owner data. ### Can customers manage billing without contacting support? [#can-customers-manage-billing-without-contacting-support] Yes. Stripe's customer portal lets customers update payment methods, apply supported coupons, and manage existing subscriptions. Purchasing an additional computer still uses a new Checkout session. # VPS-per-User (/docs/developer/deployment/vps-per-user) # VPS-per-User [#vps-per-user] Matrix OS production user runtime is VPS-native: one customer VPS per independently billed runtime slot. A Clerk user may own multiple runtime slots, and each customer slot has its own standard Starter, Builder, or Max subscription. The platform remains the control plane for auth, routing, provisioning, integrations, R2 host-bundle publication, upgrades, and recovery. Implementation history and production verification notes are tracked in `specs/070-vps-per-user/changelog.md`. ## Production Scope [#production-scope] Included: * Lazy provisioning through `POST /vps/provision` for an authenticated internal operator request. * One-time host registration through `POST /vps/register`. * VPS-first routing for users with a `running` `user_machines` row. * Shared `code.matrix-os.com` routing to the authenticated user's VPS-hosted code-server gateway. * Customer host restore gate, hourly Postgres backups, and R2 metadata pointers. * Manual recovery through `POST /vps/recover` or `matrixctl recover`. * In-place machine capacity changes through `POST /vps/:machineId/resize`. * Host-bundle based updates for shell, gateway, code, default apps, and runtime CLIs. * Local owner-controlled Postgres on each customer VPS at `127.0.0.1:5432`. Not included: * Automatic unreachable detection and replacement. * Sleep, warm pools, idle deletion, and geographic routing. * Data deletion from R2 during phase-1 VPS deletion. ## Cost And Quota [#cost-and-quota] The default server type is controlled by `HETZNER_SERVER_TYPE` and currently targets `cpx22`. Before adding a customer, confirm: * The Hetzner customer project has quota for one additional server. * The expected monthly cost is accepted by the operator. * The customer is explicitly opted in. * `CUSTOMER_VPS_ENABLED=true` is set only in the intended environment. Customer capacity is enforced per runtime slot: provisioning requires an active subscription for that exact slot. Operator preview VMs use the separate bounded preview policy and do not consume billable computer capacity. Do not batch-enable users until recovery and rollback have been exercised for a non-production account. ## Routing [#routing] `code.matrix-os.com` is a single public entrypoint. The platform authenticates the Clerk session or `matrix_code_session`, resolves the user to a running VPS, strips user cookies and authorization headers, then forwards to that VPS over HTTPS with platform proof headers. If no running VPS exists, the platform returns an unavailable response or uses explicitly configured legacy fallback paths for old deployments only. New production users should be provisioned as customer VPSes. ## Customer VPS Runtime [#customer-vps-runtime] Each customer VPS gets: * `/opt/matrix/env/host.env` with machine ID, Clerk user ID, handle, `DATABASE_URL`, `PLATFORM_INTERNAL_URL`, and per-host `UPGRADE_TOKEN`. * `/opt/matrix/env/r2.env` with R2 credentials scoped for backup/sync. * `/opt/matrix/app` from the host bundle: gateway package, shell build, shared packages, and bundled default apps. * `/opt/matrix/runtime` from the host bundle: Node, code-server, and bundled coding-agent CLIs. * `/opt/matrix/bin` launchers for `matrix-gateway`, `matrix-shell`, `matrix-code`, `matrix-sync-agent`, and `matrix-update`. * `/home/matrix/home` for owner files and apps. * A local Postgres database endpoint at `127.0.0.1:5432`. The current bootstrap runs Postgres as a single local `postgres:16` service container named `matrix-postgres` with a machine-local volume. Gateway/shell/code/default apps are not user runtime containers; they run through systemd host services from the host bundle. ## Gateway Identity [#gateway-identity] Gateway routes resolve owner identity through the request principal seam. A validated JWT subject wins first. If no JWT is present, a trusted single-user/container gateway may use the platform-provisioned configured identity from runtime configuration, with `MATRIX_USER_ID` as the canonical user id. This value must come from Matrix OS provisioning, not from request headers, query params, cookies, route params, or request bodies. Open local development may use the `dev-default` principal only when auth is disabled, production is false, the environment is local/development, and no configured container identity exists. Production and auth-enabled deployments refuse that fallback. ## Required Environment [#required-environment] | Variable | Required | Notes | | ----------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CUSTOMER_VPS_ENABLED` | Yes | Enables the VPS provisioning path for the intended environment. | | `CUSTOMER_VPS_IMAGE_VERSION` | Yes | Selects the host bundle key at `system-bundles//matrix-host-bundle.tar.gz`. | | `MATRIX_HOST_BUNDLE_URL` | No | Optional override for the exact bundle URL. By default cloud-init downloads through the platform tunnel at `/system-bundles//matrix-host-bundle.tar.gz`. | | `MATRIX_HOST_BUNDLE_BASE_URL` | No | Optional base URL for default bundle URL generation when not using `MATRIX_HOST_BUNDLE_URL`; defaults to `PLATFORM_PUBLIC_URL`. | | `CUSTOMER_VPS_TLS_VERIFY` | No | Defaults to `false` because phase-1 customer hosts use self-signed local TLS on :443. Set `true` only after installing publicly trusted host certificates. | | `HETZNER_API_TOKEN` | Yes | Hetzner Cloud API token for provisioning and deletion. | | `R2_BUCKET` / `S3_BUCKET` | Yes | Bucket used for metadata, DB snapshots, and host bundles. | | `MATRIX_USER_ID` | Yes for trusted single-user/container gateways | Platform-provisioned stable owner id used as the configured container identity when no validated JWT principal is present. | | `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | Yes when building a host bundle | Baked into the Next.js shell bundle. If missing, production browsers may try to load `clerk.example.com`. | | `PLATFORM_INTERNAL_URL` | Yes on customer VPSes | Base URL used by customer gateways for platform-owned integration and bundle/update APIs. | | `UPGRADE_TOKEN` | Yes on customer VPSes | Per-host bearer token used for platform internal calls. | | `DATABASE_URL` | Yes on customer VPSes | Points the gateway at the customer-local Postgres database. | ## Host Bundle Updates [#host-bundle-updates] Per-user VPSes do not run the legacy Matrix OS Docker user image. They run host services installed from: ```text system-bundles//matrix-host-bundle.tar.gz system-bundles//matrix-host-bundle.tar.gz.sha256 ``` Rebuild and publish this bundle whenever shell, gateway, bundled apps, host scripts, or runtime CLIs change. Existing VPSes need an explicit in-place refresh or recovery/reprovision until automated bundle upgrades are implemented. Before rollout, verify: * Served shell HTML and client chunks do not reference `clerk.example.com`. * Gateway health returns OK and uses the VPS Postgres database. * `/api/bridge/query` can list app schemas from the customer-local Postgres database. * Fresh browser loads do not call legacy `/api/canvas`. * Missing app icons resolve through stable fallbacks rather than a repeated Gemini 503 loop. * Canvas pan/zoom starts only from the canvas surface, not from wheel events inside a selected app window. ## App Runtime And Postgres [#app-runtime-and-postgres] First-party and polished default apps are Vite + React apps with `runtime: "vite"` and `build.output: "dist"` in `matrix.json`. The host-bundle build runs `scripts/build-default-apps.mjs`, and customer VPS startup copies the built app `dist/` assets plus manifests into `/home/matrix/home/apps`. Apps use the local Postgres database through the gateway bridge: ```ts await fetch("/api/bridge/query", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ action: "insert", app: "todo", table: "tasks", data: { text: "Ship it", done: false }, }), }); ``` The gateway registers manifest-declared `storage.tables` into schema-per-app Postgres tables. App child processes do not receive raw `DATABASE_URL`; the bridge is the intended scoped API for easy, safe access to the owner-local database. ## Backup Retention [#backup-retention] The customer host runs `matrix-db-backup.timer` hourly. The backup script must upload a timestamped snapshot before updating `system/db/latest`. R2 keys: * `system/vps-meta.json`: current machine metadata and heartbeat timestamp. * `system/db/latest`: latest successful snapshot pointer. * `system/db/snapshots/.dump`: Postgres custom-format snapshot restored directly with `pg_restore`. Retention pruning is deferred in this slice, so the hourly backup path uploads a new snapshot and updates `system/db/latest` without calling a no-op prune command. ## Manual Recovery [#manual-recovery] Use recovery when a customer VPS is failed, unrecoverable, or intentionally replaced. ```bash curl -sS -X POST "$PLATFORM_PUBLIC_URL/vps/recover" \ -H "Authorization: Bearer $PLATFORM_SECRET" \ -H "Content-Type: application/json" \ -d '{"clerkUserId":"user_test_vps"}' ``` Expected behavior: * The platform verifies `system/db/latest` unless `allowEmpty` is explicitly true. * The active machine row moves to `recovering` with a new `machineId`. * The old Hetzner server is deleted if it exists. * The replacement server boots from cloud-init and restores before gateway startup. * The VPS registers and eventually returns `running`. Use `allowEmpty` only for a new or intentionally empty user: ```bash curl -sS -X POST "$PLATFORM_PUBLIC_URL/vps/recover" \ -H "Authorization: Bearer $PLATFORM_SECRET" \ -H "Content-Type: application/json" \ -d '{"clerkUserId":"user_test_vps","allowEmpty":true}' ``` ## Restored State [#restored-state] Restored: * Postgres app data included in the latest successful snapshot. * VPS metadata needed for routing and operator checks. Not restored in this slice: * Any data that was never uploaded to R2. * In-memory process state. * A failed backup that did not update `system/db/latest`. If restore fails, `matrix-restore.service` exits non-zero and `matrix-gateway.service` remains gated by `ConditionPathExists=/opt/matrix/restore-complete`. ## Machine Resize [#machine-resize] Use resize when a running customer VPS needs more or less CPU/RAM without replacing the machine or restoring from backup. ```bash curl -sS -X POST "$PLATFORM_PUBLIC_URL/vps/$MACHINE_ID/resize" \ -H "Authorization: Bearer $PLATFORM_SECRET" \ -H "Content-Type: application/json" \ -d '{"serverType":"cpx32"}' ``` Expected behavior: * The endpoint is platform-internal only and requires the same platform bearer token as provision, status, recovery, delete, deploy, and fleet routes. * The route validates the UUID path parameter and the `serverType` body with Zod before touching the service. * The service only resizes `running`, undeleted machines that still have a Hetzner server ID. * The target server type must be allowed by the user's active billing entitlement when billing enforcement is configured. * The platform marks the machine `resizing`, powers the server off, calls Hetzner's in-place server-type action with disk upgrade disabled, powers the server back on, then marks it `running` with the accepted target type. * The platform does not create, delete, recover, or reprovision the machine. Owner data under `/home/matrix/home` and the customer-local Postgres volume stay on the same VPS. * Provider failures return a generic provisioning error to the caller while server-side logs retain provider details. Do not use recovery for ordinary capacity changes. Recovery intentionally replaces the server and restores from the latest backup; resize keeps the current machine and data volume in place. ## Rollback [#rollback] Rollback is a routing/operator decision: * Users without a `running` `user_machines` row should not be treated as successfully provisioned production users. * To stop serving a VPS user, delete or move the machine out of `running` state and verify the user sees the intended unavailable/reprovisioning path. * `DELETE /vps/:machineId` soft-deletes the platform row and deletes the Hetzner server, but does not remove R2 data. Do not request review or rollout approval while still pushing commits to the branch. # AI agent recipes: turn one successful task into a repeatable workflow URL: /blog/ai-agent-recipes-repeatable-workflows Learn how to turn a successful AI task into a reusable recipe with clear inputs, outputs, tools, review rules, and failure handling. An AI agent recipe is a reusable task brief that records what an agent needs, what it should do, what it should produce, and what a person must review. The safest way to create one is to complete the task successfully once, capture the working method, test it again, and only then consider automation. A recipe is more useful than a clever prompt because it preserves the operating contract around the prompt: sources, permissions, stopping conditions, output format, and approval boundaries. ## What belongs in an AI agent recipe? [#what-belongs-in-an-ai-agent-recipe] A reliable recipe answers seven questions: | Component | Question | | --------- | ------------------------------------------------------------------- | | Objective | What outcome should exist when the task finishes? | | Inputs | Which files, records, or systems are required? | | Method | Which steps and decision rules should the agent follow? | | Tools | Which applications or integrations may it use? | | Output | What exact artifact should it create? | | Review | Which claims or actions require human approval? | | Failure | What should happen when access, evidence, or confidence is missing? | If one of these is ambiguous, the recipe is likely to produce inconsistent results. ## Start with a completed task [#start-with-a-completed-task] Do not begin by automating an imagined workflow. Run the task with an agent while you can inspect the inputs and correct mistakes. Suppose the goal is a weekly customer-feedback report. The first run may reveal that call notes use inconsistent names, support tickets lack product-area labels, or the agent cannot distinguish a committed feature from a suggestion. Those are workflow problems, not prompt problems. After the successful run: 1. Record the sources that were actually useful. 2. Remove steps that did not affect the result. 3. Turn corrections into explicit decision rules. 4. Define the output structure. 5. Mark claims that need source links. 6. Add the human approval point. 7. Describe what the agent should do when blocked. This produces a recipe grounded in observed work rather than speculation. ## Define success as an artifact [#define-success-as-an-artifact] “Research our competitors” is not a completion condition. “Create a dated comparison brief covering five named competitors, link every factual change to a primary source, and flag uncertain claims” is. Useful output artifacts include: * a pull request with passing tests; * a meeting brief with source links; * a weekly report with missing-data flags; * a campaign brief awaiting approval; * a software-spend review with renewal dates; * a set of follow-up drafts that have not been sent. The artifact makes the work inspectable and gives the agent a place to stop. ## Separate instructions from permissions [#separate-instructions-from-permissions] A recipe can tell an agent to draft a customer follow-up. It does not grant permission to read the CRM or send email. Tool access and approval policy belong to the runtime and connected service. Keep credentials out of recipe text. Name the required connection, describe the allowed action, and specify what needs approval. For example: > Read approved customer notes, prepare a follow-up draft, cite the promises already made, and stop before selecting recipients or sending. That boundary remains understandable even when the recipe is used with a different agent. ## Test before scheduling [#test-before-scheduling] xAI recommends the same progression for Grok Bot: perform a task once, save the reliable method as a skill, and only then turn it into a routine that runs on a schedule or supported event. [Read the Grok Bot guidance](https://docs.x.ai/grok-bot/skills-routines-and-automations). A practical readiness test is two consecutive runs with: * complete required inputs; * output in the expected format; * factual claims linked to evidence; * no unapproved external action; * visible failure when a source is unavailable; * an acceptable amount of human correction. Scheduling an unreliable recipe only produces mistakes on time. ## How Matrix Recipes work today [#how-matrix-recipes-work-today] [Matrix Recipes](/recipes) are manually started task briefs. Open a recipe, copy its instructions, paste them into an agent in Matrix, provide the requested sources, and review the result. They do not install a bot, connect an account, or create a schedule. One-click installation is planned, while scheduled work is a separate setup that depends on the selected plan and runtime. The [Recipes guide](/docs/guide/recipes) documents the current boundary. That manual first-run model is useful: it encourages a team to inspect the job before expanding autonomy. ## A reusable recipe template [#a-reusable-recipe-template] Use this structure: ```text Objective: Create [specific artifact] for [audience or decision]. Required inputs: - [source] - [source] Method: 1. [step] 2. [step] 3. [verification] Output: [format, destination, and required fields] Approval boundary: Stop before [external or consequential action]. Failure behavior: If [input/access/evidence] is missing, report the blocker and do not guess. Completion test: The task is complete when [verifiable conditions]. ``` ## Frequently asked questions [#frequently-asked-questions] ### Is an AI agent recipe just a prompt? [#is-an-ai-agent-recipe-just-a-prompt] No. A prompt requests behavior. A recipe also defines inputs, tools, outputs, review boundaries, failure behavior, and completion criteria. ### Can the same recipe work with different agents? [#can-the-same-recipe-work-with-different-agents] Often, if it describes the job independently of one product. Results still depend on the agent, model, available tools, permissions, and source quality. ### When should a recipe become scheduled automation? [#when-should-a-recipe-become-scheduled-automation] After repeated supervised runs produce reliable artifacts and predictable failures. Scheduling should change when the task starts, not weaken its review controls. ### Where can I find examples? [#where-can-i-find-examples] Browse [Matrix Recipes](/recipes) for research, reports, bug fixes, campaign briefs, meeting follow-ups, and software-spend reviews. # E2B pricing for long-running AI agents URL: /blog/e2b-pricing-long-running-ai-agents Calculate E2B sandbox costs for long-running agent workloads and compare usage-priced sandboxes with retained cloud computers without forcing a false equivalence. E2B pricing is built for programmatically created sandboxes: a free Hobby plan or a $150-per-month Pro plan, plus per-second compute usage. For long-running agents, calculate the plan fee, CPU, memory, storage, concurrency, and total sandbox-hours together. Then decide whether the workload truly needs disposable sandboxes or a retained computer. This is not simply a question of which monthly number is lower. E2B and Matrix OS sell different infrastructure abstractions. E2B is designed for software that creates isolated environments through an SDK. Matrix is designed around a computer retained by a developer or team. ## How does E2B pricing work? [#how-does-e2b-pricing-work] At publication time, E2B lists: * Hobby at $0 plus usage, with sandbox sessions up to one hour; * Pro at $150 per month plus usage, with sessions up to 24 hours; * CPU, memory, and some storage billed according to the selected resources; * concurrency allowances that vary by plan. E2B's official calculator currently lists CPU at $0.000014 per vCPU-second and memory at $0.0000045 per GiB-second. Prices and limits can change, so use the [E2B pricing page](https://e2b.dev/pricing) for a purchasing calculation. ## A reproducible cost calculation [#a-reproducible-cost-calculation] Use this formula: `monthly cost = plan fee + (CPU rate + memory rate + storage rate) × total running seconds + concurrency add-ons` For example, a two-vCPU sandbox contributes $0.000028 per second in CPU charges at the current listed rate. Add the memory selected for that sandbox, then multiply the combined rate by every second every sandbox runs. Ten sandboxes running for ten hours equal 100 sandbox-hours, not ten. Build the estimate from workload evidence: | Input | What to measure | | ----------- | -------------------------------------------------------- | | Duration | Median and 95th-percentile task time | | Concurrency | Peak sandboxes running simultaneously | | Resources | vCPU and memory required by tests and builds | | Idle time | Time spent waiting for CI, approval, or external systems | | Recovery | Cost of recreating or resuming interrupted work | Do not model an agent as active only while it generates tokens. A sandbox may remain allocated while dependencies install, tests run, services stay available, or a human reviews an artifact. ## What do the session limits mean? [#what-do-the-session-limits-mean] E2B documents a maximum running duration of one hour on Hobby and 24 hours on Pro. Its SDK also documents beta pause and reconnect behavior. That makes the simplistic claim that every stopped connection destroys all useful state inaccurate. [Review the current sandbox API](https://e2b.dev/docs/sdk-reference/js-sdk/v2.10.5/sandbox). The architectural question remains: should your application manage sandbox lifecycle, or should a project retain one computer? A 24-hour ceiling may be irrelevant for a 20-minute test run and central to a workspace expected to remain available for weeks. ## When E2B is the natural fit [#when-e2b-is-the-natural-fit] Choose the sandbox model when: * an application creates isolated execution environments for many users or jobs; * each task should start from a controlled template; * strong task-level isolation matters more than continuity; * the workload is bursty enough that per-second billing is advantageous; * lifecycle control belongs in your product's code. That is a meaningful category, not a deficient version of a VPS. ## When retained compute is the natural fit [#when-retained-compute-is-the-natural-fit] A retained computer is more natural when one developer or team repeatedly returns to the same repositories, dependencies, terminals, databases, and preview services. See [current Matrix plans and resources](/#pricing) and the terms displayed at checkout. Choose the computer lifecycle and capacity required by your workload; agent-provider access can have separate costs. Matrix is not designed to replace E2B when a product needs thousands of API-created sandboxes. E2B is not designed to be a named developer computer. Compare them only after classifying the workload. ## The buying decision [#the-buying-decision] Run a one-week measurement rather than comparing headline prices: 1. Count total sandbox-hours and peak concurrency. 2. Record the resources required for representative builds. 3. Include idle waits and failed-task recovery. 4. Price the workload with each provider's current calculator. 5. Evaluate operational fit: API-managed sandboxes or a retained workspace. For a broader landscape, read [E2B alternatives for persistent AI-agent workloads](/blog/e2b-alternative) and [How to choose hosting for AI coding agents](/blog/ai-agent-hosting-guide). ## Frequently asked questions [#frequently-asked-questions] ### Is E2B Pro $150 per month all-inclusive? [#is-e2b-pro-150-per-month-all-inclusive] No. E2B currently describes Pro as $150 per month plus usage costs. Model CPU, memory, storage, duration, and concurrency using its current pricing page. ### Can an E2B sandbox run overnight? [#can-an-e2b-sandbox-run-overnight] Yes, when the task fits the active plan's duration and resource limits. Pro currently lists sessions up to 24 hours. Design explicit checkpoints for any task that could exceed its window. ### Does E2B support persistence? [#does-e2b-support-persistence] E2B documents pause, reconnect, templates, and lifecycle controls. Verify the exact guarantees needed by your workload rather than treating “sandbox” as synonymous with “all state disappears immediately.” ### Is Matrix OS cheaper than E2B? [#is-matrix-os-cheaper-than-e2b] For one retained developer computer, Matrix's fixed plan may have a lower headline price. For high-volume disposable execution, E2B's API and usage model may be the better fit. They should be compared with a representative workload, not one price. # Grok Bot skills and routines vs Matrix Recipes URL: /blog/grok-bot-skills-routines-vs-matrix-recipes Compare Grok Bot skills and routines with Matrix Recipes by reusable instructions, scheduling, permissions, portability, and current product behavior. Grok Bot and Matrix package repeatable agent work differently. Grok Bot uses skills for reusable methods and routines for scheduled or event-triggered execution. Matrix Recipes are currently portable task briefs that a user copies into an agent and starts manually. Choose based on whether you want an integrated Bot automation lifecycle or an inspectable brief inside a broader computer workspace. This is narrower than the overall [Grok Bot vs Matrix OS comparison](/blog/grok-bot-vs-matrix-os). Here, the only question is how a successful task becomes repeatable. ## How Grok Bot skills and routines work [#how-grok-bot-skills-and-routines-work] xAI defines two building blocks: * a **skill** contains reusable instructions for how to perform a task; * a **routine** tells one Bot when to run a workflow, either on a schedule or after a supported event. xAI recommends starting with a one-time task, making it reliable, saving the method as a skill, and only then automating it. Skills can be available across Bots, although the selected Bot still needs relevant connectors or login access. [Read the official documentation](https://docs.x.ai/grok-bot/skills-routines-and-automations). This creates an integrated progression from demonstration to reusable capability to recurring execution. ## How Matrix Recipes work today [#how-matrix-recipes-work-today] A [Matrix Recipe](/recipes) is a reusable task brief. It defines the requested inputs, steps, expected result, and review guidance. The user copies the instructions into an agent, supplies the required sources, and reviews the output. Current recipes do not install a bot, connect an account, or create a schedule. One-click recipe installation is planned. Scheduling is a separate runtime capability, and unattended work requires an eligible plan. These boundaries are documented in the [Matrix Recipes guide](/docs/guide/recipes). The recipe is therefore closer to a portable operating brief than an installed automation object. ## Compare the two models [#compare-the-two-models] | Question | Grok Bot | Matrix Recipes | | -------------------- | --------------------------------------------- | --------------------------------------------------------------- | | Reusable unit | Skill | Task brief | | Recurrence | Routine with schedule or supported event | Separate scheduling setup | | First run | Teach or perform a task, then save the method | Copy the brief, provide inputs, and run it | | Runtime | Named Grok Bot and its cloud computer | Agent running in the Matrix workspace | | Tool access | Bot needs the relevant connector or login | Agent needs a supported Matrix connection or authenticated tool | | Portability | Designed for Grok Bots | Instructions can be inspected and adapted | | Current catalog role | Skills, routines, and community task patterns | Manual briefs for defined jobs | The rows are not direct feature equivalents. A routine is not merely a more advanced recipe; it includes a trigger and belongs to Grok Bot's execution model. ## Where Grok Bot is stronger [#where-grok-bot-is-stronger] Grok Bot is the clearer choice when you want the reusable method and recurring trigger managed as native objects around a named Bot. Its documented skill-to-routine progression reduces the glue required to schedule a proven task. Teams should still verify feature availability, connectors, account permissions, run history, and approval behavior in their own Grok Bot account. ## Where Matrix Recipes are stronger [#where-matrix-recipes-are-stronger] Matrix Recipes are useful when transparency and adaptability matter more than one-click automation. The complete task brief is visible, can be edited before a run, and lives alongside files, terminals, applications, and agent sessions in a retained workspace. Matrix also supports several terminal-agent workflows rather than requiring the recipe to belong to one agent product. That does not guarantee identical results across agents: model behavior, tools, and permissions still vary. ## Permissions remain separate from instructions [#permissions-remain-separate-from-instructions] Neither model makes a workflow safe merely because its instructions are reusable. A dependable task should state: * which sources are authoritative; * which tools are required; * which actions are read-only; * which external changes require approval; * how missing access is reported; * where the result and run evidence are stored. In Matrix, copying a recipe grants no permissions. In Grok Bot, a skill may be available across Bots, but each Bot still needs the required access. That separation prevents a shared method from silently becoming shared authority. ## Which should you choose? [#which-should-you-choose] Choose Grok Bot skills and routines when you want repeatable work managed natively around Grok Bots, including supported scheduled or event-driven triggers. Choose Matrix Recipes when you want inspectable, manually launched briefs inside a persistent workspace where you can adapt the instructions and choose the agent and tools used for the run. If you are designing the process before choosing a platform, start with the neutral [AI agent recipe template](/blog/ai-agent-recipes-repeatable-workflows). Prove the task, measure corrections, and then decide how much of its lifecycle should be installed or scheduled. ## Frequently asked questions [#frequently-asked-questions] ### Does Grok Bot call these objects recipes? [#does-grok-bot-call-these-objects-recipes] xAI's official terminology is skills and routines. Community directories may use “recipes” or “templates” as a broader label for reusable Grok Bot jobs. ### Can a Matrix Recipe run on a schedule? [#can-a-matrix-recipe-run-on-a-schedule] Not by copying it alone. Scheduling is a separate setup and depends on an eligible Matrix plan and runtime capability. ### Are Matrix Recipes installed applications? [#are-matrix-recipes-installed-applications] No. They are currently manually launched task briefs. One-click installation is planned and should not be treated as a shipped capability. ### Which approach is better for human approval? [#which-approach-is-better-for-human-approval] Both can define human checkpoints. Evaluate whether the current product makes the proposed action, evidence, destination, and approval state visible for the specific workflow you intend to run. # From customer conversation to campaign: turning company memory into content URL: /blog/marketing-customer-conversation-to-campaign A practical workflow for turning sales calls, support conversations, product decisions, and research into sourced, reviewed marketing campaigns. Customer conversations can become better campaigns when a team preserves the source, extracts recurring problems carefully, converts the evidence into an approved brief, and generates content without losing attribution or nuance. The shortcut—feeding a transcript to a model and publishing the output—creates avoidable risk. One loud customer can look like a market trend. Sensitive details can leak. A polished paraphrase can become an unsupported product claim. ## Define the source boundary first [#define-the-source-boundary-first] Decide which material the workflow may use: * selected sales-call notes or transcripts, * approved support themes, * customer research interviews, * product documentation and release notes, * roadmap decisions approved for external use, * existing campaign performance. Do not give a content agent broad access merely because the connector exists. Use selected folders, projects, or records where possible, and exclude conversations that contain sensitive or contract-specific information. ## Separate signals from stories [#separate-signals-from-stories] The agent can classify evidence into: * repeated customer language, * jobs customers are trying to complete, * objections and unanswered questions, * moments of surprise or confusion, * proof already available, * claims that require validation. It should report the number and dates of supporting sources rather than declaring a trend. Marketing decides what deserves a campaign. ## Build a sourced campaign brief [#build-a-sourced-campaign-brief] A useful brief contains: | Section | Required evidence | | ----------- | ----------------------------------------------------------- | | Audience | Named segment and context | | Problem | Source language and frequency | | Promise | Current product capability or explicit vision | | Proof | Documentation, demonstration, or approved customer evidence | | Objections | Supporting conversations or research | | Conversion | One clear next action | | Constraints | Claims, privacy, legal, and brand limits | The brief becomes the approved contract between evidence and production. ## Generate channel variants from one approved idea [#generate-channel-variants-from-one-approved-idea] Once the brief is approved, an agent can prepare a blog outline, landing-page section, email, social post, sales enablement note, or webinar description. Each asset should preserve the same core claim while adapting format and depth. Do not ask separate agents to rediscover positioning independently. That creates drift. Reuse the brief and store corrections so the next draft starts from better context. ## Add a factual and brand review [#add-a-factual-and-brand-review] Before publishing, check: * every product claim against current documentation, * every statistic against its primary source, * every customer reference for permission, * every link and campaign parameter, * title and description against search intent, * the difference between available capability and product direction. Matrix's existing company-OS articles use this distinction deliberately. For example, [building a company OS](/blog/company-os-ai-agents-series) labels forward-looking workflows instead of presenting them as shipped facts. ## Close the loop with results [#close-the-loop-with-results] After publication, connect outcomes to the brief: * qualified visits and conversions, * questions raised by readers or sellers, * claims that performed or confused, * assets reused by the team, * corrections required after launch. The result is not “AI generated 20 posts.” It is a growing record of which customer problems, messages, and proof create useful action. The [Marketing AI Institute's research](https://www.marketingaiinstitute.com/hubfs/2025%20State%20of%20Marketing%20AI%20Report.pdf) and [Salesforce State of Marketing](https://www.salesforce.com/ap/resources/research-reports/state-of-marketing/) frame marketing's move toward integrated AI workflows and more unified data. The hard part is maintaining source quality and accountability across that integration. ## How Matrix could support the workflow [#how-matrix-could-support-the-workflow] Matrix can provide the durable working environment: files, connected tools, research sessions, drafts, and reviewable artifacts in one cloud computer. The [professional-assistant solution](/solutions/professional-ai-assistant-cloud-computer) describes the current foundation. Some end-to-end campaign functions in this article are product direction, not a statement that Matrix currently replaces a marketing automation suite. Verify available actions in the [integration guide](/docs/guide/integrations). Start with one monthly customer-language brief. If it consistently produces cited, useful campaign decisions, expand into asset production and reporting. [Read about the marketing operating system](/blog/marketing-team-ai-operating-system?preview=1) or [discuss a workflow pilot](/contact?audience=team). # The marketing ops agent: clean data, trackable campaigns, faster reporting URL: /blog/marketing-ops-agent-clean-data-reporting How a marketing operations agent can check campaign data, links, attribution, CRM hygiene, and recurring reports while preserving human review. A marketing operations agent should make campaigns easier to trust. Its first jobs are not writing slogans; they are checking data, validating links, enforcing naming conventions, finding inconsistencies, and preparing reports whose numbers can be traced to a source. This work is repetitive enough for automation and important enough to require visible exceptions. ## What should a marketing ops agent check? [#what-should-a-marketing-ops-agent-check] Before launch: * campaign and asset naming, * UTM source, medium, campaign, and content values, * destination URLs and redirects, * form routing and required fields, * CRM campaign association, * suppression and consent rules, * owner and approval status, * analytics events expected after launch. After launch: * broken links or failed forms, * spend without corresponding tracking, * leads missing campaign attribution, * duplicate contacts and inconsistent fields, * channel totals that do not reconcile, * material changes from the baseline, * missing or late reporting inputs. ## Use rules before reasoning [#use-rules-before-reasoning] Many QA checks should be deterministic. A URL either returns the expected response or it does not. A required UTM field is present or missing. A campaign identifier matches the convention or fails validation. Use the agent to explain, prioritize, and investigate anomalies—not to replace exact checks with a confident paragraph. | Check | Best mechanism | | -------------------------- | ---------------------------------------- | | Required UTM fields | Rule | | Broken destination | HTTP check | | Duplicate normalized email | Database comparison | | Sudden conversion change | Statistical threshold plus investigation | | Why performance changed | Agent hypothesis with evidence | | Budget or targeting change | Human decision | ## Produce an exception queue [#produce-an-exception-queue] A useful agent reports records that need action: * what failed, * affected campaign and owner, * evidence and time detected, * suggested correction, * whether the correction is reversible, * approval required. Do not hide ten failures inside a prose summary. Operators need a queue they can resolve. ## Make recurring reports reproducible [#make-recurring-reports-reproducible] A report should specify: 1. Source systems and extraction times. 2. Definitions for every metric. 3. Transformations and exclusions. 4. Comparison period. 5. Missing or delayed data. 6. Agent-generated interpretation separated from calculated facts. 7. Links to the supporting records. The agent can draft the narrative and highlight anomalies. A channel owner verifies conclusions before distribution. ## Protect write access [#protect-write-access] Reading campaign configuration and changing it are different privileges. Begin with read-only checks. Then allow low-risk draft actions, such as preparing a corrected tracking sheet. Only after repeated validation should the workflow update bounded fields—and even then, budget, audience, publication, deletion, and external messaging should require explicit approval. The [Matrix trust-layer blueprint](/blog/trust-layer-company-ai-agents) describes this progression from observable work to earned autonomy. ## Connect the workspace without copying every secret [#connect-the-workspace-without-copying-every-secret] Matrix's integration architecture keeps provider credentials in a platform-owned layer rather than requiring raw provider secrets inside customer apps or VPSes. Current services and actions are documented in [Matrix integrations](/docs/guide/integrations). The complete marketing-ops workflow described here is partly forward-looking. Matrix can host the workspace and agent work; teams should verify each provider action and permission before implementation. ## What should the team measure? [#what-should-the-team-measure] Track operational outcomes: * QA issues found before launch, * broken-link and form failure duration, * percentage of leads with valid attribution, * report preparation time, * number of manual corrections, * false-positive rate, * unauthorized or failed write attempts. Current marketing research emphasizes connected data, integrated workflows, and measurable outcomes. See the [Marketing AI Institute report](https://www.marketingaiinstitute.com/hubfs/2025%20State%20of%20Marketing%20AI%20Report.pdf) and [Salesforce State of Marketing](https://www.salesforce.com/ap/resources/research-reports/state-of-marketing/). Those goals depend on operational discipline more than content volume. ## Start with preflight QA [#start-with-preflight-qa] The safest first version runs when a campaign is marked ready for review. It checks links, tracking, naming, ownership, and required records, then produces a pass/fail report. Nothing publishes automatically. Once that loop is reliable, add post-launch monitoring and reporting. The marketing ops agent earns trust by making errors visible before it earns permission to correct them. [Read the Matrix workflow architecture](/blog/trigger-to-outcome-matrix-agent-workflows) or [talk to Matrix about a marketing-operations pilot](/contact?audience=team). # Your marketing team's AI operating system URL: /blog/marketing-team-ai-operating-system What an AI operating system for marketing should connect: company memory, campaign work, approvals, measurement, and reusable agent workflows. A marketing team's AI operating system should connect source material, campaign work, approvals, and measurement in one durable workspace. It should not be a collection of unrelated generation tools that produce more assets than the team can verify or learn from. The useful unit is a complete marketing loop: insight becomes a brief, the brief becomes reviewed assets, the campaign ships through approved channels, and results become memory for the next decision. ## What belongs in the operating system? [#what-belongs-in-the-operating-system] An AI marketing workspace needs five layers: * **Company context:** positioning, product facts, audience definitions, approved claims, and brand guidance. * **Market evidence:** customer conversations, research, competitor changes, and performance data. * **Campaign state:** briefs, owners, assets, deadlines, channels, and approvals. * **Agent workflows:** repeatable research, QA, drafting, repurposing, and reporting. * **Learning:** outcomes linked back to the assumptions and assets that produced them. If these layers remain disconnected, an agent may write fluent copy while repeating outdated positioning or inventing proof. ## Move from content generation to campaign execution [#move-from-content-generation-to-campaign-execution] Generation is one step. A reliable campaign workflow looks more like this: 1. Gather approved customer and product evidence. 2. Define the audience, problem, promise, and conversion event. 3. Draft a campaign brief. 4. Produce channel-specific assets from the approved brief. 5. Run brand, factual, link, and tracking QA. 6. Route high-impact claims and launches for approval. 7. Publish through authorized tools. 8. Collect performance and record what changed. Each transition should preserve the relationship between source, decision, artifact, and result. ## Give the agent bounded jobs [#give-the-agent-bounded-jobs] Strong marketing-agent jobs include: * assembling a weekly customer-language digest, * checking UTM naming and destination links, * drafting variations from one approved message, * preparing an editorial brief with citations, * reconciling campaign status, * generating a report from named data sources, * flagging claims without evidence. Keep final positioning, sensitive customer references, budget changes, and external publishing under human ownership. ## Company memory is the differentiator [#company-memory-is-the-differentiator] Marketing quality depends on context accumulated outside the marketing team: sales calls, support issues, roadmap decisions, product documentation, and leadership priorities. The workspace should bring selected evidence into the campaign without turning every connected system into an ungoverned data lake. [Building a company brain that remembers](/blog/founders-company-brain-that-remembers?preview=1) describes the underlying memory model; [Drive as working memory](/blog/onedrive-google-drive-working-memory-ai-agents) explains why source systems should remain authoritative. ## How Matrix fits [#how-matrix-fits] Matrix provides a persistent cloud computer with files, apps, agent sessions, and connected-tool paths. Its [professional-assistant solution](/solutions/professional-ai-assistant-cloud-computer) is designed for research, planning, follow-ups, reports, dashboards, and documents. The full marketing operating system described here is a product direction. Current integrations and actions should be checked against the [Matrix integration documentation](/docs/guide/integrations). Generated work should begin as a draft, and meaningful external actions should remain visible. ## Start with one campaign loop [#start-with-one-campaign-loop] Choose an upcoming launch or recurring campaign and define: * authoritative inputs, * approved positioning, * required deliverables, * QA checks, * approval owners, * publishing boundaries, * success metrics. Run the workflow for four cycles. Measure missing inputs, reviewer correction, time to approved asset, tracking errors, and reuse of validated material. Marketing AI research increasingly describes a move from isolated experiments toward integrated workflows and measurable adoption. The [Marketing AI Institute's State of Marketing AI report](https://www.marketingaiinstitute.com/hubfs/2025%20State%20of%20Marketing%20AI%20Report.pdf) and [Salesforce's State of Marketing](https://www.salesforce.com/ap/resources/research-reports/state-of-marketing/) provide useful market context. Your own operating evidence should determine which workflows earn more autonomy. ## The system should improve judgment, not only speed [#the-system-should-improve-judgment-not-only-speed] A team should be able to answer: * Which evidence supports this message? * Who approved it? * Where is the current version? * What shipped on each channel? * What did the campaign teach us? When those answers are available in one working environment, AI stops being a disconnected copy tool and begins to support the marketing operation. [Explore Matrix use cases](/use-cases) or [talk to Matrix about a marketing workflow](/contact?audience=team). # Matrix OS vs ChatGPT Projects: memory in a chat or a computer that acts? URL: /blog/matrix-os-vs-chatgpt-projects Compare Matrix OS and ChatGPT Projects for project memory, files, collaboration, tools, execution, persistence, and recurring work. **ChatGPT Projects is the better choice when you want chats, uploaded files, project instructions, memory, and ChatGPT tools organized around a long-running topic. Matrix OS is the better fit when the project needs its own persistent computer with a filesystem, terminals, running services, installed agents, and operational artifacts.** The distinction is not memory versus no memory. It is conversational project context versus a durable execution environment. *These comparisons use the same criteria and acknowledge where each alternative is stronger. Verify current plan limits and features before deciding.* ## At a glance [#at-a-glance] | Criterion | ChatGPT Projects | Matrix OS | | --------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Primary surface | ChatGPT project | Cloud desktop, files, terminals, apps, CLI | | Context | Chats, uploads, instructions, project memory | Files, workspace records, repos, sessions, transcripts | | Tools | ChatGPT tools and enabled apps | Installed Linux tools, coding agents, Matrix integrations | | Execution | Tasks supported inside ChatGPT | General processes and services on the Matrix computer | | Collaboration | Shared projects and contained project context | Shared or reattachable workspace/session patterns; validate team controls for the intended deployment | | Best fit | Research, writing, planning, and chat-centered recurring work | Work needing a persistent machine and inspectable execution | ## Where ChatGPT Projects is stronger [#where-chatgpt-projects-is-stronger] Projects gives ChatGPT users a familiar way to group conversations, upload files, add instructions, retain project memory, and share context. OpenAI positions it for repeated work such as research, planning, reporting, and content creation. [See the official ChatGPT Projects guide](https://help.openai.com/en/articles/10169521-projects-in-chatgpt). For teams already working in ChatGPT, this is a low-friction way to keep a body of conversational work coherent. Business, Enterprise, and Edu controls apply to projects according to workspace settings. Choose ChatGPT Projects when the principal artifact is a set of conversations and generated documents. ## Where Matrix OS is different [#where-matrix-os-is-different] Matrix provides a computer. Project context can include actual repositories, shell processes, previews, files, and persistent sessions. The agent can operate inside the same environment a developer or operator later inspects. This is useful when work must continue after a chat closes, when tools need installation, or when the output is a running service rather than only an answer or file. ## Compare the work itself [#compare-the-work-itself] ### Research and drafting [#research-and-drafting] ChatGPT Projects offers a polished, direct workflow for files, web research, Canvas, memory, and conversation. Matrix can support research and documents, but its advantage is not a superior chat-project organizer. ### Coding and processes [#coding-and-processes] Matrix exposes a Linux environment, Git, terminals, and installed coding agents. ChatGPT may provide coding and agent tools depending on the plan, but a Project remains a ChatGPT context container rather than a user-operated persistent machine. ### Memory [#memory] ChatGPT Project memory can reference project conversations and files under documented plan and workspace rules. Matrix retains files and workspace artifacts on the cloud computer. These are different memory models: inferred conversational context versus inspectable filesystem and application state. ### Connected actions [#connected-actions] Both can interact with external services through their respective apps or integrations. Test the exact service, action, approval, identity, and retention behavior required. ## Which should you choose? [#which-should-you-choose] Choose **ChatGPT Projects** if: * your work is primarily research, analysis, writing, or planning, * ChatGPT is already the team's main AI surface, * shared chats and files provide enough continuity, * you do not need to operate a general cloud machine. Choose **Matrix OS** if: * work needs a filesystem and long-running processes, * you want to bring multiple agent tools into one computer, * repositories, terminals, previews, and apps are core artifacts, * the environment must remain available independently of the chat surface. ## Test one recurring workflow [#test-one-recurring-workflow] Run a weekly research-to-action loop in both products. Gather sources, create a brief, update a working artifact, execute one bounded task, return after several days, and hand the context to a teammate. Compare continuity, evidence, actionability, permissions, and recovery. The right choice depends on whether your project needs better conversation memory or somewhere for the work itself to live. [Explore Matrix's professional assistant](/solutions/professional-ai-assistant-cloud-computer) or read [why agents need a computer](/blog/cloud-computer-for-agents). # Matrix OS vs Claude Projects: context window or persistent workspace? URL: /blog/matrix-os-vs-claude-projects Compare Matrix OS and Claude Projects across shared knowledge, project instructions, conversation context, tool execution, persistence, and team workflows. **Claude Projects is the better choice when you want Claude conversations to share project instructions and an uploaded knowledge base. Matrix OS is the better fit when the project needs a persistent computer with files, terminals, running processes, and a choice of agent tools—including Claude Code.** The decision is between a model-centered context workspace and an environment-centered operating workspace. *These comparisons are neutral and based on current official documentation. Verify plan limits and capabilities before purchase.* ## At a glance [#at-a-glance] | Criterion | Claude Projects | Matrix OS | | --------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------- | | Core experience | Claude chats with shared project knowledge | Persistent cloud computer for people and agents | | Context | Uploaded project knowledge and instructions | Files, repos, sessions, transcripts, apps, and workspace records | | Model | Claude | Bring Claude Code, Codex, OpenCode, Gemini CLI, and others | | Execution | Claude capabilities available in the product | General Linux processes, terminals, previews, and tools | | Collaboration | Private or organization-visible projects on supported work plans | Workspace and session sharing patterns; validate team requirements directly | | Best fit | Knowledge-intensive Claude conversations | Work requiring durable execution and environment control | ## Where Claude Projects is stronger [#where-claude-projects-is-stronger] Claude Projects organizes conversations around a shared knowledge base and project instructions. Anthropic documents private and organization-visible options for work plans, with retrieval used as project knowledge grows. [See Anthropic's Projects guide](https://support.anthropic.com/en/articles/9519177-how-can-i-create-and-manage-projects). That makes Projects a natural fit for analysis, writing, research, and recurring conversations where Claude is the chosen model and uploaded knowledge provides enough context. ## Where Matrix OS is different [#where-matrix-os-is-different] Matrix gives the agent an actual computer. A Claude Code session can operate against a repository, run tests, start a preview, write files, and remain available when the user's laptop closes. The same computer can also host other terminal agents and tools. Matrix's [cloud-coding guide](/docs/guide/cloud-coding) documents how projects, worktrees, sessions, transcripts, and previews remain in the user's Matrix home. ## Compare the boundaries [#compare-the-boundaries] ### Knowledge [#knowledge] Claude Projects makes selected knowledge immediately useful inside Claude chats. Matrix stores inspectable files and application state in a general workspace. Neither approach removes the need to decide which sources are authoritative and current. ### Execution [#execution] If the work is primarily reasoning over documents, Claude Projects is simpler. If the job requires shells, packages, background processes, or several development tools, Matrix offers the broader execution layer. ### Model commitment [#model-commitment] Claude Projects is optimized around Claude. Matrix is model- and agent-agnostic at the computer layer, although each third-party agent retains its own account, pricing, behavior, and terms. ### Sharing and governance [#sharing-and-governance] Anthropic provides documented project visibility within Claude for Work. Matrix buyers should validate current sharing, identity, audit, and administration requirements during a team pilot rather than infer enterprise parity from the workspace concept. ## Which should you choose? [#which-should-you-choose] Choose **Claude Projects** if: * Claude is the desired working surface, * uploaded knowledge and shared instructions are sufficient, * the outputs are mainly analysis and documents, * you want less environment management. Choose **Matrix OS** if: * Claude Code or another terminal agent needs a persistent machine, * the project contains running software and local tools, * several agents should operate in the same environment, * inspectable files and processes matter more than a curated chat context. Some teams can use Claude Projects for knowledge work and Matrix for execution. Test how context moves between them before adopting both. ## Run the same project for a week [#run-the-same-project-for-a-week] Give each product a recurring task that uses source documents, requires an updated artifact, and includes one executable step. Return from another device and hand the project to a teammate. Compare context quality, traceability, execution, effort, and policy fit. [Run Claude Code in a Matrix cloud workspace](/blog/claude-code-cloud) or [explore the professional assistant solution](/solutions/professional-ai-assistant-cloud-computer). # Matrix OS vs GitHub Copilot Coding Agent: PR agent or persistent computer? URL: /blog/matrix-os-vs-github-copilot-coding-agent Compare Matrix OS and GitHub Copilot Coding Agent across task entry, runtime, repository workflow, tool choice, persistence, governance, and team fit. **Matrix OS and GitHub Copilot Coding Agent solve different layers of agentic development.** GitHub Copilot is the more direct choice when work begins and ends in GitHub issues, branches, pull requests, and review. Matrix OS is the better fit when you want a persistent cloud computer where multiple coding agents, terminals, files, previews, and other tools remain available beyond one PR task. Neither is universally better. The decision depends on whether the durable object is the pull request or the development environment. *This comparison uses the same practical criteria across products. Product behavior changes quickly; verify current capabilities and pricing before choosing.* ## At a glance [#at-a-glance] | Criterion | GitHub Copilot Coding Agent | Matrix OS | | ----------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Center of gravity | GitHub task and PR workflow | Persistent cloud computer | | Best entry point | Issue, Agents UI, PR, GitHub surfaces | Browser desktop, CLI, terminal sessions | | Agent choice | Copilot plus supported partner agents and models | User-installed terminal agents such as Claude, Codex, OpenCode, and Gemini CLI | | Output | Branch, code changes, tests, pull request | Files, running processes, previews, diffs, and pull requests | | Persistence | Managed agent sessions around repository work | Durable workspace and named sessions | | Governance | Mature GitHub organization and enterprise controls | Owner-controlled workspace boundary; enterprise pilot capabilities should be validated directly | ## Where GitHub Copilot Coding Agent is stronger [#where-github-copilot-coding-agent-is-stronger] GitHub's agent workflow is native to the system where many engineering teams already manage issues, code review, CI, and merge authority. You can delegate work from GitHub, monitor sessions, iterate, and review the resulting branch or pull request. GitHub also provides centralized enterprise controls for agent availability, sessions, audit events, custom agents, models, and MCP policy. Its documentation now includes Copilot, Claude, Codex, and partner agents in the same broader management surface. [See GitHub's agent-management documentation](https://docs.github.com/en/copilot/concepts/agents/enterprise-management). Choose GitHub when repository workflow is the product you need and minimizing new infrastructure matters most. ## Where Matrix OS is different [#where-matrix-os-is-different] Matrix is a computer rather than a repository-specific agent. The workspace can retain repositories, terminals, processes, files, previews, apps, and agent sessions. A developer can start work in the browser, reattach through the Matrix CLI, or return after a laptop closes. Matrix is also agent-agnostic at the environment layer. Its [cloud-coding documentation](/docs/guide/cloud-coding) describes installing tools on the user's Linux computer and operating multiple sessions against durable project records. Choose Matrix when agents need a long-lived environment, non-PR artifacts, custom system tools, or parallel work that outlives one GitHub task. ## Compare the full workflow [#compare-the-full-workflow] ### Task initiation [#task-initiation] GitHub is excellent when the issue is the prompt. Matrix accepts terminal and workspace-driven work, which can be useful when the task begins in another system or needs exploratory shell access before a PR exists. ### Environment ownership [#environment-ownership] GitHub manages the agent's cloud execution. Matrix gives the user a private Linux workspace whose files and project records remain in the Matrix home. That flexibility also means the operator owns more environment choices. ### Review [#review] Both should lead to human review for consequential changes. GitHub makes the PR the natural review surface. Matrix exposes terminal output, files, previews, diffs, and PRs within a broader workspace. ### Operations beyond code [#operations-beyond-code] Copilot's deepest advantage is GitHub-native software work. Matrix can host other tools and apps, but broader business workflows depend on the integrations currently available and should be verified in the [Matrix docs](/docs/guide/integrations). ## Which should your team choose? [#which-should-your-team-choose] Choose **GitHub Copilot Coding Agent** if: * most delegated work starts as a GitHub issue, * PR creation and review are the desired endpoint, * GitHub-native enterprise controls are a priority, * you want GitHub to manage the execution environment. Choose **Matrix OS** if: * the agent needs a persistent general-purpose computer, * you want to bring several terminal agents into one environment, * previews, services, files, and long-running processes matter, * developers need to reconnect from browser or CLI. Some teams may use both: GitHub as the collaboration and review system, Matrix as the durable computer where additional agent and terminal work happens. ## Run a proof task [#run-a-proof-task] Give each option the same task: modify a real test repository, run checks, start a preview, pause the human client, return later, inspect evidence, request a revision, and open or update a PR. Record setup time, completion, review clarity, policy fit, and total cost. That reveals more than a feature checklist. [Explore Matrix cloud coding](/solutions/ai-coding-agents-cloud-workspace) or read [Matrix OS vs GitHub Codespaces](/blog/matrix-os-vs-github-codespaces). # Matrix OS vs Glean: enterprise search or agent workspace? URL: /blog/matrix-os-vs-glean Compare Matrix OS and Glean across enterprise search, company knowledge, permissions, agents, actions, execution environments, and workflow ownership. **Glean is the stronger choice when the primary need is permission-aware enterprise search and assistance across company knowledge. Matrix OS is the stronger fit when an agent needs a persistent computer where it can create files, run tools, maintain processes, and produce inspectable work.** Glean also offers agents and actions, so the boundary is not simply “search versus action.” The difference is where each product begins and what it treats as the durable operating environment. *These comparisons stay neutral and use current public documentation. Enterprise buyers should validate security, integrations, and deployment directly.* ## At a glance [#at-a-glance] | Criterion | Glean | Matrix OS | | -------------- | --------------------------------------------------- | --------------------------------------------------------------------------- | | Starting point | Enterprise knowledge connected across applications | Private cloud computer for agents and users | | Core strength | Search, answers, and company context | Execution environment, files, terminals, sessions, apps | | Agents | Glean Agents with governed data sources and actions | User-selected agents operating inside Matrix | | Permissions | Enterprise connector and administration model | Workspace and platform integration boundaries; validate enterprise controls | | Best fit | Finding and using distributed company knowledge | Hosting long-running agent work and artifacts | ## Where Glean is stronger [#where-glean-is-stronger] Glean is designed to search organization content across connected applications and understand company-specific context. Its documentation describes search, chat, and purpose-built agents, with administrative controls for agent access, data sources, actions, and models. [See Glean's agent documentation](https://docs.glean.com/agents) and [search overview](https://docs.glean.com/administration/search/about). For large organizations with a knowledge-discovery problem, mature permission-aware retrieval can matter more than a new execution environment. ## Where Matrix is different [#where-matrix-is-different] Matrix gives the agent a persistent Linux computer. It can maintain actual project files, repositories, terminal sessions, previews, and apps. Rather than indexing every company system first, a Matrix workflow can operate from selected sources and write reviewable artifacts into its workspace. This is useful for coding, document production, research workspaces, and operational workflows that require local tools or processes. It is not equivalent to Glean's enterprise-wide search coverage. ## Knowledge access and action create different risks [#knowledge-access-and-action-create-different-risks] A search product must preserve source permissions and cite evidence. An execution workspace must additionally control: * which credentials the agent can use, * which commands and tools it can run, * which files it can change, * which external actions require approval, * how work can be stopped or recovered. Glean and Matrix approach these boundaries from different starting points. Evaluate both retrieval and execution, not only answer quality. ## Which should you choose? [#which-should-you-choose] Choose **Glean** if: * employees struggle to find information across many enterprise systems, * permission-aware search is the primary use case, * broad organizational deployment and administration are required, * the desired actions fit Glean's supported agent environment. Choose **Matrix OS** if: * an agent needs its own computer and local toolchain, * workflows create files, code, previews, or long-running processes, * a smaller bounded workspace is preferable to enterprise-wide indexing, * you want to bring different agent tools into the same environment. Some organizations could use Glean to find trusted context and Matrix to perform bounded work. That architecture requires explicit source and permission handoffs. ## Run a decision-grade pilot [#run-a-decision-grade-pilot] Choose one workflow that requires both finding information and producing an artifact. Measure retrieval precision, source traceability, completion, permission behavior, reviewer effort, and recovery. Avoid a demo based only on asking general company questions. [Read about Matrix's trust layer](/blog/trust-layer-company-ai-agents) or [plan an enterprise AI lab](/solutions/enterprise-ai-coding-lab). # Matrix OS vs Google Colab for university AI labs: notebook or complete cloud environment? URL: /blog/matrix-os-vs-google-colab-university-ai-labs Compare Matrix OS and Google Colab for university AI labs across notebooks, GPUs, setup, persistence, full-stack development, coding agents, governance, and teaching fit. **Google Colab is the better choice for notebook-centered machine learning, data science, and teaching that benefits from fast access to managed accelerators. Matrix OS is the better fit for courses that need a complete persistent Linux environment with repositories, terminals, applications, previews, and coding agents.** The products overlap around cloud access, but they optimize for different teaching objects: the notebook versus the computer. *These comparisons use consistent criteria and state when the alternative wins. Universities should validate privacy, identity, accessibility, retention, cost, and support directly.* ## At a glance [#at-a-glance] | Criterion | Google Colab | Matrix OS | | -------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Primary object | Hosted Jupyter notebook | Hosted Linux computer and workspace | | Best subjects | ML, data science, interactive notebooks | Software engineering, agents, full-stack apps, multi-tool projects | | Compute | Managed CPU, GPU, and TPU access subject to plan and availability | Selected VPS power and region; not a specialized accelerator notebook service | | Persistence | Notebook and attached storage patterns; runtimes can terminate | Persistent files, sessions, repos, and processes on the Matrix computer | | Setup | Very low for notebook workflows | More general environment with more configuration surface | | Agents | Notebook AI features and code assistance | User-installed terminal coding agents in the workspace | ## Where Google Colab is stronger [#where-google-colab-is-stronger] Colab is a hosted Jupyter Notebook service requiring little setup and providing access to compute including GPUs and TPUs. Google explicitly positions it for machine learning, data science, and education. [See the official Colab FAQ](https://research.google.com/colaboratory/faq.html). For an instructor teaching tensors, model training, visualization, or a notebook-based assignment, Colab's focused environment can be exactly right. Students can open a notebook and begin without learning a full cloud machine. ## Where Matrix is different [#where-matrix-is-different] Matrix gives each participant a general-purpose development computer. A course can use Git repositories, multiple terminals, package managers, background services, browser previews, and coding-agent CLIs in the same environment. This is useful for agent-native software engineering, full-stack applications, systems work, and projects that do not fit a sequence of notebook cells. [Matrix's university solution](/solutions/university-ai-development-lab) describes the intended lab model. ## Persistence changes course design [#persistence-changes-course-design] Colab says free resources are not guaranteed or unlimited and that usage limits fluctuate. This is reasonable for a broadly accessible notebook service, but instructors should design around runtime behavior and plan constraints. Matrix is designed around a persistent computer, but universities still need explicit retention, reset, backup, and teardown policies. Persistence should not mean indefinite storage without governance. ## Which should you choose? [#which-should-you-choose] Choose **Google Colab** if: * the notebook is the natural assignment artifact, * managed accelerator access matters, * minimal setup is more important than a full environment, * the course can operate within Colab's current runtime and policy constraints. Choose **Matrix OS** if: * students need Git, shells, services, and web previews, * coding agents are part of the curriculum, * projects must persist as complete environments, * the course covers software systems rather than only notebooks. Some programs will use both: Colab for focused notebook exercises and Matrix for durable projects. Avoid forcing one environment onto every learning objective. ## Run a teaching pilot [#run-a-teaching-pilot] Give a small cohort the same representative assignment. Measure time to first result, support requests, environment failures, accessibility, compute availability, student understanding, and quality of submitted evidence. IREX reports that governed university AI pilots and systematic impact measurement remain limited in its readiness sample. [Read the IREX findings](https://www.irex.org/universityaireadiness). A comparison should therefore evaluate the operating model, not only the feature list. [Read “No more laptop roulette”](/blog/university-ai-courses-no-laptop-roulette?preview=1) or [plan a university pilot](/contact?audience=university). # Matrix OS vs HubSpot AI: CRM copilot or agent-native sales system? URL: /blog/matrix-os-vs-hubspot-ai Compare Matrix OS and HubSpot Breeze across CRM context, sales and marketing agents, connected tools, deal workspaces, execution, governance, and team fit. **HubSpot AI is the stronger choice when customer data, pipeline, campaigns, service, and AI work should remain inside an established CRM platform. Matrix OS is the stronger fit when a team wants a flexible agent workspace that can operate across files, tools, terminals, and selected systems without making the CRM the entire working environment.** Matrix does not currently replace HubSpot's mature CRM, marketing, sales, or service products. The comparison is between CRM-native intelligence and a broader agent-computer model. *These comparisons use consistent criteria and identify when the alternative wins. Confirm current HubSpot editions, credits, and Matrix actions directly.* ## At a glance [#at-a-glance] | Criterion | HubSpot Breeze | Matrix OS | | ------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------- | | System center | HubSpot customer platform and Smart CRM | Persistent cloud computer and workspace | | Context | CRM records, customer activity, content, connected HubSpot data | Selected files, apps, repositories, and connected tools | | Agents | Breeze assistants and agents within HubSpot workflows | User-selected agents and Matrix-native workflows | | GTM suite | Mature marketing, sales, service, and operations products | Product blueprints for deal and company workflows; not a full GTM suite | | Best fit | Teams committed to HubSpot as customer system | Cross-tool work needing a general execution environment | ## Where HubSpot is stronger [#where-hubspot-is-stronger] HubSpot already owns the structured customer record and the workflows around it. Breeze can summarize CRM records, create content, answer questions, and support agents for customer conversations and specialized GTM work. [See HubSpot's Breeze overview](https://knowledge.hubspot.com/ai/understand-breeze). Its Customer Agent is designed to answer from approved content, cite sources, work across supported customer channels, and hand complex cases to people. [See the HubSpot product page](https://www.hubspot.com/products/artificial-intelligence/ai-customer-service-agent). Choose HubSpot when the CRM is the natural source of truth and the desired workflow fits its platform. ## Where Matrix is different [#where-matrix-is-different] Matrix can provide a working environment around a deal or company process: files, drafts, research, terminal tools, agent sessions, and selected integrations. The CRM can remain authoritative while Matrix holds working artifacts that do not fit naturally into CRM fields. The [agent-native CRM](/blog/building-agent-native-crm-matrix) and [deal-workspace](/blog/agent-native-deal-workspace-matrix) articles are product blueprints, not claims that Matrix currently offers HubSpot-equivalent CRM functionality. ## CRM record versus deal workspace [#crm-record-versus-deal-workspace] A CRM excels at standardized lifecycle data: contacts, companies, activities, owners, stages, and reporting. A deal workspace can be better for messy active work: research, proposals, files, decisions, technical investigations, and cross-functional handoffs. Most teams need both functions. The architectural question is whether to keep all work inside the CRM, extend it with connected tools, or use a separate execution workspace around selected records. ## Which should you choose? [#which-should-you-choose] Choose **HubSpot AI** if: * HubSpot is already the customer system of record, * sales, marketing, and service workflows should be administered together, * CRM-native reporting and governance matter, * Breeze's supported agents cover the jobs. Choose **Matrix OS** if: * work crosses code, files, documents, and tools beyond CRM, * agents need a persistent computer, * the team wants to choose different agent runtimes, * a bounded pilot should remain separate from the production CRM. Use both if HubSpot remains authoritative and Matrix receives only the context required for a defined workflow. Write back approved results, preserve record IDs, and avoid shadow CRM state. ## Test one sales loop [#test-one-sales-loop] Choose account preparation and follow-up. Compare data access, source citations, draft quality, approval flow, write-back reliability, visibility, and cost. Include a duplicate contact and contradictory meeting note to test how each product handles bad data. [Read the agentic sales workflow](/blog/sales-agentic-workflow-first-touch-to-close?preview=1) or [review Matrix integrations](/docs/guide/integrations). # Matrix OS vs Lovable, Bolt, and v0: prototype factory or durable system? URL: /blog/matrix-os-vs-lovable-bolt-v0 Compare Matrix OS with Lovable, Bolt, and v0 across prompt-to-app speed, visual iteration, code ownership, environment control, deployment, and long-running work. **Lovable, Bolt, and v0 are stronger choices when the main job is turning a prompt into a visual web application quickly. Matrix OS is a stronger fit when the main job is maintaining a durable development computer where agents, repositories, terminals, previews, and operational tools continue working together.** This is not one three-way feature ranking. The app builders have different capabilities. The useful comparison is their shared prompt-to-product center of gravity versus Matrix's environment-first model. *This comparison uses consistent criteria and explains when the alternative is better. Confirm current product behavior and pricing directly.* ## Category map [#category-map] | Product | Best starting point | Durable object | | --------- | ------------------------------------------------- | ---------------------------------------------------------- | | Lovable | Describe and visually iterate on a full-stack app | Lovable project, optionally synced to GitHub | | Bolt | Build or import a web project conversationally | Bolt project and connected repository | | v0 | Generate and iterate on a web interface or app | v0 chat/project and Vercel deployment | | Matrix OS | Open a persistent computer and choose your tools | Files, repos, sessions, services, and apps on the computer | ## Where the app builders win [#where-the-app-builders-win] They compress the distance between an idea and something visible. Lovable provides conversational building, visual editing, backend paths, preview, publishing, and GitHub synchronization. Its docs explain that a connected repository becomes the source of truth and can be used with normal Git workflows. [See Lovable's GitHub documentation](https://docs.lovable.dev/integrations/github). Bolt supports creating and importing GitHub projects, including organization-level repository access. [See Bolt's GitHub documentation](https://support.bolt.new/integrations/git). v0 generates an application from a prompt and integrates publishing with Vercel. Its deployment documentation covers production URLs, previews, environment variables, protection, and deployment policy. [See v0 deployments](https://v0.dev/docs/deployments). Choose these products when visual product creation is the bottleneck. ## Where Matrix is different [#where-matrix-is-different] Matrix does not begin with a specialized web-app generator. It provides the Linux computer where a developer can install tools, clone repositories, run Claude or Codex, keep multiple terminal sessions alive, and operate previews and tests. That makes it suitable for existing systems, mixed toolchains, backend services, scripts, research, and agent workflows that do not fit one app-builder canvas. It also means Matrix does not provide the same opinionated prompt-to-polished-interface shortcut. ## Compare the lifecycle, not the first prompt [#compare-the-lifecycle-not-the-first-prompt] ### Prototype speed [#prototype-speed] Lovable, Bolt, and v0 should usually win for a greenfield visual prototype. ### Existing codebase [#existing-codebase] Test repository import, branch handling, bidirectional sync, organization permissions, and behavior when developers edit code elsewhere. Do not assume all GitHub connections work identically. ### Environment control [#environment-control] Matrix exposes a general-purpose Linux workspace. App builders abstract more of the environment to make creation faster. ### Deployment [#deployment] The builders offer integrated publishing paths. Matrix supports persistent previews and services, while production deployment remains part of the user's chosen stack. ### Long-running work [#long-running-work] Matrix is designed around persistent sessions and files. App builders retain projects, but their primary workflow is iterative product generation rather than hosting arbitrary agent and terminal work. ### Team governance [#team-governance] All four products evolve quickly. Enterprise buyers should test identity, repository scope, auditability, data handling, deployment policy, and recovery directly rather than relying on category assumptions. ## Which should you choose? [#which-should-you-choose] Choose **Lovable, Bolt, or v0** if: * you need a prototype or web app quickly, * visual iteration is central, * integrated preview and publishing reduce meaningful friction, * the supported stack fits the product. Choose **Matrix OS** if: * you need a general computer rather than a specialized builder, * existing repositories and terminal tools define the workflow, * multiple coding agents or services must run together, * the workspace must support code and non-code operational work. Many teams can use both: an app builder for rapid creation, then GitHub and a durable environment for deeper engineering and operations. ## A fair evaluation task [#a-fair-evaluation-task] Build the same small internal application. Then add authentication, change the data model, run tests, fix a regression, hand the repository to another developer, and operate it for two weeks. Measure the whole lifecycle—not only time to the first screenshot. [Explore Matrix cloud coding](/solutions/ai-coding-agents-cloud-workspace) or read [how to choose hosting for AI coding agents](/blog/ai-agent-hosting-guide). # Matrix OS vs n8n: automation graph or agent runtime? URL: /blog/matrix-os-vs-n8n Compare Matrix OS and n8n across deterministic workflows, visual orchestration, AI agents, integrations, execution environments, state, approvals, and operational fit. **n8n is the better choice when you want to design, inspect, and operate trigger-and-node workflows across APIs. Matrix OS is the better fit when an agent needs a persistent general-purpose computer with files, terminals, applications, and open-ended tools.** Both can participate in agentic workflows. The distinction is a visual automation graph versus an agent operating environment. *These comparisons apply the same criteria and explain when the alternative wins. Confirm current nodes, licenses, hosting, and Matrix integrations before choosing.* ## At a glance [#at-a-glance] | Criterion | n8n | Matrix OS | | ------------- | --------------------------------------- | ----------------------------------------------------------- | | Core object | Workflow graph with triggers and nodes | Cloud computer with files, apps, and sessions | | Best work | Repeatable API and data automation | Open-ended tasks needing local tools and durable state | | Observability | Workflow executions and node-level data | Terminal output, files, session records, and activity | | Integrations | Large node and credential ecosystem | Smaller documented integration set plus general Linux tools | | AI | AI and agent nodes inside workflows | Bring agent CLIs and Matrix-native agent workflows | | Hosting | n8n Cloud or self-hosted | Matrix Cloud or preview self-host path | ## Where n8n is stronger [#where-n8n-is-stronger] n8n makes process topology explicit. Operators can see triggers, branches, transformations, retries, API calls, and outputs. That is valuable for deterministic or semi-deterministic business automation where each step should be inspectable. n8n also offers a broad integration ecosystem and can be self-hosted. Choose it when the job is connecting systems through a repeatable graph and an API-oriented workflow is the natural representation. [See n8n's official AI workflow documentation](https://docs.n8n.io/advanced-ai/). ## Where Matrix is different [#where-matrix-is-different] Matrix begins with a computer. An agent can inspect a repository, run a script, use a terminal application, create local artifacts, and maintain a service or preview. The path does not have to be fully modeled as nodes before work begins. This flexibility suits exploratory and tool-rich tasks. It can also make behavior less predictable, which increases the importance of permissions, review, and logs. ## Deterministic steps and agent judgment belong together [#deterministic-steps-and-agent-judgment-belong-together] The strongest architecture may combine them: * n8n receives a trigger and performs exact data movement, * a bounded agent interprets an ambiguous input, * n8n validates required output fields, * a human approves a consequential action, * the workflow writes the result and records status. Do not replace a reliable API node with an agent simply because natural language is fashionable. Use agent judgment where rules cannot express the work economically. ## Which should you choose? [#which-should-you-choose] Choose **n8n** if: * workflows are primarily event-driven API integrations, * visual process inspection matters, * deterministic branching and transformations dominate, * its available nodes cover the required systems. Choose **Matrix OS** if: * tasks need a filesystem, shell, browser IDE, or arbitrary tools, * an agent must work in a persistent project environment, * the path cannot be fully specified as an automation graph, * people need to inspect and continue the same workspace. Use both when n8n is the orchestration layer and Matrix is a controlled execution environment. Define authentication, idempotency, timeout, retry, and approval boundaries explicitly. ## Test a real exception [#test-a-real-exception] Build the same document or research workflow in both products. Then remove an input, expire a credential, and introduce conflicting data. Compare how each system exposes state, requests intervention, retries safely, and recovers. Happy-path demos obscure the difference. Exceptions reveal whether the workflow is operable. [Read Matrix's trigger-to-outcome architecture](/blog/trigger-to-outcome-matrix-agent-workflows) or [review the current integration documentation](/docs/guide/integrations). # Matrix OS vs Notion AI: smart notebook or company brain? URL: /blog/matrix-os-vs-notion-ai Compare Matrix OS and Notion AI across documents, enterprise search, connected knowledge, structured data, agent actions, execution, and company workflows. **Notion AI is the better choice when your company brain is primarily pages, databases, workspace search, and knowledge retrieved from connected apps. Matrix OS is the better fit when the company brain must also operate through a persistent computer with files, terminals, agents, applications, and running workflows.** Notion is a mature collaborative knowledge workspace. Matrix is developing an agent-native computer and company-workspace layer. Buyers should not treat those as interchangeable maturity or feature sets. *These comparisons use consistent criteria and state when the alternative is stronger. Verify current product and enterprise capabilities directly.* ## At a glance [#at-a-glance] | Criterion | Notion AI | Matrix OS | | --------------- | -------------------------------------------------------- | ------------------------------------------------------------------ | | Core object | Page, database, workspace knowledge | Computer, files, apps, sessions, workflows | | Search | Enterprise Search across Notion and supported connectors | File and tool context available in the Matrix workspace | | Structured work | Mature Notion databases and collaboration | Apps and workspace records; company-OS patterns are still evolving | | Execution | Notion automations, AI, agents, and connected actions | General Linux tools, agent sessions, and Matrix integrations | | Best fit | Documentation and knowledge-centered collaboration | Persistent agent work that needs a computer | ## Where Notion AI is stronger [#where-notion-ai-is-stronger] Notion has established primitives for pages, databases, permissions, comments, templates, and team knowledge. Notion Enterprise Search can search the workspace and connected services such as Slack, Google Drive, and Jira, returning cited sources and respecting connected-app permissions. [See Notion's Enterprise Search guide](https://www.notion.com/help/enterprise-search). Its published security documentation explains connector architecture, permission synchronization, retention, encryption, and workspace isolation. [Review Notion's security documentation](https://www.notion.com/help/enterprise-search-security-and-privacy-practices). Choose Notion when the main problem is documenting, structuring, finding, and collaborating on company knowledge. ## Where Matrix is different [#where-matrix-is-different] Matrix starts with a persistent computer. The workspace can hold files, run tools and terminals, host coding agents, maintain services, and use connected integrations. It aims to connect memory to execution rather than only retrieval. The [Matrix company OS blueprint](/blog/company-os-ai-agents-series) is explicit that many enterprise workflows are product direction. Matrix should not be positioned as a feature-for-feature replacement for Notion today. ## Search versus work [#search-versus-work] Enterprise search answers, “What does the company know?” An agent workspace must also answer: * What is currently being worked on? * Which source and version support this draft? * What action is proposed? * Who must approve it? * What changed after approval? Notion is adding more agent and workflow capability, so this distinction is not permanent or absolute. Evaluate the exact workflow rather than relying on labels such as notebook or operating system. ## Which should you choose? [#which-should-you-choose] Choose **Notion AI** if: * company knowledge already lives in Notion, * pages and databases are the natural work objects, * mature collaboration and enterprise search matter most, * you want to minimize a new infrastructure layer. Choose **Matrix OS** if: * agents need terminals, repositories, local files, or running services, * the workflow crosses code and operational artifacts, * a durable computer is the missing layer, * you want to choose among multiple agent tools. Use both if Notion remains an authoritative knowledge source while Matrix performs bounded work. In that design, preserve source links and permissions rather than copying all company content into uncontrolled agent memory. ## Test one company workflow [#test-one-company-workflow] Try a weekly operating review. Gather project and customer evidence, prepare a brief, record decisions, execute one approved follow-up, and retain the result. Compare source traceability, collaboration, action boundaries, and administrative fit. [Read about building a company brain](/blog/founders-company-brain-that-remembers?preview=1) or [explore Matrix use cases](/use-cases). # Matrix OS vs Replit Agent: app builder or always-on workspace? URL: /blog/matrix-os-vs-replit-agent Compare Matrix OS and Replit Agent for building apps, controlling the environment, running other agents, persistent development work, deployment, and team workflows. **Replit Agent is the more direct choice when you want to describe an application and move quickly from prompt to working preview and deployment inside one product. Matrix OS is the better fit when you want an always-on Linux computer where you choose the repositories, tools, coding agents, terminals, and services.** The practical distinction is guided app creation versus environment ownership. *These comparisons use consistent criteria and neutral recommendations. Verify current features and prices with each provider.* ## At a glance [#at-a-glance] | Criterion | Replit Agent | Matrix OS | | ------------ | ------------------------------------------------------------- | -------------------------------------------------------------- | | Primary job | Build and publish an app from a prompt | Host a persistent computer for agents and development | | Workflow | Guided planning, generation, preview, checkpoints, publishing | User-directed shell, repos, agents, previews, and PRs | | Environment | Replit project environment | Private hosted Linux computer | | Agent choice | Replit Agent | Bring Claude, Codex, OpenCode, Gemini CLI, and other tools | | Deployment | Integrated Replit publishing | Run previews and use the deployment workflow you choose | | Best user | Someone optimizing for a fast app-building loop | Developer or team optimizing for a durable, flexible workspace | ## Where Replit Agent is stronger [#where-replit-agent-is-stronger] Replit provides a coherent path from idea to application. Its official guide emphasizes describing the product, reviewing a plan, letting Agent write and debug code, testing in Preview, using checkpoints, and publishing from the same project. [See Replit's Agent guide](https://docs.replit.com/learn/build-with-agent). That guided experience is valuable for founders, operators, students, and developers who want a fast first result without assembling a toolchain. Choose Replit when integrated creation and publishing are more important than selecting every part of the environment. ## Where Matrix OS is different [#where-matrix-os-is-different] Matrix begins with the computer. You can clone an existing repository, install system packages, authenticate your chosen coding agents, keep named sessions alive, and expose previews through the Matrix workflow. The [Matrix cloud-coding guide](/docs/guide/cloud-coding) documents the workspace as owned files and records under the user's Matrix home. The platform does not require one model or one agent interface. Choose Matrix when the project already has an engineering workflow, when several agents must share the same tools, or when work extends beyond generating one app. ## Important tradeoffs [#important-tradeoffs] ### Speed to first application [#speed-to-first-application] Replit's guided workflow usually has the clearer advantage. It is explicitly designed to turn a description into a preview and publishable application. ### Toolchain freedom [#toolchain-freedom] Matrix provides a general Linux environment with package installation and terminal access. That flexibility is useful, but it asks the user to understand and operate more of the stack. ### Existing repositories [#existing-repositories] Both can work with code projects, but test the exact import, branching, and organization flow you need. Matrix centers Git and terminal workflows; Replit centers the Replit project experience. ### Deployment [#deployment] Replit integrates publishing into the builder. Matrix can keep a preview or service running, but production deployment remains a separate workflow chosen by the team. ### Non-coding work [#non-coding-work] Matrix can host files, apps, assistants, and connected-tool workflows on the same computer. Those use cases are broader, but each required integration should be confirmed against current documentation. ## Which should you choose? [#which-should-you-choose] Choose **Replit Agent** if: * you want the shortest guided path from idea to hosted app, * one integrated builder and deployment flow is desirable, * visual preview and conversational iteration are the core workflow, * managing a general-purpose machine would add unnecessary complexity. Choose **Matrix OS** if: * you want a persistent general-purpose cloud computer, * the team brings its own repositories and agent tools, * multiple long-running terminals and services matter, * the development environment must support work beyond one app builder. ## Test with the same project [#test-with-the-same-project] Ask each platform to import or create a small full-stack app, add one feature, run tests, recover from a broken change, expose a preview, and document how the work reaches production. Compare time, control, review evidence, portability, and ongoing operational effort. The right choice is the workflow your team can reliably own after the first impressive demo. [Explore the Matrix cloud workspace](/solutions/ai-coding-agents-cloud-workspace) or [start with the developer quickstart](/docs/quickstart). # Matrix OS vs Salesforce Agentforce: agent layer or owned workspace? URL: /blog/matrix-os-vs-salesforce-agentforce Compare Matrix OS and Salesforce Agentforce across CRM data, business actions, governance, agent orchestration, persistent compute, ownership, and enterprise fit. **Salesforce Agentforce is the stronger choice when agents should operate on Salesforce data, metadata, flows, and business actions within an enterprise CRM platform. Matrix OS is the stronger fit when an agent needs an owned, persistent computer with files, terminals, applications, and tools beyond the Salesforce environment.** These products have very different maturity, scope, and buying motions. Matrix should not be presented as a replacement for the Salesforce platform. *These comparisons use consistent criteria, cite current sources, and explain when the alternative is better. Enterprise teams should run security and architecture reviews.* ## At a glance [#at-a-glance] | Criterion | Salesforce Agentforce | Matrix OS | | ----------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Center of gravity | Salesforce data, metadata, applications, and actions | Persistent cloud computer and agent workspace | | Agent grounding | Data 360 and connected structured or unstructured data | Selected workspace files, repos, apps, and integrations | | Actions | Salesforce flows, APIs, Apex, prompt templates, platform actions | Linux tools, terminal agents, and documented Matrix integrations | | Governance | Salesforce enterprise security, observability, and administration | Owner-controlled workspace boundaries; validate enterprise requirements directly | | Best fit | Enterprise customer workflows centered on Salesforce | Open-ended work requiring a general execution environment | ## Where Agentforce is stronger [#where-agentforce-is-stronger] Salesforce positions Agentforce as a platform for designing and orchestrating agents using enterprise data, business logic, and actions. Its documentation describes actions backed by flows, prompt templates, Apex, and other platform capabilities. [See how Agentforce works](https://www.salesforce.com/agentforce/how-it-works/) and the [developer action model](https://developer.salesforce.com/docs/ai/agentforce/guide/get-started-actions.html). Organizations already standardized on Salesforce gain proximity to customer records, permissions, reporting, and existing automation. Choose Agentforce when the workflow is fundamentally a Salesforce workflow. ## Where Matrix is different [#where-matrix-is-different] Matrix gives each agent or user a durable computer. The workspace can host code repositories, local documents, command-line tools, previews, applications, and different agent runtimes. That creates flexibility for work that spans engineering and business artifacts. It does not provide Salesforce's CRM data model, Data 360, ecosystem, governance maturity, or prebuilt enterprise actions. ## Platform data versus selected context [#platform-data-versus-selected-context] Agentforce can ground work in the Salesforce platform and connected data. Matrix can work from selected files and connected tools without requiring the company to centralize its operation in one CRM. The first model can provide richer standardized business context. The second can reduce coupling and give the agent a broader execution environment. Each creates different permission, consistency, and maintenance responsibilities. ## Which should you choose? [#which-should-you-choose] Choose **Salesforce Agentforce** if: * Salesforce is a core system of record, * agents need governed access to CRM data and platform actions, * enterprise administration and observability are mandatory, * the organization already has Salesforce architecture and operations capacity. Choose **Matrix OS** if: * the agent needs a general Linux computer, * work spans repositories, documents, local tools, and multiple systems, * you want a contained experimental environment, * Salesforce-centered architecture would be disproportionate to the workflow. Use both if Agentforce governs Salesforce-native customer actions while Matrix performs bounded work outside the CRM. Define which system owns each record and never let two agents silently update the same state. ## Run a controlled pilot [#run-a-controlled-pilot] Test one workflow with real exceptions: conflicting customer data, a missing approval, an unavailable connector, and an action that must be reversed. Measure completion, source traceability, administrative effort, security review, reviewer load, and total operating cost. The winning product is the one whose control model matches the system where the decision belongs. [Explore Matrix's enterprise AI lab](/solutions/enterprise-ai-coding-lab) or [read about permissions and audit](/blog/trust-layer-company-ai-agents). # Matrix OS vs Zapier and Make: zaps or a computer that does the work? URL: /blog/matrix-os-vs-zapier-make Compare Matrix OS with Zapier and Make across app integrations, visual automation, agentic steps, persistent compute, files, approvals, and workflow ownership. **Zapier and Make are usually better when the work is a well-defined sequence of events and actions across SaaS applications. Matrix OS is better when the work needs a persistent computer, local files, terminals, installed tools, or an agent that must explore before it can act.** The categories are converging. Automation platforms now include AI and agents, while agent workspaces connect external services. The deciding question is whether the workflow is best represented as an automation graph or as work performed inside a computer. *These comparisons use consistent criteria and neutral conclusions. Verify current plans, integration coverage, and limits directly.* ## At a glance [#at-a-glance] | Criterion | Zapier and Make | Matrix OS | | ----------------- | -------------------------------------------------------- | ---------------------------------------------------------- | | Center of gravity | Triggers, actions, data mapping, branches | Persistent computer, agents, files, apps, sessions | | Integrations | Very broad SaaS connector ecosystems | Smaller Matrix integration layer plus Linux tools and APIs | | Predictability | Strong for explicit flows | Stronger for open-ended tasks; requires tighter review | | Local artifacts | Usually passed between steps or stored in connected apps | Native files and processes on the computer | | Best fit | Cross-app business automation | Tool-rich agent execution and durable workspaces | ## Where Zapier and Make are stronger [#where-zapier-and-make-are-stronger] These platforms are designed to connect applications without requiring every team to build integration infrastructure. Their visual builders make triggers, mappings, filters, routers, and actions explicit. Zapier describes its core workflow as a trigger followed by one or more actions and offers thousands of integrations, plus AI steps and agentic workflows. [See Zapier's product overview](https://help.zapier.com/hc/en-us/articles/37518970271245-What-is-Zapier). Choose an automation platform when the work is repeatable, application-centric, and expressible as known steps. ## Where Matrix is different [#where-matrix-is-different] Matrix provides the place where an agent works. It can retain source files, run a command-line tool, inspect a repository, create an application, or keep a process alive. This is useful when the next action depends on investigating a changing environment rather than mapping fields between two APIs. Matrix currently documents integrations with Gmail, Google Calendar, Google Drive, GitHub, Slack, and Discord. [Review the current actions](/docs/guide/integrations). It should not be described as matching Zapier or Make's connector breadth. ## When a workflow graph is better [#when-a-workflow-graph-is-better] Use Zapier or Make for: * copying a qualified form submission into a CRM, * routing notifications by explicit rules, * synchronizing known fields, * scheduling reports from supported sources, * applying deterministic transformations. The graph is an advantage because operators can see and test the path. ## When a computer is better [#when-a-computer-is-better] Use Matrix for: * modifying a repository and running tests, * working across a folder of changing documents, * using command-line or locally installed tools, * maintaining long-running previews or processes, * exploratory work whose path is not known in advance. The computer is an advantage because the agent has a real environment. It also expands the blast radius, so credentials and approvals matter. ## Which should you choose? [#which-should-you-choose] Choose **Zapier or Make** if connector breadth and deterministic cross-app automation dominate. Choose **Matrix OS** if execution requires a durable filesystem, shell, software tools, or a general-purpose agent workspace. Use both when the automation platform owns triggers and exact API actions while Matrix performs a bounded, artifact-producing task. Give the combined workflow an idempotency key, timeout, retry policy, owner, and approval boundary. ## Evaluate the failure path [#evaluate-the-failure-path] Run a workflow with a missing field, revoked credential, duplicate trigger, slow agent, and failed destination. Compare whether the system prevents duplicate actions, exposes useful evidence, and lets an operator recover without guessing. The product with more logos on its integration page is not automatically the better operating system. The winner is the one that makes your actual workflow reliable. [Read about reliable Matrix workflows](/blog/trigger-to-outcome-matrix-agent-workflows) or [explore the professional assistant](/solutions/professional-ai-assistant-cloud-computer). # OpenHands Cloud vs self-hosted vs Matrix OS URL: /blog/openhands-cloud-self-hosted-matrix-os Compare OpenHands Cloud, self-hosted OpenHands, and Matrix OS by agent layer, runtime ownership, isolation, persistence, and operational responsibility. OpenHands Cloud, self-hosted OpenHands, and Matrix OS solve different layers of the coding-agent stack. OpenHands is an agent platform with hosted and self-hosted deployment paths. Matrix OS is a retained computer and workspace where terminal agents and development services run. The right choice depends on whether you are selecting the agent, the runtime, or both. That distinction corrects an outdated comparison: OpenHands does provide managed infrastructure through OpenHands Cloud. Its documentation also supports local, CLI, headless, remote-runtime, and enterprise deployment patterns. [Review the current OpenHands options](https://docs.openhands.dev/overview/quickstart). ## What does OpenHands provide? [#what-does-openhands-provide] OpenHands supplies the software-development agent experience: task execution, tool use, model configuration, repository workflows, and sandbox runtimes. The local setup uses a containerized runtime by default, while OpenHands Cloud supplies managed sandbox environments. OpenHands Enterprise adds a self-hosted or private-cloud path with organizational controls. That means “OpenHands” is not one hosting model. Buyers should evaluate Cloud, open-source local deployment, and Enterprise separately. [See the deployment matrix](https://docs.openhands.dev/enterprise). ## What does Matrix OS provide? [#what-does-matrix-os-provide] [Matrix OS](https://matrix-os.com) starts from the computer rather than a single agent framework. It provides a retained cloud machine with repositories, terminals, files, preview services, browser access, and Matrix's orchestration surfaces. Teams can use terminal agents such as Claude Code, Codex, Gemini CLI, and OpenCode in that environment. Matrix and OpenHands are therefore not strict substitutes. A technically capable operator may install OpenHands on a compatible Matrix computer, but that should be evaluated as a self-managed application deployment—not presented as a built-in Matrix integration. ## Compare the operating models [#compare-the-operating-models] | Question | OpenHands Cloud | Self-hosted OpenHands | Matrix OS | | ---------------- | ---------------------------------------- | ------------------------------------- | ------------------------------------------ | | Primary purchase | Managed coding-agent product | Agent platform you operate | Retained agent computer and workspace | | Agent choice | OpenHands with supported models | OpenHands with configured models | Multiple terminal-agent tools | | Runtime | Managed sandbox | Docker/local/enterprise configuration | Dedicated Matrix computer | | Operations | OpenHands manages service infrastructure | Your team manages deployment | Matrix manages hosted computer layer | | Best fit | Fast OpenHands adoption | Customization and private deployment | Durable multi-tool development environment | None wins every row. OpenHands Cloud is the shortest route if the team specifically wants the OpenHands agent. Self-hosting is strongest when deployment control and customization justify operational work. Matrix fits when the persistent environment and freedom to use several terminal agents are the primary requirements. ## Where persistence actually lives [#where-persistence-actually-lives] “Persistent” can refer to different things: * conversation history; * files inside a runtime; * a resumable sandbox; * a retained development machine; * a process that restarts after host failure. Do not collapse these into one checkbox. OpenHands documents conversation resume and several runtime choices. Matrix retains the project computer across client disconnections. Neither removes the need for Git checkpoints, backups, and process supervision when recovery matters. ## Security and isolation questions [#security-and-isolation-questions] Before choosing, ask: 1. Where do repository data and generated artifacts live? 2. Which party owns model credentials? 3. Is isolation per task, user, team, or machine? 4. Can runtimes reach private services safely? 5. Who patches the host and runtime images? 6. What survives termination, restart, or account closure? OpenHands warns that its open-source single-user setup is not a ready-made multi-tenant deployment; Enterprise exists for broader organizational requirements. Matrix users should likewise treat a dedicated computer as a security boundary that still requires scoped credentials and review gates. ## Which option should you choose? [#which-option-should-you-choose] Choose **OpenHands Cloud** when you want OpenHands with minimal installation and its managed repository workflow. Choose **self-hosted OpenHands** when you want to customize the agent stack and are prepared to operate its application, containers, authentication, networking, and upgrades. Choose **Matrix OS** when you want a retained development computer that supports several terminal-agent workflows, persistent project services, and direct browser or shell access. If you need both, test OpenHands on a compatible retained host against a representative repository. Validate installation, resource use, sandbox security, preview routing, and recovery before calling the combination production-ready. For adjacent decisions, see [Codex alternatives in 2026](/blog/codex-alternative-2026), [Matrix OS vs a VPS](/blog/matrix-os-vs-vps), and [E2B alternatives for persistent workloads](/blog/e2b-alternative). ## Frequently asked questions [#frequently-asked-questions] ### Does OpenHands provide cloud compute? [#does-openhands-provide-cloud-compute] Yes. OpenHands Cloud uses managed sandbox environments. OpenHands also documents local, remote-runtime, and enterprise self-hosted options. ### Is Matrix OS an OpenHands replacement? [#is-matrix-os-an-openhands-replacement] Not directly. OpenHands is primarily an agent platform; Matrix is primarily a retained computer and workspace for agents. The overlap is in where and how agent work executes. ### Can OpenHands run on Matrix OS? [#can-openhands-run-on-matrix-os] A Matrix computer is a general Linux environment, so installation may be possible when current OpenHands requirements are satisfied. Treat this as a self-managed deployment and validate it; it is not currently documented as a first-class Matrix integration. ### Which option offers the most control? [#which-option-offers-the-most-control] Self-hosted OpenHands offers the most control over the OpenHands application stack. Matrix offers direct control over a retained project environment while managing more of the surrounding platform. OpenHands Cloud minimizes setup but delegates more infrastructure decisions to its vendor. # Recipe, skill, routine, or workflow? An AI agent glossary URL: /blog/recipe-skill-routine-workflow-glossary Understand the practical differences between AI agent recipes, prompts, skills, routines, workflows, schedules, and automations. An AI agent recipe describes a repeatable job. A skill supplies reusable know-how. A workflow connects steps into an outcome. A routine or schedule determines when that workflow runs. Automation describes how much of the process proceeds without a person. Vendors use these words differently, so the safest approach is to ask what each object contains and what it can change—not rely on the label alone. ## The terminology at a glance [#the-terminology-at-a-glance] | Term | Practical meaning | Main question | | ---------- | -------------------------------------------------------- | --------------------------------------------- | | Prompt | A request or instruction given to a model or agent | What are you asking now? | | Recipe | A reusable brief for a defined job and result | How should this job be repeated? | | Skill | Reusable procedural knowledge or capability instructions | How does the agent perform this kind of work? | | Workflow | Connected steps, tools, decisions, and handoffs | How does work move from trigger to outcome? | | Routine | A repeatable workflow associated with timing or an event | When should the work run? | | Schedule | A time-based trigger | At what time or interval does it start? | | Automation | A degree of execution without human intervention | Which steps happen without approval? | These objects can be combined. A scheduled workflow may invoke several skills while following a recipe and pausing before an external action. ## What is a prompt? [#what-is-a-prompt] A prompt is the instruction presented to the model or agent during a run. It may be one sentence or a detailed brief. Prompts are flexible, but they often omit operational context such as authoritative sources, permissions, and stopping conditions. Use a prompt for exploration or a one-time request. Promote it into a recipe when the job repeats and consistency matters. ## What is a recipe? [#what-is-a-recipe] A recipe packages a job so someone can run it again. In Matrix, a recipe identifies the inputs, work, expected result, and review step. Current [Matrix Recipes](/recipes) are copied and started manually; copying one does not install software, connect tools, or create a schedule. Use a recipe when the outcome should be repeatable but the operator still needs to provide sources or supervise the run. ## What is a skill? [#what-is-a-skill] A skill captures reusable instructions for a capability. It might explain how to review a pull request, classify customer risk, apply brand voice, or prepare a weekly account-health report. Skills are broader than a single recipe. One skill can support several jobs, and one recipe can invoke several skills. Availability and packaging differ across agent products. ## What is a workflow? [#what-is-a-workflow] A workflow is the full path from trigger to outcome: `trigger → gather evidence → perform work → verify → request approval → act → record result` The workflow includes systems and people, not just model instructions. A sales follow-up workflow may read meeting notes, update a draft, ask an account owner to approve it, send through email, and record the outcome. The recipe describes how to run that job. The workflow describes how the job fits into operations. ## What is a routine or schedule? [#what-is-a-routine-or-schedule] In Grok Bot's terminology, a skill records how to perform a task, while a routine tells a Bot when to run it—on a schedule or, where supported, after an event. [See xAI's definitions](https://docs.x.ai/grok-bot/skills-routines-and-automations). Matrix separates the task brief from scheduling as well. A copied recipe runs once unless a supported runtime is configured to run recurring work. [Review the current Matrix behavior](/docs/guide/recipes). This separation is healthy. Changing the trigger should not silently change permissions or approval rules. ## What is automation? [#what-is-automation] Automation is not a document type. It is a property of the workflow. A workflow may be: * manually started and manually approved; * automatically started but manually approved; * manually started with bounded autonomous execution; * automatically started and executed, with exceptions escalated; * fully automatic within an explicitly low-risk boundary. Describe the actual autonomy level instead of calling the entire system “automated.” ## A concrete example [#a-concrete-example] Consider a weekly competitor report: * **Prompt:** “Summarize competitor changes this week.” * **Recipe:** named competitors, primary sources, comparison fields, output format, and review rules. * **Skills:** web research, source evaluation, and Matrix editorial style. * **Workflow:** collect changes, verify them, draft the report, request review, and store the approved version. * **Routine:** run every Monday at 09:00. * **Automation:** research and drafting happen automatically; publication requires approval. The distinctions make failures easier to diagnose. If the report is weak, improve the recipe or skills. If it runs at the wrong time, fix the routine. If it publishes prematurely, fix the approval boundary. ## Frequently asked questions [#frequently-asked-questions] ### Is a skill the same as a workflow? [#is-a-skill-the-same-as-a-workflow] No. A skill describes reusable know-how. A workflow connects work, tools, decisions, and people from a trigger to an outcome. ### Is a routine the same as a schedule? [#is-a-routine-the-same-as-a-schedule] Not always. A schedule is time-based. A routine may also begin after a supported event, such as a new ticket or message. ### Does copying a Matrix recipe automate the task? [#does-copying-a-matrix-recipe-automate-the-task] No. It gives the agent a reusable task brief. Tool connections, permissions, scheduling, and approval rules remain separate. ### Which object should I create first? [#which-object-should-i-create-first] Start with a successful task. Capture it as a [repeatable AI agent recipe](/blog/ai-agent-recipes-repeatable-workflows), refine the needed skills, and define the workflow before adding a routine or schedule. # From first touch to close: an agentic sales workflow URL: /blog/sales-agentic-workflow-first-touch-to-close A stage-by-stage guide to using agents for account research, qualification, meeting preparation, proposals, follow-ups, approvals, and handoffs. An agentic sales workflow uses AI to prepare and coordinate work across the sales cycle while keeping qualification, commitments, pricing, and customer communication under accountable human control. The goal is not to automate a buyer through a funnel. It is to reduce the searching, copying, reformatting, and follow-up debt that prevents sellers from doing the work only they can do. ## Stage 1: research the account [#stage-1-research-the-account] The agent can assemble public company information and approved internal history into a structured brief: * why the account may fit, * relevant events or initiatives, * known contacts and relationships, * prior conversations, * plausible questions to validate. Separate verified facts from hypotheses. Every material account claim should link to a source and include a date. ## Stage 2: support qualification [#stage-2-support-qualification] An agent can compare notes with a qualification framework and flag missing evidence. It should not promote an opportunity because a summary “sounds positive.” Useful outputs include: * confirmed need and business impact, * stakeholders identified and missing, * decision process, * timeline evidence, * unresolved technical or security questions, * contradictions across records. The account owner decides whether the opportunity advances. ## Stage 3: prepare the meeting [#stage-3-prepare-the-meeting] Generate a compact briefing rather than a data dump. A strong brief includes the meeting objective, participants, recent changes, open commitments, likely objections, and five high-value questions. Keep the brief in the deal workspace so corrections improve later work. Do not make the rep reconstruct context from a fresh chat before every call. ## Stage 4: turn the conversation into a plan [#stage-4-turn-the-conversation-into-a-plan] After the call, the agent can draft: * decisions and evidence, * explicit buyer commitments, * seller commitments, * risks and unanswered questions, * next meeting objectives, * proposed CRM updates. A person confirms the record before it changes the opportunity or triggers external work. ## Stage 5: assemble proposals and follow-ups [#stage-5-assemble-proposals-and-follow-ups] The workflow can retrieve approved product language, selected case material, technical answers, and the buyer's stated needs. It can prepare a proposal section or follow-up message, but pricing, legal terms, promises, recipients, and sending require review. Matrix's guidance on [safe email agents](/blog/building-safe-email-agents) begins with attention and drafting rather than autonomous sending. The same rule applies throughout sales: autonomy should be earned from evidence. ## Stage 6: coordinate approval [#stage-6-coordinate-approval] Complex deals often stall inside the seller's company. An agent can assemble approval packets for security, legal, finance, or leadership, showing: * the requested decision, * current deal context, * supporting documents, * unresolved risks, * deadline and downstream effect. The reviewer should be able to approve, reject, or request changes without hunting for context. ## Stage 7: create a clean handoff [#stage-7-create-a-clean-handoff] Closing is not the end of the workflow. Prepare a handoff that distinguishes contract facts, promised outcomes, implementation dependencies, stakeholders, risk, and open questions. The receiving team confirms ownership. The workspace retains the path from sales evidence to delivery expectations. ## A control model for the full cycle [#a-control-model-for-the-full-cycle] | Activity | Agent role | Human role | | ------------------- | ---------------------------- | ------------------------------- | | Research | Gather and cite | Validate fit | | Qualification | Find gaps | Make the judgment | | Meeting preparation | Assemble context | Lead the conversation | | CRM hygiene | Propose changes | Approve material changes | | Proposal | Draft from approved material | Own claims and commercial terms | | Follow-up | Prepare | Approve and send | | Handoff | Assemble evidence | Accept ownership | Salesforce's State of Sales research tracks how sales organizations are adopting AI while dealing with data and trust constraints. [Read the research hub](https://www.salesforce.com/sales/state-of-sales/). The practical response is not “more AI everywhere.” It is a visible workflow with reliable sources and clear authority. ## How Matrix fits [#how-matrix-fits] Matrix provides a persistent cloud workspace where files, agent sessions, apps, and connected-tool workflows can remain available independently of one laptop. Its [trigger-to-outcome architecture](/blog/trigger-to-outcome-matrix-agent-workflows) maps naturally to sales: event, evidence, draft, review, action, and audit. Some of the workflow above is forward-looking product design. Teams should verify current integrations and actions in the [Matrix integrations documentation](/docs/guide/integrations) before planning a deployment. Start with one segment and one workflow. Measure time to preparation, correction rate, overdue follow-ups, and stage-data completeness. Expand only after the evidence is trustworthy. [See the agent-native CRM blueprint](/blog/building-agent-native-crm-matrix) or [discuss a team pilot](/contact?audience=team). # The deal room that never forgets URL: /blog/sales-deal-room-that-never-forgets How an agent-native deal room can keep account context, documents, decisions, follow-ups, and human approvals together from first meeting to close. A deal room that never forgets is not a folder with an AI search box. It is a durable workspace around one opportunity: the people, meetings, messages, documents, decisions, risks, and next actions required to move it forward. The CRM can remain the system of record. The deal room becomes the place where the team and its agents assemble context, prepare work, and maintain continuity without pretending that every interaction fits into a row of fields. ## What belongs in an agent-native deal room? [#what-belongs-in-an-agent-native-deal-room] The workspace should connect five kinds of information: * **Account facts:** company, contacts, stage, value, owner, and timeline. * **Conversation history:** selected emails, calls, notes, and commitments. * **Working artifacts:** research, plans, drafts, proposals, and mutual action plans. * **Decisions:** qualification judgments, exceptions, approvals, and changes in strategy. * **Next actions:** owner, deadline, dependency, and current status. Each item should retain a source. Generated summaries are useful navigation, but they should not silently become the record. ## Memory should prevent three common failures [#memory-should-prevent-three-common-failures] ### Repeating questions the buyer already answered [#repeating-questions-the-buyer-already-answered] Before a meeting, the agent can assemble prior requirements, objections, and unresolved questions. The seller reviews the brief rather than searching across inboxes and notes. ### Losing commitments between meetings [#losing-commitments-between-meetings] If a rep promises a security document or a follow-up date, the workspace should capture the commitment, assign an owner, and surface it until resolved. ### Rebuilding the story during handoff [#rebuilding-the-story-during-handoff] When sales hands an account to implementation or customer success, the receiving team should see evidence, decisions, constraints, and open risks—not only the latest CRM fields. ## What can an agent do safely? [#what-can-an-agent-do-safely] | Stage | Useful agent work | Human control | | ------------- | --------------------------------------------- | -------------------------------- | | Research | Assemble public and approved internal context | Confirm relevance | | Qualification | Flag gaps and contradictions | Decide whether to progress | | Meeting prep | Draft agenda and questions | Choose the conversation strategy | | Proposal | Assemble approved language and evidence | Approve scope, price, and claims | | Follow-up | Draft from meeting commitments | Approve recipient and send | | Handoff | Prepare an implementation brief | Confirm responsibilities | The agent should make the deal legible. It should not invent certainty or make commercial commitments. ## Keep the CRM, add the working layer [#keep-the-crm-add-the-working-layer] A lightweight deal workspace does not need to replace HubSpot, Salesforce, or another CRM. It can read selected context, organize working files, and write back approved updates through bounded workflows. Salesforce's State of Sales research frames AI adoption alongside persistent concerns about data quality, disconnected systems, and security. Those are not reasons to avoid agents; they are reasons to preserve provenance and review. [Explore Salesforce's State of Sales](https://www.salesforce.com/sales/state-of-sales/). Matrix's [agent-native deal workspace blueprint](/blog/agent-native-deal-workspace-matrix) describes how deal records, connected files, communication, document assembly, and approvals could work together. It is a product direction, not a claim that Matrix currently replaces a full CRM. ## Begin with meeting preparation and follow-up [#begin-with-meeting-preparation-and-follow-up] This is a narrow, measurable first loop: 1. Associate approved account sources with the workspace. 2. Assemble a one-page pre-call brief. 3. Record decisions and commitments after the call. 4. Draft a follow-up with evidence from the notes. 5. Ask the account owner to approve the message. 6. Track whether each commitment is completed. Measure prep time, factual corrections, overdue commitments, and draft acceptance. Do not start by allowing autonomous outbound communication. ## The deal—not the chat—is the durable object [#the-dealnot-the-chatis-the-durable-object] A chat ends. A deal continues across people and weeks. The workspace should let a new participant answer: What does the buyer need? What did we promise? What evidence supports our position? What must happen next? When those answers remain available and reviewable, the deal room has memory. When the agent can prepare the next step without taking ownership away from the seller, it becomes operational. [Explore Matrix's professional-assistant use case](/solutions/professional-ai-assistant-cloud-computer) or [talk to Matrix about a sales workflow](/contact?audience=team). # The sales pipeline that updates itself—without losing human control URL: /blog/sales-pipeline-updates-itself-human-control How agents can improve CRM hygiene, detect stale opportunities, resolve duplicates, and prepare pipeline updates without silently rewriting the forecast. A sales pipeline can update itself safely only when the agent proposes evidence-backed changes, applies deterministic rules where possible, and routes ambiguous or consequential decisions to a human owner. “Keep the CRM current” sounds like a simple automation. In practice, the source data is incomplete, contacts duplicate, stages mean different things to different reps, and a forecast can change management decisions. The right design is not unrestricted write access. It is a reviewable reconciliation workflow. ## Begin with observable problems [#begin-with-observable-problems] Pipeline hygiene usually breaks in predictable ways: * opportunities have no recent activity, * close dates move without explanation, * contacts are duplicated, * meeting commitments never reach the CRM, * stage and evidence disagree, * ownership is missing after a handoff, * the forecast includes stale or poorly qualified deals. An agent can detect these conditions and prepare a queue. That is more useful than generating a weekly paragraph that hides the underlying records. ## Separate deterministic checks from agent judgment [#separate-deterministic-checks-from-agent-judgment] Use rules for conditions a database can establish: * no activity for 21 days, * close date in the past, * required field empty, * same normalized email on two contacts, * opportunity has no next action. Use an agent for tasks that require interpreting text: * extracting a commitment from meeting notes, * identifying a likely objection, * explaining why stage evidence appears inconsistent, * drafting a recommended update. The agent's interpretation should remain a proposal until an owner approves it. ## Use confidence to route work, not conceal uncertainty [#use-confidence-to-route-work-not-conceal-uncertainty] | Condition | Suggested handling | | ----------------------------------------- | --------------------------------- | | Exact duplicate with identical source IDs | Deterministic merge candidate | | Similar names but different domains | Human review | | Missing next action | Ask the owner | | Meeting explicitly confirms a date | Propose update with citation | | Agent infers buying intent from tone | Do not change stage automatically | A confidence score is not permission. Show the evidence and the reason for the proposed change. ## Protect the forecast boundary [#protect-the-forecast-boundary] Stage, amount, probability, and close date affect forecasts. Treat them as high-impact fields: 1. Present the current value. 2. Present the proposed value. 3. Link the supporting source. 4. Identify the rule or inference. 5. Require the account owner or sales manager to approve. 6. Record who accepted the change. Low-risk hygiene, such as formatting a phone number, may earn more automation after repeated validation. Forecast changes should remain accountable. ## Design a daily pipeline agent [#design-a-daily-pipeline-agent] A bounded workflow could: 1. Read changed records and selected activity. 2. Run deterministic hygiene checks. 3. Analyze only the flagged records. 4. Prepare proposed updates and questions. 5. Group them by owner. 6. Apply approved changes through the CRM API. 7. Record successes, failures, and rejected proposals. The agent should never convert a provider error into a silent success. If the CRM rejects an update, the exception remains visible. ## Data quality is the prerequisite [#data-quality-is-the-prerequisite] Salesforce's State of Sales research examines AI adoption alongside the quality, security, and integration of sales data. [Explore the report](https://www.salesforce.com/sales/state-of-sales/). An agent cannot create trustworthy pipeline intelligence from records with unclear ownership and inconsistent definitions. Before automating, define what each stage means, which source wins during conflict, which fields are protected, and how duplicates are resolved. ## How Matrix could support the workflow [#how-matrix-could-support-the-workflow] Matrix's product direction combines persistent workspace state, connected tools, drafts, approvals, and activity. The [agent-native CRM blueprint](/blog/building-agent-native-crm-matrix) explains how a lightweight operational record could work alongside existing systems. This article is a design pattern, not an announcement of a complete autonomous CRM-sync product. Verify available services and actions in the [integration documentation](/docs/guide/integrations). ## Measure trust before autonomy [#measure-trust-before-autonomy] Track: * precision of duplicate and stale-deal flags, * percentage of proposals approved unchanged, * reviewer correction rate, * time records remain incomplete, * update failures and reversals, * forecast changes attributable to agent proposals. The best pipeline agent does not make the CRM look busy. It makes the state of the business more accurate while leaving important judgments with identifiable people. [Read about permissions and audit for company agents](/blog/trust-layer-company-ai-agents) or [talk to Matrix about a sales-operations pilot](/contact?audience=team). # No more laptop roulette: running AI-native courses in the cloud URL: /blog/university-ai-courses-no-laptop-roulette How cloud development environments reduce setup drift across devices while giving AI-native courses persistent tools, repos, previews, and clearer support boundaries. AI-native courses are unusually vulnerable to laptop roulette: one student has an unsupported operating system, another lacks administrator rights, a third has no space for a model or container, and half the room is running different dependency versions. A cloud lab moves the execution environment out of the student's device. The laptop, tablet, or shared computer becomes an access surface; the course tools and project state live in a consistent hosted workspace. ## Why AI courses amplify setup drift [#why-ai-courses-amplify-setup-drift] Traditional programming courses already struggle with compilers, runtimes, package managers, and permissions. Agentic development adds: * multiple coding-agent CLIs, * browser and device authentication flows, * long-running terminals, * preview servers and forwarded ports, * model-provider accounts, * repositories and worktrees, * larger compute and storage variation, * new security and academic-integrity concerns. A setup guide cannot eliminate differences in every personal machine. ## What moves into the cloud? [#what-moves-into-the-cloud] The hosted environment should contain the course-controlled layer: * starter repository, * required runtime and packages, * terminal and browser IDE, * approved agent tools, * persistent student files, * preview and test processes, * assignment-specific instructions. Students still use their own identity and approved provider accounts where required. Do not solve convenience by copying personal keys or broad credentials into a shared image. ## Design a repeatable course template [#design-a-repeatable-course-template] Create a versioned template for each module: 1. Base operating environment. 2. Tool and dependency versions. 3. Starter project commit. 4. Expected commands and ports. 5. Network and data rules. 6. Submission artifacts. 7. Recovery procedure. 8. Teardown or retention date. Test it with a new account, a small screen, and a slow connection—not only on the instructor's configured machine. ## Preserve persistence without hiding work [#preserve-persistence-without-hiding-work] Students need to stop and resume without losing a running session or local files. Faculty need evidence of what happened. Matrix's cloud-coding model keeps projects, worktrees, sessions, transcripts, reviews, and editor settings in the user's Matrix home. The [cloud coding documentation](/docs/guide/cloud-coding) explains how the browser desktop, CLI, and browser IDE operate on the same durable records. Persistence should support learning, not surveillance. Define what is retained, who can inspect it, why it is needed, and when it is deleted. ## Plan for failure as part of the course [#plan-for-failure-as-part-of-the-course] A lab needs a recovery path for: * broken dependencies, * runaway processes, * expired authentication, * corrupted starter files, * unavailable models, * network interruptions, * a student's accidental deletion. Decide whether faculty restore a clean template, preserve the student's workspace for diagnosis, or provide a new environment. Avoid an informal process that treats each failure differently. ## Measure the pilot [#measure-the-pilot] Track: * median time to first successful command, * percentage starting without instructor intervention, * support requests by category, * environment resets, * assignment completion, * accessibility issues, * compute and storage use, * student confidence before and after the module. The point is not to prove cloud is universally better. Some courses need local hardware, offline access, or specialized environments. Use the data to decide. EDUCAUSE's AI landscape work emphasizes policy, privacy, workforce readiness, and the institutional digital divide alongside adoption. [Read the EDUCAUSE study](https://library.educause.edu/resources/2025/2/2025-educause-ai-landscape-study). IREX reports that governed pilots and systematic impact measurement remain limited across its higher-education sample. [Read the IREX findings](https://www.irex.org/universityaireadiness). ## Start before the first class [#start-before-the-first-class] The best cloud lab is boring on day one. Accounts work, repositories open, the expected agent starts, previews load, and recovery is documented. That gives instructors room to teach the hard questions: how to direct an agent, verify its work, understand its limits, and remain responsible for the result. [See Matrix's university lab solution](/solutions/university-ai-development-lab) or [plan a pilot](/contact?audience=university). # The university AI lab in a box URL: /blog/university-ai-lab-in-a-box A practical model for repeatable university AI labs with cloud computers, starter repositories, coding agents, persistent previews, and faculty oversight. A university AI lab in a box is a repeatable cloud environment for courses, workshops, hackathons, and research groups. Each participant gets a consistent computer with the required files, tools, agents, and project context, while faculty define the exercise and retain oversight. The goal is not to make every course identical. It is to remove accidental differences in operating systems, laptop power, permissions, and local setup so class time can focus on the work. ## What should the lab include? [#what-should-the-lab-include] A practical lab template should define: * operating-system and runtime requirements, * starter repositories and datasets, * approved coding agents and model access, * package and tool versions, * storage and compute limits, * network and integration boundaries, * assignment instructions and evaluation artifacts, * retention and teardown policy. The environment should be reproducible without making student work disposable. A learner needs continuity across sessions; an instructor needs a clean baseline for the next cohort. ## One environment, several teaching modes [#one-environment-several-teaching-modes] ### Courses [#courses] Provision a standard workspace for a semester, attach starter projects, and preserve files and previews between classes. ### Workshops and hackathons [#workshops-and-hackathons] Prepare environments before the event so participants can begin from a browser rather than spend the opening hour installing dependencies. ### Research groups [#research-groups] Give each researcher or project an isolated working environment with explicit data and compute boundaries. ### Faculty experimentation [#faculty-experimentation] Run governed pilots away from primary university devices before adopting a new agent or skill more broadly. ## Make agent use observable [#make-agent-use-observable] Teaching with agents requires more than allowing or banning a chatbot. A lab can ask students to retain: * prompts or task instructions, * agent session output, * changed files and diffs, * test results, * source citations, * a reflection on what the student verified or corrected. The artifact becomes evidence of process. Assessment can focus on reasoning, verification, and ownership rather than guessing whether AI was involved. ## Build the lab around clear roles [#build-the-lab-around-clear-roles] | Role | Responsibility | | -------- | --------------------------------------------------------------------- | | Faculty | Define learning objectives, permitted tools, and evaluation | | IT | Approve identity, network, data, retention, and support boundaries | | Student | Direct and verify work; disclose use as required | | Agent | Prepare, execute, explain, and expose evidence within its permissions | | Platform | Keep environments consistent, accessible, and recoverable | Technology cannot resolve academic policy by itself. It can make the chosen policy easier to operate. ## How Matrix fits [#how-matrix-fits] Matrix's [university AI development lab](/solutions/university-ai-development-lab) provides hosted cloud computers for courses, workshops, research groups, and hackathons. Students can work from a browser or CLI, use starter repositories, run terminal agents, and keep previews online. Matrix currently provides individual hosted workspaces and a guided university pilot path. Institutions should confirm cohort provisioning, identity, retention, accessibility, support, and administrative requirements before representing a deployment as a complete managed campus lab. ## Begin with one bounded pilot [#begin-with-one-bounded-pilot] Choose one course module with a clear deliverable: 1. Define the learning outcome. 2. Freeze the starter environment. 3. Decide which agents and sources are allowed. 4. Specify what evidence students must submit. 5. Provision a small cohort. 6. Measure setup time, support requests, completion, and environment failures. 7. Interview students and faculty before scaling. IREX's higher-education readiness research reports that institutional foundations and governed pilots are lagging behind AI ambition. [Read the IREX report](https://www.irex.org/universityaireadiness). EDUCAUSE likewise frames AI adoption as a combined strategy, policy, workforce, privacy, and digital-divide issue. [Read the EDUCAUSE landscape study](https://library.educause.edu/resources/2025/2/2025-educause-ai-landscape-study). ## The lab should make good teaching easier [#the-lab-should-make-good-teaching-easier] Success is not the number of prompts sent. It is more time spent on learning, fewer environment failures, clearer evidence of student work, and a policy faculty can explain and enforce. When every participant starts with a working computer and every agent-assisted result remains inspectable, universities can teach the new workflow without surrendering academic control. [Explore the Matrix university solution](/solutions/university-ai-development-lab) or [plan a university pilot](/contact?audience=university). # Teaching with agents without losing academic control URL: /blog/university-teaching-with-agents-academic-control A governance framework for using AI agents in university teaching while protecting learning objectives, privacy, integrity, and faculty authority. Universities can teach with AI agents without losing academic control when they define the learning objective first, make permitted agent behavior explicit, protect institutional and student data, and assess the student's reasoning and verification—not merely the final output. The choice is not unrestricted adoption or a universal ban. Different assignments can permit different capabilities. ## Start with the learning objective [#start-with-the-learning-objective] Before choosing a tool, ask what the student must learn: * recall and explain foundational knowledge, * formulate a research question, * design an experiment, * write and debug code, * evaluate evidence, * make a professional judgment, * critique an agent's process or output. If the agent performs the exact cognitive work being assessed, change the permitted use or redesign the assessment. If directing and verifying an agent is itself the objective, require evidence of that process. ## Define levels of agent participation [#define-levels-of-agent-participation] | Level | Permitted use | Suitable evidence | | ------------- | ---------------------------------------------- | ------------------------------------------ | | No agent | Independent assessment | Supervised work or oral defense | | Assistive | Explanation, brainstorming, formatting | Disclosure and source verification | | Collaborative | Drafting, coding, analysis with student review | Session record, diffs, reflection | | Agent-native | Student designs and operates an agent workflow | Architecture, controls, tests, audit trail | Policies become easier to follow when an assignment states the level instead of relying on a vague institution-wide sentence. ## Keep academic responsibility with people [#keep-academic-responsibility-with-people] Students remain responsible for submitted claims, code, citations, and ethical choices. Faculty remain responsible for assessment design. Institutions remain responsible for approved tools, privacy, accessibility, retention, and support. An agent should not make disciplinary findings, infer misconduct from style, or become the sole basis for a high-impact academic decision. ## Protect data before connecting tools [#protect-data-before-connecting-tools] Classify the material an agent may access: * public course material, * licensed content, * student submissions, * unpublished research, * personal data, * restricted institutional records. Then define storage, provider, region, retention, sharing, and deletion rules. An available connector is not automatic authorization. ## Assess process through artifacts [#assess-process-through-artifacts] In an agent-native assignment, ask students to submit: * the task specification, * relevant prompts or instructions, * sources and context provided, * agent output or session evidence, * file diffs and tests, * errors found and corrections made, * a short explanation of decisions retained by the student. This creates a teachable record and makes evaluation less dependent on unreliable AI-detection guesses. ## Give faculty a controlled environment [#give-faculty-a-controlled-environment] A standardized cloud lab can define tools, starter repositories, compute, and network boundaries for a particular course. Matrix's [university AI development lab](/solutions/university-ai-development-lab) is designed around repeatable hosted environments accessible through browser and CLI. Technology does not supply the academic policy. Institutions should validate identity, privacy, accessibility, retention, faculty access, and administrative controls during a pilot. ## Use an iterative governance process [#use-an-iterative-governance-process] UNESCO reported in 2025 that nearly two-thirds of surveyed higher-education institutions either had AI guidance or were developing it, while confidence and implementation remained uneven. [Read the UNESCO survey](https://www.unesco.org/en/articles/unesco-survey-two-thirds-higher-education-institutions-have-or-are-developing-guidance-ai-use). IREX's more recent readiness research similarly identifies gaps between ambition, policy, governed pilots, and impact measurement. [Read the IREX report](https://www.irex.org/universityaireadiness). A practical governance cycle is: 1. Select a bounded course and learning objective. 2. Define permitted agent use and data boundaries. 3. Train faculty and students on the rules. 4. Run the pilot in a controlled environment. 5. Review incidents, learning evidence, access, and support. 6. Update the policy before expanding. ## Academic control means visible choices [#academic-control-means-visible-choices] The institution should be able to explain which agents are allowed, what they can access, what evidence students retain, who reviews exceptions, and how the environment is recovered or deleted. That is stronger than pretending agents are absent. It lets universities teach students how modern work is changing while keeping learning, privacy, and judgment at the center. [Read the university AI lab blueprint](/blog/university-ai-lab-in-a-box?preview=1) or [plan a Matrix university pilot](/contact?audience=university). # Your AI chief of staff needs a workspace, not a chat window URL: /blog/founders-ai-chief-of-staff-workspace What an AI chief of staff should prepare, remember, coordinate, and escalate—and why founders need a workspace with visible human control. An AI chief of staff should not be a chatbot with an executive title. It should be a durable workspace that helps a founder prepare decisions, maintain the operating rhythm, and turn commitments into visible follow-through. That means remembering why a decision was made, gathering evidence from connected tools, preparing drafts, tracking open loops, and asking for approval before consequential actions. The value is not a clever answer. It is fewer dropped handoffs between the answer and the work. Matrix is building toward that model: an [AI assistant with its own cloud computer](/solutions/professional-ai-assistant-cloud-computer), where files, apps, agent sessions, and connected tools can live together. This article describes the operating pattern. It does not claim that every workflow below is already automated end to end. The distinction matters because adoption is already ahead of operational maturity. High Alpha's 2025 founder research found that go-to-market execution remained a leading concern while AI strategy rose sharply, yet fewer than one-quarter of surveyed companies measured internal AI impact with KPIs or dashboards. An AI chief of staff should close that execution gap, not add another experiment. [See the 2025 SaaS Benchmarks](https://saasbenchmarks.highalpha.com/). ## What should an AI chief of staff actually do? [#what-should-an-ai-chief-of-staff-actually-do] A useful chief-of-staff workspace should handle five jobs: 1. **Prepare:** assemble the context for a meeting, decision, or review. 2. **Remember:** preserve decisions, owners, deadlines, and source material. 3. **Coordinate:** turn commitments into tasks and follow-ups. 4. **Draft:** prepare briefs, updates, messages, and reports for review. 5. **Escalate:** surface exceptions instead of hiding them in a summary. This is different from asking a general assistant to summarize one document. The workspace must survive across weeks, connect evidence to action, and make current state inspectable. ## Build around the founder's operating rhythm [#build-around-the-founders-operating-rhythm] Start with recurring moments rather than an open-ended promise to “automate the company.” A founder's week often contains a leadership review, customer calls, recruiting decisions, investor updates, product tradeoffs, and dozens of follow-ups. Each moment can become a bounded workflow: | Moment | Agent preparation | Human decision | | --------------- | ------------------------------------------------------------ | ------------------------------ | | Monday planning | Gather metrics, unresolved tasks, and calendar constraints | Set priorities and owners | | Customer call | Assemble account history, open issues, and prior commitments | Choose the agenda and position | | Hiring review | Organize evidence and outstanding questions | Make the hiring decision | | Investor update | Draft progress, risks, asks, and supporting numbers | Approve the narrative and send | | Friday review | Compare planned and completed work; flag open loops | Reset or close commitments | The agent does the retrieval and assembly. The founder keeps judgment, prioritization, and external commitments. ## Memory needs structure, not just a longer transcript [#memory-needs-structure-not-just-a-longer-transcript] Chat history is useful, but it is a weak company record. A durable workspace should distinguish: * source documents from generated summaries, * decisions from discussion, * commitments from suggestions, * current plans from superseded plans, * approved messages from unreviewed drafts. Matrix treats files and workspace records as durable context. The broader idea is developed in [building a company OS around the tools your team uses](/blog/company-os-ai-agents-series): the company should keep authoritative systems while the workspace connects them into repeatable work. ## Connected tools should preserve boundaries [#connected-tools-should-preserve-boundaries] Matrix currently documents connections for services including Gmail, Google Calendar, Google Drive, GitHub, Slack, and Discord. Its [integration guide](/docs/guide/integrations) recommends reviewing important actions and using drafts before sending when the outcome matters. That distinction is essential for founders. “Read my calendar” and “cancel a customer meeting” should not share the same approval posture. A good workspace makes the action, identity, destination, and evidence visible before it changes an external system. ## What should remain human? [#what-should-remain-human] The chief-of-staff metaphor becomes dangerous when it implies invisible authority. Keep people responsible for: * strategic priorities, * hiring and performance decisions, * financial commitments, * legal representations, * sensitive external communication, * exceptions where the source evidence conflicts. The agent should compress preparation, not accountability. ## A practical first workflow [#a-practical-first-workflow] Begin with a weekly founder briefing: 1. Define the authoritative sources. 2. Gather the week's decisions, metrics, meetings, and open tasks. 3. Link every material statement to a source. 4. Separate facts, inferred risks, and proposed actions. 5. Draft the briefing inside the workspace. 6. Let the founder correct it and assign next steps. 7. Record the approved decisions and owners. Measure missing inputs, corrections, time to review, and follow-ups completed. Do not claim leverage until the workflow produces reliable evidence. McKinsey's 2025 global survey found workflow redesign had the strongest relationship with reported EBIT impact among the organizational attributes it tested. That is a useful design principle even for a small company: measure the whole operating loop, not the speed of one generated summary. [Read the survey](https://www.mckinsey.com/capabilities/quantumblack/our-insights/the-state-of-ai-how-organizations-are-rewiring-to-capture-value). ## A 30-day readiness checklist [#a-30-day-readiness-checklist] Before giving an assistant more autonomy, verify that: * every recurring briefing names its authoritative sources, * facts, inferences, and proposed actions are labeled separately, * external messages remain drafts until an owner approves them, * failed or incomplete runs are visible, * decisions retain an owner, date, rationale, and review trigger, * one operating metric can show whether the workflow improved. NIST's generative-AI risk profile calls out governance, content provenance, testing, and incident disclosure as cross-cutting concerns. For a founder workflow, that translates into visible sources, review boundaries, and a recovery path—not a thick policy document. [Read the NIST profile](https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence). ## The test for a real AI workspace [#the-test-for-a-real-ai-workspace] After a month, ask four questions: * Does it know what the company decided and where the evidence lives? * Does it prepare recurring work without rebuilding context each time? * Can a teammate inspect and correct what it did? * Do consequential actions still have a clear human owner? If the answer is yes, the workspace is beginning to act like a chief of staff. If it only produces articulate replies, it is still a chat box. ## Frequently asked questions [#frequently-asked-questions] ### Is an AI chief of staff the same as an AI executive assistant? [#is-an-ai-chief-of-staff-the-same-as-an-ai-executive-assistant] They overlap, but the chief-of-staff pattern is broader. An executive assistant often focuses on scheduling, communication, and preparation. A chief-of-staff workspace also preserves decisions, coordinates cross-functional commitments, and supports recurring operating reviews. ### What should a founder automate first? [#what-should-a-founder-automate-first] Start with one frequent, reviewable loop such as a weekly founder briefing or customer-call preparation. Avoid starting with irreversible actions or a workflow whose inputs and owner are unclear. ### Should an AI chief of staff send messages automatically? [#should-an-ai-chief-of-staff-send-messages-automatically] Not by default. Begin with drafts and explicit approval for the recipient, claims, promises, and send action. Expand autonomy only after the workflow has a reliable track record and a clear recovery path. [Explore Matrix use cases](/use-cases) or [talk to Matrix about a team workflow](/contact?audience=team). # Build a company brain that remembers why URL: /blog/founders-company-brain-that-remembers A practical system for turning scattered decisions, files, and conversations into company memory that stays attributable, current, and useful. A company brain is not a database containing every message the company has ever produced. It is a working system that can answer three questions: what do we know, what did we decide, and what happens next? For founders, the gap between an idea and execution is usually not a lack of documents. It is broken continuity. Context lives across calls, inboxes, chat, project tools, drives, and individual memory. An AI workspace can help only if it preserves the authority of those sources and turns their context into reviewable work. ## What is a company brain? [#what-is-a-company-brain] A useful company brain has four layers: * **Sources:** documents, messages, repositories, calendars, and systems of record. * **Working memory:** active plans, drafts, research, and intermediate analysis. * **Decisions:** what was chosen, by whom, why, and with which evidence. * **Execution:** tasks, workflows, approvals, and completed artifacts. Most knowledge products concentrate on the first layer. Most automation products begin with the fourth. The missing middle is where teams interpret information and commit to a course of action. Matrix's company-OS direction connects these layers through a persistent workspace. [The company OS series](/blog/company-os-ai-agents-series) explains the broader architecture; this article focuses on how a founder can start small. This is primarily an information-design problem. McKinsey's 2025 AI survey found that agents were most commonly reported in IT and knowledge management, but nearly two-thirds of respondents said their organizations had not begun scaling AI across the enterprise. The gap between experimentation and dependable use makes provenance and lifecycle more important than collecting more content. [Read the survey](https://www.mckinsey.com/capabilities/quantumblack/our-insights/the-state-of-ai). ## Keep source systems authoritative [#keep-source-systems-authoritative] A company brain should not silently copy everything into a new, opaque store. Google Drive can remain authoritative for a proposal. GitHub can remain authoritative for code. A CRM can remain authoritative for pipeline stage. The workspace should retain links, identifiers, versions, and timestamps. Generated material should be visibly generated. When an agent says a customer requested a feature, a teammate should be able to open the supporting note or thread. This is why [working memory for AI agents](/blog/onedrive-google-drive-working-memory-ai-agents) should complement company storage rather than replace it. ## Turn decisions into durable objects [#turn-decisions-into-durable-objects] Founders repeat the same explanations because decisions are buried in meetings and chat. A decision record can be simple: | Field | Example | | -------------- | ---------------------------------------------------- | | Decision | Focus Q4 launch on engineering teams | | Owner | CEO | | Date | 4 September 2026 | | Evidence | Five customer calls, activation data, support themes | | Alternatives | General productivity, university-first launch | | Review trigger | New segment exceeds activation threshold | An agent can prepare the record and link evidence. A person approves the decision. Later work can reference the approved object instead of inferring strategy from a transcript. The extra word in this article's title—*why*—is the important one. A roadmap item without its rejected alternatives and supporting evidence is easy to misread six months later. Preserving rationale lets a new teammate or an agent distinguish a durable constraint from an old preference. ## Give memory a lifecycle [#give-memory-a-lifecycle] Company knowledge changes. Every durable item should have a lifecycle: 1. Captured from a named source. 2. Classified as fact, interpretation, decision, or draft. 3. Reviewed by an owner when necessary. 4. Used in a workflow with provenance intact. 5. Superseded or archived when it is no longer current. Without this lifecycle, “memory” becomes a pile of plausible but stale context. ## Connect memory to recurring work [#connect-memory-to-recurring-work] The company brain becomes valuable when it shortens a real loop: * customer call to product decision, * product decision to launch plan, * sales activity to forecast review, * meeting commitment to follow-up, * operating data to investor update. Matrix's [trigger-to-outcome model](/blog/trigger-to-outcome-matrix-agent-workflows) provides a useful pattern: define the trigger, gather evidence, prepare a draft, route approval, take the bounded action, and record the result. ## Start with one high-friction loop [#start-with-one-high-friction-loop] Choose a workflow that happens frequently and has clear evidence. A weekly customer-to-product review is a strong candidate: 1. Collect selected customer notes and open issues. 2. Group repeated problems without erasing dissent. 3. Link each theme to its sources. 4. Compare themes with the current roadmap. 5. Draft proposed decisions and open questions. 6. Let product owners approve or reject them. 7. Store the final decisions with review dates. Track how often claims lack evidence, how much reviewers correct, and whether decisions reach execution. High Alpha describes a shift from AI novelty toward operationalization: repeatable playbooks, end-to-end workflows, and measurable outcomes. [Its 2025 SaaS benchmarks](https://saasbenchmarks.highalpha.com/) support a simple conclusion: company memory matters when it compounds execution. ## What not to put in the company brain [#what-not-to-put-in-the-company-brain] More capture is not always better. Exclude or tightly control: * credentials and secrets that belong in a secrets manager, * personal or sensitive data without a defined business need, * duplicate copies that obscure the authoritative source, * generated claims that have not been checked, * obsolete plans without an explicit superseded state. NIST recommends governance across the generative-AI lifecycle, including provenance and differentiated human oversight. The practical takeaway is that memory needs access rules, ownership, and deletion—not only retrieval. [Read the NIST generative-AI profile](https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence). ## A company brain should make the company less dependent on recall [#a-company-brain-should-make-the-company-less-dependent-on-recall] The goal is not to remember everything forever. It is to keep important context available, current, attributable, and actionable. When a new teammate can understand why a priority exists, when an agent can prepare work from approved context, and when a founder can inspect the path from source to outcome, the company brain is doing its job. ## Frequently asked questions [#frequently-asked-questions] ### Is a company brain just a knowledge base? [#is-a-company-brain-just-a-knowledge-base] No. A knowledge base mainly stores and retrieves information. A company brain also records decisions and connects approved context to work, while leaving source systems authoritative. ### Does every company conversation need to be stored? [#does-every-company-conversation-need-to-be-stored] No. Capture information because it has a defined use, owner, retention rule, and access boundary. Storing everything creates privacy risk and makes current, authoritative knowledge harder to identify. ### How do you stop company memory from becoming stale? [#how-do-you-stop-company-memory-from-becoming-stale] Give important records an owner, timestamp, review trigger, and status such as current, superseded, or archived. Agents should flag uncertainty instead of treating old material as current fact. [See how Matrix approaches shared agent workspaces](/blog/shared-agent-workspaces-for-teams) or [explore the professional assistant workspace](/solutions/professional-ai-assistant-cloud-computer). # How a 10-person company gains leverage with AI agents URL: /blog/founders-operating-leverage-with-agents A grounded playbook for small teams using AI agents across GTM, reporting, research, follow-ups, and other recurring operating workflows. A 10-person company does not literally become a 50-person company by adopting agents—and it should not plan headcount from that slogan. It gains operating leverage when the same team can run more complete, reliable workflows without adding equivalent coordination overhead. Agents can help with research, preparation, reporting, follow-ups, and recurring work. They should not become an excuse to remove owners, skip review, or automate a broken process. The practical target is more throughput with the same accountability. That distinction matches the broader evidence. McKinsey's 2025 global survey found that 62% of respondents' organizations were at least experimenting with AI agents, while only 39% reported any enterprise-level EBIT impact from AI. The firms reporting the most value were much more likely to redesign workflows instead of adding AI to isolated tasks. [Read the survey](https://www.mckinsey.com/capabilities/quantumblack/our-insights/the-state-of-ai). ## Where do agents create operating leverage? [#where-do-agents-create-operating-leverage] Look for work with four properties: * it repeats, * its inputs are identifiable, * its output can be reviewed, * failure is visible and recoverable. Strong early candidates include account research, meeting preparation, weekly reporting, pipeline hygiene, customer-feedback synthesis, document assembly, and follow-up drafts. Weak candidates include ambiguous strategy, sensitive people decisions, unsupervised financial commitments, and communication where tone or authority cannot be delegated safely. ## Build loops, not isolated prompts [#build-loops-not-isolated-prompts] An end-to-end agent workflow has more structure than “write an update.” Consider a weekly GTM review: 1. Read selected CRM, calendar, and project inputs. 2. Identify missing or inconsistent records. 3. Assemble pipeline changes and customer themes. 4. Draft the operating update with source links. 5. Ask owners to resolve exceptions. 6. Publish the approved update. 7. Record decisions and next actions. The agent compresses gathering and preparation. Team members remain responsible for corrections and commitments. ## Five workflows for a small company [#five-workflows-for-a-small-company] ### 1. Customer and account preparation [#1-customer-and-account-preparation] Prepare a concise brief before each important call: company context, prior conversations, open issues, promises, and questions. Do not let the agent invent relationship history when a source is missing. ### 2. Follow-up discipline [#2-follow-up-discipline] Detect commitments and prepare follow-up drafts. Keep recipient selection, promises, pricing, and sending under human review. [Safe email agents](/blog/building-safe-email-agents) should earn autonomy gradually. ### 3. Company reporting [#3-company-reporting] Gather metrics and project changes into a consistent weekly format. Link numbers to the source and flag missing data instead of filling gaps with estimates. ### 4. Market and competitor monitoring [#4-market-and-competitor-monitoring] Run scheduled research against named sources, separate facts from interpretation, and retain the evidence behind each change. A founder should review the implications, not manually collect every update. ### 5. Reusable document production [#5-reusable-document-production] Assemble proposals, briefs, and updates from approved templates and sources. Keep generated drafts visibly separate from final versions. [Matrix's document workflow blueprint](/blog/automating-professional-services-documents) explains this pattern in detail. These workflows should not all launch at once. Pick the one with the clearest inputs, highest recurrence, and easiest review. A narrow workflow that runs every week is more useful than five impressive demos nobody trusts. ## Give every workflow an owner and a boundary [#give-every-workflow-an-owner-and-a-boundary] Use a simple control table: | Workflow | Agent may | Human must | | ---------------- | ------------------------------- | ---------------------------------------- | | Account brief | Read approved sources and draft | Verify sensitive claims | | Follow-up | Prepare a message | Approve recipient, promise, and send | | Weekly report | Aggregate and explain changes | Approve conclusions | | Research monitor | Collect and classify updates | Decide strategic response | | Proposal | Assemble approved material | Approve scope, price, and legal language | This makes delegation explicit. It also reveals where a process lacks an owner. ## The infrastructure matters [#the-infrastructure-matters] Recurring agents need a durable place to run, store working artifacts, and expose their state. Matrix provides an [always-on cloud computer for agents](/solutions/cloud-computer-for-ai-agents) with files, terminals, apps, sessions, and connected-tool paths. The device becomes an access surface; the work does not depend on a founder keeping a laptop awake. That does not make every workflow safe automatically. Credentials should be scoped, consequential actions reviewed, and recovery planned. ## Measure leverage without inventing ROI [#measure-leverage-without-inventing-roi] Do not begin with a headline such as “5x productivity.” Establish a baseline and measure: * time from trigger to first reviewable draft, * percentage of drafts accepted with minor edits, * missing-input and exception rate, * number of overdue commitments, * time spent on coordination, * throughput of completed, approved workflows. High Alpha's 2025 founder research says fewer than one-quarter of surveyed companies used KPIs or dashboards to measure internal AI impact; more than one-third still relied on informal team feedback. [Read the report](https://saasbenchmarks.highalpha.com/). The opportunity is real, but the evidence should come from your own operating data. Use a before-and-after scorecard for four weekly cycles: | Metric | Baseline | Agent-assisted target | | ------------------------------- | ---------: | ------------------------------: | | Time to first reviewable output | Measure it | Lower, without more corrections | | Missing or unsupported claims | Measure it | Trending down | | Human review time | Measure it | Lower, not zero | | Commitments completed on time | Measure it | Trending up | Avoid targets that reward volume alone. More messages, summaries, or drafts can increase coordination work rather than reduce it. ## Start with one complete workflow [#start-with-one-complete-workflow] Choose one weekly loop, define its sources and approval boundary, and run it manually with an agent for four cycles. Fix the missing data and ownership problems before adding automation. A small company gains leverage when agents make good operating habits cheaper to repeat. If they merely increase the volume of drafts, the company has more output—but not more capacity. ## Frequently asked questions [#frequently-asked-questions] ### Can AI agents really replace the work of dozens of employees? [#can-ai-agents-really-replace-the-work-of-dozens-of-employees] That is the wrong planning assumption. Agents can compress parts of repeatable workflows, but people still own judgment, relationships, exceptions, and consequential decisions. Measure workflow outcomes before translating time saved into staffing claims. ### Which AI-agent workflow should a startup build first? [#which-ai-agent-workflow-should-a-startup-build-first] Choose a high-frequency workflow with named inputs, a reviewable output, a clear owner, and recoverable failure. Weekly reporting or meeting preparation is usually safer than autonomous customer communication. ### How many agent workflows should a small team run? [#how-many-agent-workflows-should-a-small-team-run] Start with one and operate it for four cycles. Add another only when the first has stable inputs, visible exceptions, an owner, and evidence that it improves a business outcome. [Explore Matrix use cases](/use-cases) or [plan a team workflow with Matrix](/contact?audience=team). # OpenClaw 2 shows where AI agents are headed URL: /blog/openclaw-2-future-agent-workspaces OpenClaw 2 makes the browser and shared sessions central. Here is why that shift matters for persistent, collaborative agent computing. [OpenClaw 2](https://openclaw.ai/blog/openclaw-2-accidentally) began as an effort to simplify setup and rebuild the browser app. It grew into the project's largest release: a broader rethink of installation, memory, skills, automations, security, native apps, and shared cloud sessions. The interesting part is not the size of the release. It is the direction of travel. Agents are moving beyond private conversations. They are becoming durable places where work continues, context accumulates, and another person can join without starting over. OpenClaw is approaching that shift from the agent layer. Matrix OS approaches it from the computer and workspace layer. Together, they point toward the same larger idea: the useful unit of AI work is no longer a chat. It is a persistent, inspectable workspace shared by people and agents. ## What changed in OpenClaw 2? [#what-changed-in-openclaw-2] OpenClaw says the August 2026 release includes work from 933 contributors, including 569 first-time contributors, across more than 16,000 pull requests. The project initially focused on getting people to a useful Claw faster and making the browser a first-class experience. That cleanup eventually touched almost every part of the system. Three changes are especially relevant to the future of agent products: 1. **Setup starts with what the user already has.** OpenClaw can work with existing model subscriptions, API keys, and local models instead of forcing every user through the same provider-specific path. 2. **The browser becomes a primary surface.** People can configure the agent, return to ongoing work, and follow activity without treating the browser as a secondary dashboard. 3. **Cloud sessions become collaborative.** A person can bring a teammate into live work or hand it over while keeping the context intact. Those are product improvements, but they also reveal a change in the underlying mental model. ## The browser is becoming an access layer [#the-browser-is-becoming-an-access-layer] Early AI products treated the browser as the place where the intelligence lived. Close the tab and the interaction was effectively over. Persistent agents invert that relationship. The work lives somewhere else: in an agent runtime, a cloud session, or a remote computer. The browser becomes an access layer for inspecting and steering work that already exists. That distinction matters. A durable agent may be reading mail, updating a project, waiting for an approval, or coordinating with another person while no browser is open. When someone returns, the interface should reveal the current state rather than recreate it from a transcript. This is also the premise behind [agents needing a computer rather than another chat box](/blog/cloud-computer-for-agents). The screen is not the runtime. It is a window into the runtime. ## Shared context changes the collaboration model [#shared-context-changes-the-collaboration-model] OpenClaw describes shared cloud sessions as a way to make the product multiplayer. A teammate can join live work or take it over without discarding what the agent already knows. This solves a familiar problem. Most AI work is still trapped inside one person's session. Sharing usually means copying an answer, forwarding a transcript, or explaining the task again in another tool. The artifact moves, but the working context does not. A shared agent workspace needs more than simultaneous access. It needs: * durable project state, * a visible record of what the agent changed, * clear ownership when work changes hands, * permissions that survive beyond one prompt, * a way to pause, inspect, approve, or stop consequential actions. Collaboration is not simply adding another avatar to a chat. It is making the state of the work legible to everyone responsible for it. ## OpenClaw and Matrix OS operate at different layers [#openclaw-and-matrix-os-operate-at-different-layers] OpenClaw and Matrix OS should not be collapsed into the same product category. OpenClaw is an open-source personal AI assistant and agent platform. It connects models, channels, skills, automations, memory, and user workflows. OpenClaw 2 makes that agent easier to start, access through the browser, and share through cloud sessions. [Matrix OS](https://matrix-os.com) provides a persistent computer and workspace for agents. Repositories, terminals, files, apps, logs, and running services remain available independently of a local laptop. People can inspect the same durable environment in which terminal agents do their work. | Layer | OpenClaw 2 | Matrix OS | | -------------- | ---------------------------------------------------- | ---------------------------------------------------------------- | | Primary focus | Assistant, skills, channels, memory, and automations | Persistent computer, files, terminals, apps, and review surfaces | | Browser role | First-class agent experience | Window into a durable cloud computer | | Collaboration | Shared cloud agent sessions | Shared workspace state and inspectable artifacts | | Model approach | Supports multiple model and credential paths | Hosts the agent tools chosen for the computer | | Core question | What can this agent do for me or my team? | Where does agent work live, run, and remain inspectable? | The layers can be complementary in principle, but this article is not announcing an OpenClaw integration with Matrix OS. It is identifying a shared architectural direction. ## Simpler setup is an infrastructure feature [#simpler-setup-is-an-infrastructure-feature] OpenClaw's installation work is easy to describe as onboarding polish. It is more consequential than that. Every agent depends on models, credentials, tools, storage, permissions, and a place to run. If those pieces must be assembled before the first useful result, infrastructure becomes the product's adoption ceiling. Starting with subscriptions, keys, and models people already use reduces that burden. Moving optional configuration out of the critical path lets the agent become useful before it becomes elaborate. Matrix follows a related principle at the computer layer. The goal of a managed agent computer is not to hide that infrastructure exists. It is to make repositories, shells, routing, access, and persistence available without turning every agent experiment into a server-maintenance project. The best setup flow is not the one with the fewest visible controls. It is the one that reaches a safe, useful result quickly and reveals deeper controls when the workflow needs them. ## Ownership needs inspectability [#ownership-needs-inspectability] OpenClaw closes its announcement by connecting open source with ownership: users can shape the software around their lives rather than accept a fixed product designed elsewhere. Ownership also needs operational visibility. An agent that reaches across email, messages, files, and automations can have real consequences. People need to know what it accessed, what it changed, what remains active, and who can intervene. The more useful an agent becomes, the less acceptable a black-box session becomes. That is why persistent state and human control belong together. A durable workspace should leave artifacts behind: files, diffs, logs, messages, approvals, and task history. Those artifacts make delegation reviewable. For company workflows, this becomes a trust problem as much as a usability problem. Our article on [permissions, approvals, and audit for company AI agents](/blog/trust-layer-company-ai-agents) describes the controls required when agents move from suggestions to actions. ## What OpenClaw 2 signals for the category [#what-openclaw-2-signals-for-the-category] OpenClaw 2 suggests four broader product shifts: 1. **Agents will be model-flexible.** People will expect to use existing subscriptions, keys, and local models rather than reorganize around one provider. 2. **The browser will show ongoing work.** It will not necessarily host the process doing that work. 3. **Agent sessions will become multiplayer.** Context, ownership, and handoff will become product primitives. 4. **Infrastructure will recede without disappearing.** The runtime still matters, but users should not rebuild it for every useful workflow. The next generation of agent products will not be judged only by answer quality. They will be judged by how quickly they become useful, how safely they connect to real systems, how clearly people can inspect their work, and how gracefully that work moves between people. OpenClaw 2 is evidence that the market is moving in that direction. Matrix OS is building for the same destination from below: a persistent computer where agent work has somewhere durable to live. ## FAQs [#faqs] ### What is the main OpenClaw 2 update? [#what-is-the-main-openclaw-2-update] OpenClaw 2 is a broad platform release centered on simpler installation and a rebuilt browser experience. It also updates memory, skills, models, automations, security, native apps, plugins, and shared cloud sessions. See the [official announcement](https://openclaw.ai/blog/openclaw-2-accidentally) and [release notes](https://docs.openclaw.ai/releases/2026.8.1) for the complete list. ### Does OpenClaw 2 run on Matrix OS? [#does-openclaw-2-run-on-matrix-os] This article does not announce or document an OpenClaw integration with Matrix OS. It compares the architectural direction of the two products: OpenClaw at the assistant and agent layer, and Matrix at the persistent computer and workspace layer. ### Why do shared agent sessions matter? [#why-do-shared-agent-sessions-matter] They let another person join or take over work without rebuilding the context from a copied answer or transcript. Useful collaboration still requires visible state, permissions, ownership, and reviewable artifacts. ### Why is a browser experience important for persistent agents? [#why-is-a-browser-experience-important-for-persistent-agents] A browser makes ongoing agent work accessible from different devices. When the runtime is remote, closing the browser does not need to end the work; the browser becomes a surface for inspection and control. ### What is a persistent agent workspace? [#what-is-a-persistent-agent-workspace] It is an environment where project state, tools, artifacts, and running work remain available between human sessions. Persistence should be paired with Git checkpoints, logs, permissions, backups, and explicit human controls. # How to choose hosting for AI coding agents URL: /blog/ai-agent-hosting-guide Evaluate agent hosting by lifecycle, isolation, access, orchestration, recoverability, and cost instead of relying on a generic cloud-compute checklist. AI coding agents can run on a laptop, in a managed task sandbox, on a raw VPS, or inside a persistent workspace. Each option can execute code. The difference is what happens between commands, after a disconnect, and when several tasks need the same project state. Choose the operating model before comparing plan limits. A short-lived sandbox is useful for isolated jobs. A dedicated computer is useful when repositories, services, and tools should remain in place. A managed coding agent is useful when you want the vendor to own both the agent and its runtime. ## Start with the workload lifecycle [#start-with-the-workload-lifecycle] Ask how work begins and ends: * Does an API create a fresh environment for every task? * Should the environment pause and resume? * Will a developer return to the same repository tomorrow? * Must an agent wait for human approval without losing state? * Do background services need to remain available between tasks? These questions separate job sandboxes from durable development computers. Neither model is universally better. ## Check the isolation boundary [#check-the-isolation-boundary] "Isolated" can describe a container, microVM, virtual machine, dedicated server, or a set of application permissions. Find the actual boundary and decide whether it matches the data involved. For private repositories, review: * which party operates the host, * where source code and logs are stored, * how outbound network access is controlled, * how secrets reach the agent, * whether storage is encrypted and backed up, * how access is revoked and audited. An agent should receive the minimum permissions required for its task. Hosting does not replace repository protections or deployment approvals. ## Separate uptime from recoverability [#separate-uptime-from-recoverability] A remote computer continues running when a laptop sleeps or changes networks. That improves uptime, but it does not make a process immortal. Hosts restart, commands fail, disks fill, and agents make mistakes. Reliable agent hosting still needs: * Git commits or patches as checkpoints, * one branch and worktree per agent, * process supervision for services and scheduled jobs, * logs that remain available after failure, * backups for state not already stored in Git, * an explicit stop and recovery procedure. Treat "persistent" as a lifecycle property, not a guarantee that every process survives every failure. ## Decide how people will inspect the work [#decide-how-people-will-inspect-the-work] Background work needs a review surface. A terminal alone may be enough for one developer, but teams usually need branches, diffs, test results, logs, and ownership. Useful questions include: * Can a reviewer see the exact files and commands used? * Can the agent open a draft pull request? * Can a person pause or stop a run? * Are approvals required before pushing, deploying, or sending messages? * Can the team tell which agent owns each branch and process? The best hosting platform is often the one that makes incomplete work easy to inspect. ## Compare the main hosting models [#compare-the-main-hosting-models] | Model | Best for | What you operate | | -------------------------- | ------------------------------------- | ------------------------------------------- | | Local laptop | Short interactive tasks | The whole environment | | API sandbox | Disposable isolated jobs | Task lifecycle and integration | | Raw VPS | Maximum infrastructure control | Security, updates, access, backups, tooling | | Managed coding agent | Delegated tasks in one product | Repository permissions and review policy | | Persistent agent workspace | Repeated work across tools and agents | Project workflow and agent permissions | [Matrix OS](https://matrix-os.com) uses the last model. Matrix Cloud provides a persistent computer with browser and terminal access; self-hosting is available when a team wants to operate the server. Terminal agents can use the same durable project environment while remaining isolated through Git worktrees. ## Evaluate cost with a representative week [#evaluate-cost-with-a-representative-week] Do not compare only the advertised unit price. Model the actual number of environments, active hours, retained storage, network usage, and concurrent agents. Include the engineering time required to secure and maintain the setup. Usage billing can be efficient for bursty tasks. A fixed-price computer can be easier to predict for continuous work. The cheaper model depends on utilization. ## A practical selection process [#a-practical-selection-process] Test each candidate with the same real task: 1. Prepare a private repository and scoped credentials. 2. Run a multi-step change with tests. 3. Disconnect and reconnect during the run. 4. Introduce a failure and test recovery. 5. Inspect the final diff, logs, and permission trail. 6. Measure setup time and total cost. The result should be a reviewable artifact, not merely a completed agent transcript. Use the selection process above during evaluation. For the managed-versus-self-operated decision, compare [Matrix OS with a raw VPS](/blog/matrix-os-vs-vps). ## FAQs [#faqs] ### Does AI-agent hosting need a dedicated server? [#does-ai-agent-hosting-need-a-dedicated-server] No. Disposable sandboxes and managed agent runtimes are often better for isolated tasks. A dedicated or persistent computer becomes useful when project state and services should remain available across many tasks. ### Can several agents use the same computer? [#can-several-agents-use-the-same-computer] Yes, but give each agent a separate Git worktree, branch, ports, and task ownership. Shared compute should not mean a shared working directory. ### Is a VPS enough? [#is-a-vps-enough] A VPS supplies compute and uptime. It can be enough if your team is prepared to own authentication, patching, backups, terminals, routing, observability, and agent coordination. # AI-powered DevOps without handing agents the keys URL: /blog/ai-powered-devops-coding-agents Use coding agents for test triage, deploy preparation, and rollback analysis while keeping production changes behind explicit controls. Coding agents are useful in DevOps when they gather evidence, prepare changes, and explain failures. They become risky when a vague prompt can cross directly into production. A practical design keeps agents inside a controlled loop: observe, propose, verify, request approval, and execute only the actions explicitly allowed by policy. ## Which DevOps tasks fit coding agents? [#which-devops-tasks-fit-coding-agents] Start with work that is reversible and easy to verify. ### Test failure triage [#test-failure-triage] An agent can collect failed jobs, read logs, map failures to recent commits, reproduce the issue in an isolated environment, and prepare a candidate fix. The output should be a branch with tests and a short explanation of uncertainty. This removes the first hour of investigation without pretending every failure has an automatic solution. ### Deployment preparation [#deployment-preparation] Agents can assemble release notes, check migration files, compare configuration, run smoke-test plans, and verify that required approvals exist. Let the agent prepare the deploy; let the delivery system enforce whether it may proceed. ### Rollback analysis [#rollback-analysis] Rollback execution is often deterministic, but the decision is consequential. An agent can identify the last known-good release, summarize affected changes, validate the rollback command in staging, and present the evidence to an operator. Automating the evidence is safer than automating the judgment by default. ## Design the workflow around authority [#design-the-workflow-around-authority] For each step, write down: | Step | Agent may | Agent may not | | -------- | ------------------------------------- | -------------------------------- | | Observe | Read approved logs and metrics | Browse unrelated customer data | | Diagnose | Run tests in an isolated environment | Change production state | | Propose | Open a branch or draft PR | Merge to a protected branch | | Verify | Run documented checks | Redefine the acceptance criteria | | Execute | Trigger pre-approved low-risk actions | Bypass deployment approvals | The boundary should be enforced by credentials and platform policy, not only written in the prompt. ## Use event-driven jobs, not an endless autonomous loop [#use-event-driven-jobs-not-an-endless-autonomous-loop] Most operational automation should start from a clear event: a failed CI run, a Sentry issue, a release candidate, or an operator request. Give the job a bounded objective, time limit, permitted tools, and expected artifact. An always-running agent with broad production access is hard to reason about. A queue of bounded jobs is easier to audit, retry, and stop. ## Keep environments separate [#keep-environments-separate] Investigation and remediation should happen away from production. A useful topology is: 1. An event creates a task with links to relevant evidence. 2. The agent receives a separate Git worktree and branch. 3. Tests run against an isolated database or staging environment. 4. The agent opens a draft pull request. 5. CI reruns checks independently. 6. A person approves the merge or deployment. If several agents participate, give each one a distinct responsibility. One can diagnose, another can review the proposed diff, and deterministic CI remains the final verifier. ## Make rollback a product feature [#make-rollback-a-product-feature] Before an agent can touch a deployment workflow, the team should know how to reverse it. Record the previous artifact, database compatibility, feature-flag state, and rollback command. Test the path in staging. Some changes are not safely reversible. A destructive data migration, external notification, or irreversible API call should require stronger controls than a stateless service deploy. ## Where persistent compute helps [#where-persistent-compute-helps] Some investigations outlive a laptop session: large test suites, multi-service reproductions, or an agent waiting for CI. A remote computer can keep those processes available while the operator disconnects. [Matrix OS](https://matrix-os.com) provides a persistent workspace for terminal agents, repositories, logs, and dev services. That can make long investigations easier to resume. It does not replace CI, branch protection, deployment policy, or incident command. ## What to measure [#what-to-measure] Track whether the workflow improves operations: * time from alert to useful diagnosis, * percentage of agent proposals accepted without major revision, * false-positive and abandoned-run rates, * human time spent reviewing, * rollback frequency and recovery time, * permissions or policies the agent attempted to exceed. The goal is not the maximum number of automated actions. It is shorter recovery with a clear chain of responsibility. For implementation patterns, see [How to run parallel AI-agent pipelines](/blog/run-claude-code-and-codex-in-parallel) and [Permissions, approvals, and audit for company AI agents](/blog/trust-layer-company-ai-agents). ## FAQs [#faqs] ### Should an agent deploy directly to production? [#should-an-agent-deploy-directly-to-production] Only for narrow, pre-approved actions with strong safeguards. Most teams should begin with agents preparing changes and evidence while existing systems enforce approval and deployment. ### Can an agent decide to roll back? [#can-an-agent-decide-to-roll-back] It can recommend a rollback and prepare the procedure. Automatic execution should depend on predefined signals, tested runbooks, and the risk of the specific service. ### Does this replace an on-call engineer? [#does-this-replace-an-on-call-engineer] No. Agents can reduce investigation and coordination work. People remain responsible for ambiguous decisions, customer impact, and changes with a large blast radius. # How to run Claude Code headlessly URL: /blog/claude-code-headless Use Claude Code in scripts and CI with explicit permissions, structured output, bounded tasks, and a remote runtime when local uptime is not enough. Claude Code can run non-interactively for bounded jobs such as repository analysis, release-note drafting, test triage, and code changes that will be reviewed through Git. Headless execution means there is no person answering prompts during the run. It does not mean unlimited autonomy, persistent memory, or automatic safety. The command still runs on a host, under credentials and permissions that you control. ## Start with a bounded command [#start-with-a-bounded-command] Claude Code supports non-interactive execution through its print mode. A minimal pattern is: ```bash claude --print "Inspect the failing tests in packages/api. Explain the likely cause. Do not edit files." ``` Check [Anthropic's Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/overview) before scripting flags, output formats, or permission settings because the interface evolves. Begin read-only. Once the job reliably produces useful output, allow a narrowly scoped write task in a disposable branch or worktree. ## Define the output contract [#define-the-output-contract] An automation should produce something another system can evaluate. Ask for structured output when a machine will consume the result, or write a stable Markdown artifact when a person will review it. A useful task definition includes: * the repository path and allowed files, * the objective and acceptance criteria, * commands the agent may run, * actions it must not take, * a time or iteration limit, * the required final artifact. For a code change, the artifact should normally be a diff plus test results, not only a prose answer. ## Run each job in an isolated worktree [#run-each-job-in-an-isolated-worktree] Do not point concurrent jobs at the same checkout. Create one worktree and branch per task: ```bash git fetch origin git worktree add ../app-agent-142 -b agent/issue-142 origin/main cd ../app-agent-142 claude --print "Fix issue 142 using the acceptance criteria in the issue. Run the focused tests." ``` The worktree prevents agents from mixing file changes, indexes, generated output, and package locks. Use separate ports and databases when jobs run services. ## Treat permissions as part of the program [#treat-permissions-as-part-of-the-program] Non-interactive jobs cannot pause for every ambiguous decision. Configure permissions so the safe path is also the available path. Avoid broad production credentials. Prefer a repository token that can push only the task branch, read-only access to logs, and short-lived credentials for external tools. Keep deployment, merge, and destructive database operations behind separate approval gates. ## Decide where the process should run [#decide-where-the-process-should-run] For CI jobs, use the CI runner and its normal timeout, artifacts, and credential controls. For a scheduled job, use a service or computer with process supervision. For long exploratory work, a persistent remote computer can keep the repository and tools available after the laptop disconnects. [Matrix OS](https://matrix-os.com) can host Claude Code on a persistent cloud computer with browser and terminal access. The remote host removes the laptop from the runtime path, but Git checkpoints, logs, timeouts, and recovery procedures still matter. ## Keep context in durable artifacts [#keep-context-in-durable-artifacts] Do not depend on an earlier conversation being available. Store task context in the issue, repository instructions, plan, or input file. Store progress in commits, notes, and test output. If a job must resume, give it the original goal plus the durable artifacts from the previous run. This is easier to audit than relying on hidden conversational memory. ## Use headless Claude Code in CI carefully [#use-headless-claude-code-in-ci-carefully] A safe first CI use is review-only: summarize a diff, identify missing tests, or compare changes with repository guidance. Keep the result advisory until the team understands false positives and cost. If the job writes code, run it in a separate workflow with a bot branch. Do not let generated changes bypass the same tests and human review required for human-authored code. This article focuses on non-interactive automation. For remote runtime setup, see [How to run Claude Code in the cloud](/blog/claude-code-cloud); for unattended work, see [How to run Claude Code overnight safely](/blog/run-claude-code-overnight-safely). ## FAQs [#faqs] ### Does headless Claude Code keep running after a laptop closes? [#does-headless-claude-code-keep-running-after-a-laptop-closes] Only if the command runs somewhere other than the sleeping laptop. Headless describes the interface, not the location or uptime of the host. ### Is headless mode the same as a background agent? [#is-headless-mode-the-same-as-a-background-agent] Not necessarily. A headless CLI process is something you operate. A managed background agent usually includes a provider-owned runtime, task lifecycle, and review interface. ### Can headless Claude Code modify code? [#can-headless-claude-code-modify-code] Yes, when its configured permissions allow it. Use an isolated branch and require normal tests and review before merging. # Claude Code vs Devin: control or managed delegation? URL: /blog/claude-code-vs-devin Compare Claude Code and Devin by runtime ownership, customization, review workflow, task shape, and operational responsibility. Claude Code and Devin can both take a software task, inspect a repository, change code, run commands, and return work for review. The central difference is who owns the environment and workflow around the agent. Claude Code is an agent you can run in a terminal on infrastructure you choose. Devin is a managed software-engineering agent with its own workspace and task experience. Choose between them by deciding how much runtime control you need and how much operating work you want the vendor to absorb. ## What does Claude Code give you? [#what-does-claude-code-give-you] Claude Code is terminal-first. It runs against the files and tools available on its host, whether that is a laptop, CI runner, VPS, or persistent development computer. That makes the environment highly adaptable. A team can install private CLIs, use existing repository scripts, choose network policy, and integrate the agent with its normal terminal workflow. The same flexibility creates responsibility. The team owns the host, credentials, process lifecycle, repository isolation, and review conventions unless it chooses an additional managed environment. ## What does Devin give you? [#what-does-devin-give-you] Devin packages the agent with a managed workspace and delegation workflow. A user assigns a task, provides access to the repository and relevant tools, and reviews progress and artifacts through Devin's product. Devin now also documents Terminal, Windsurf, schedules, playbooks, Slack, Linear, and MCP capabilities, so it should not be reduced to a closed web-only task box. That is attractive when the team wants a higher-level handoff and does not want to assemble a runtime for the agent. The tradeoff is that customization, environment behavior, and supported integrations follow the managed platform. Capabilities and pricing change quickly for both products. At this update, Devin documents Free, Pro, Max, and Teams self-serve plans with quotas and on-demand credits. Verify current details in [Anthropic's Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/overview) and [Devin's billing documentation](https://docs.devin.ai/admin/billing/self-serve) before making a procurement decision. ## Claude Code and Devin compared [#claude-code-and-devin-compared] | Question | Claude Code | Devin | | ---------------------- | ----------------------------------------------------- | ----------------------------------------- | | Primary interface | Terminal-first agent with integrations | Managed task and workspace product | | Runtime | Local, remote, CI, or another supported host | Cognition-managed environment | | Infrastructure control | High when self-operated | Abstracted behind the product | | Setup | You prepare the environment | Vendor prepares the workspace | | Custom tooling | Anything supported by your host and policy | Tools and integrations supported by Devin | | Review boundary | Whatever Git and CI workflow you define | Devin's workflow plus repository review | | Pricing unit | Claude subscription or API usage, plus chosen compute | Plan quota plus on-demand credits | | Best fit | Teams that want control and composability | Teams that want managed task delegation | ## When should you choose Claude Code? [#when-should-you-choose-claude-code] Choose Claude Code when the repository depends on a specialized local toolchain, private network, self-hosted service, or detailed permission model. It also fits developers who want to work interactively in a shell and decide how the agent is orchestrated. For long-running work, place it on a remote host rather than assuming the local laptop will remain awake. Claude Code can continue or resume recorded conversations, but that does not keep a terminated process executing. Use one worktree per task and checkpoint changes through Git. [Review Claude Code's resume controls](https://docs.anthropic.com/en/docs/claude-code/cli-usage). [Matrix OS](https://matrix-os.com) is one way to provide that persistent host. It gives terminal agents a durable computer with browser and terminal access while leaving agent choice and repository workflow with the team. ## When should you choose Devin? [#when-should-you-choose-devin] Choose Devin when you want the task, agent, runtime, and progress surface packaged together. It can be the shorter path for well-scoped backlog work when the repository and required services fit the managed environment. Before granting access, test private dependencies, network requirements, secrets, branch protections, and the quality of the returned pull requests on a representative task. ## Consider the hybrid option [#consider-the-hybrid-option] A team does not have to standardize on one agent. Managed agents can handle suitable independent tasks while Claude Code works inside a team-controlled environment for tasks that require private tooling or close supervision. The shared contract should be Git: * one branch per task, * documented acceptance criteria, * automated tests, * a human review before merge, * no direct production access by default. This keeps the review process consistent even when the execution environments differ. For the infrastructure side of the decision, see [How to choose hosting for AI coding agents](/blog/ai-agent-hosting-guide) and [How to run Claude Code in the cloud](/blog/claude-code-cloud). ## FAQs [#faqs] ### Is Devin simply hosted Claude Code? [#is-devin-simply-hosted-claude-code] No. They are different products from different companies with different agents, runtime models, interfaces, and workflows. ### Which is better for private infrastructure? [#which-is-better-for-private-infrastructure] Claude Code on a team-controlled host usually offers more direct environment and network control. Devin may still fit when its current enterprise controls and integrations meet the team's requirements. ### Which is easier to start with? [#which-is-easier-to-start-with] Devin reduces infrastructure setup by packaging the runtime. Claude Code is straightforward for terminal users but leaves the host and workflow choices to the team. ### How should teams compare price? [#how-should-teams-compare-price] Use a representative task set. Include Devin plan quota and on-demand credits on one side; include the Claude plan or API usage, compute, and operator time on the other. A subscription headline alone does not measure cost per accepted pull request. ### Can both open pull requests? [#can-both-open-pull-requests] Both can participate in pull-request workflows when repository permissions and integrations are configured. Protect the default branch and review generated changes normally. # How to run Codex headlessly on a remote computer URL: /blog/codex-headless-remote-machine Run Codex CLI without depending on a local laptop by using a remote host, scoped credentials, Git worktrees, checkpoints, and process supervision. Codex CLI can run on a remote computer just as it runs in a local terminal. The remote host supplies the filesystem, tools, and uptime; your laptop becomes a client used to start, inspect, and review the work. "Headless" describes a workflow without a continuously attended graphical interface. It does not remove the need for authentication, approvals, a durable output, or a machine that stays available. ## Choose the remote-host model [#choose-the-remote-host-model] There are three common ways to run Codex away from a laptop: * a CI runner for bounded automated jobs, * a raw VPS that your team configures and maintains, * a managed persistent computer with browser or terminal access. Use CI when the task belongs inside a repeatable pipeline. Use a VPS when you want maximum infrastructure control. Use a persistent development computer when people and agents should return to the same project environment across tasks. OpenAI also offers managed Codex workflows. Compare those with a self-operated CLI based on whether you want OpenAI or your team to own the execution environment. ## Prepare the host [#prepare-the-host] Install Git, the repository's language runtimes, build dependencies, and Codex CLI using the [current OpenAI Codex documentation](https://developers.openai.com/codex/cli/). Create a non-root developer user and restrict inbound access. Authenticate through a supported method. Do not copy browser cookies or unrelated personal credentials to the server. Use scoped repository access and short-lived tokens where possible. Clone the repository and confirm that a normal human workflow succeeds before adding the agent: ```bash git clone cd corepack pnpm install --frozen-lockfile corepack pnpm test ``` Replace the commands with the project's documented setup. ## Give every task a worktree [#give-every-task-a-worktree] Create an isolated checkout rather than allowing Codex to edit the shared main working directory: ```bash git fetch origin git worktree add ../app-codex-142 -b agent/codex-142 origin/main cd ../app-codex-142 codex ``` State the objective, allowed scope, acceptance criteria, and required verification. Ask Codex to stop and report when it needs authority outside that boundary. ## Keep the process available [#keep-the-process-available] If you start Codex through SSH, use a persistent terminal or the host's supported session manager. `tmux` keeps a remote shell alive when the SSH connection drops: ```bash tmux new -s codex-142 codex ``` Detach and reconnect later with `tmux attach -t codex-142`. This protects against a client disconnect. It does not automatically recover the process after a host reboot or application failure. Use Git checkpoints and process supervision when automatic recovery is required. ## Review the result through Git [#review-the-result-through-git] Before pushing, inspect the diff and rerun the relevant checks. The ideal handoff contains: * a narrowly scoped branch, * an explanation of the change, * tests and their output, * known limitations or follow-up work, * no unrelated formatting or dependency churn. Push the branch and open a draft pull request. Keep merge rights and deployment credentials separate from the agent unless the workflow has an explicit reason to grant them. ## Use Matrix OS as the remote computer [#use-matrix-os-as-the-remote-computer] [Matrix OS](https://matrix-os.com) provides a persistent cloud computer with browser and terminal access. Codex CLI can run alongside other terminal agents and project services, with separate Git worktrees used to keep tasks isolated. Matrix removes the laptop from the runtime path and manages more of the computer setup than a raw VPS. It does not replace branch protection, backups, agent permissions, or review. For local lifecycle details, see [How to keep Codex CLI running after you close your laptop](/blog/keep-codex-running). For parallel work, see [How to run Claude Code and Codex in parallel](/blog/run-claude-code-and-codex-in-parallel). ## FAQs [#faqs] ### Does Codex CLI require a graphical interface? [#does-codex-cli-require-a-graphical-interface] No. It is terminal-native. The exact modes and automation flags depend on the current Codex CLI, so use OpenAI's official documentation when scripting it. ### Will Codex continue if my laptop disconnects? [#will-codex-continue-if-my-laptop-disconnects] Yes, if Codex runs on a remote computer and the remote process remains active. A disconnect only removes your view of that process. ### Will `tmux` recover Codex after a server reboot? [#will-tmux-recover-codex-after-a-server-reboot] No. `tmux` helps with terminal disconnections, not full host restarts. Preserve work in Git and configure appropriate process supervision if the job must restart automatically. ### Can Codex and Claude Code share one remote machine? [#can-codex-and-claude-code-share-one-remote-machine] Yes. Give each agent a separate worktree, branch, ports, and task. Merge through a normal review queue rather than letting both edit the same checkout. # Remote development environments for AI teams URL: /blog/remote-dev-environment-for-ai-teams Design remote development environments for coding agents with durable state, parallel isolation, observability, and human control. Remote dev environment for AI teams The classic remote dev environment was built for humans. A cloud machine with a terminal, maybe a code server, shared access over SSH. The developer connects, types, and disconnects. The environment waits. That model breaks the moment agents enter the picture. Agents don't type and disconnect. They run for hours. They open files, execute tests, push commits, and wait on CI. They pick up new tasks while you sleep. The environment they need isn't a workspace you visit — it's a machine that runs whether you're there or not. Here's what actually changes when your team shifts from writing code to directing agents that write code, and what your infrastructure needs to support that shift. ## The Human-Centric Assumptions Baked Into Most Dev Environments [#the-human-centric-assumptions-baked-into-most-dev-environments] Most remote dev environments were designed around one workflow: a developer opens a connection, does work, closes the connection. The environment is a tool you pick up and put down. That assumption shows up everywhere. Session timeouts. Idle shutdown policies. Billing models that charge only for active hours. Workspace templates that spin up fresh on each connection. None of these are bugs. They're the right design for human developers who take breaks, switch tasks, and go home at the end of the day. Agents don't go home. They run until the task is done — or until the environment stops them. When the environment is designed to stop, the agent stops with it. ## What Agents Actually Need From an Environment [#what-agents-actually-need-from-an-environment] ### Persistent sessions [#persistent-sessions] An agent running a test suite, waiting on a build, or iterating through a refactor needs a runtime long enough for that bounded task and a way to checkpoint progress before the runtime ends. For recurring project work, a retained environment reduces setup and makes it easier to resume. For isolated jobs, a time-bounded sandbox may be safer and more economical. Match the lifecycle to the task. ### Stable file state [#stable-file-state] Agents read and write files. They check out branches, modify source, run linters, and commit changes. If the environment resets between sessions, the agent loses its working state — and you lose the work. Ephemeral sandboxes are useful for isolated testing. They're the wrong tool for an agent carrying state across a multi-hour task. You need a real persistent filesystem, not a container that evaporates. ### Tool access that survives disconnects [#tool-access-that-survives-disconnects] Agents connect to external services — GitHub for PRs, Linear for issue context, Sentry for error traces, Slack for notifications. Those connections need to stay live even when no human is actively watching. If the environment only maintains external connections while a user session is open, the agent loses its integrations the moment you close your laptop. That's not a remote dev environment for agents. It's a remote dev environment for humans that happens to run an agent occasionally. ### The ability to run multiple agents in parallel [#the-ability-to-run-multiple-agents-in-parallel] A team directing agents doesn't run one at a time. You assign one agent to a Sentry bug, another to a feature branch, another to a documentation update. They run concurrently on separate tasks, and you review the output. That means isolated sessions for each agent, with enough compute to support parallel workloads. A single shared terminal doesn't cut it. ## How the Developer's Role Changes [#how-the-developers-role-changes] When agents do the coding, the developer's job shifts from writing to directing and reviewing. You write the task description. The agent writes the code. You review the diff, approve the PR, or redirect with a follow-up prompt. The cycle is task-in, reviewed-change-out. That changes what you need from your environment moment to moment. You're not typing in a terminal for hours — you're checking in, reviewing output, and queuing the next task. Maybe from a laptop, maybe from a phone, maybe between meetings. The environment needs to support that pattern. Accessible from any browser, agent status visible at a glance, diffs reviewable without a full development setup on whatever device you happen to have open. ## What a Purpose-Built Environment for Agent Teams Looks Like [#what-a-purpose-built-environment-for-agent-teams-looks-like] The requirements above point to a specific kind of infrastructure. Not a sandbox. Not a traditional cloud IDE. A persistent cloud computer that runs agents in the background, stays connected to your tools, and lets you check in from anywhere. [Matrix OS](https://matrix-os.com) is built around this model. Each cloud plan provisions a dedicated computer. Its processes are independent of laptop sleep and local network disconnects, and the filesystem remains available between connections. Restarts and failures still require normal recovery practices such as Git checkpoints and process supervision. See [current Matrix plans and resources](/#pricing) and the terms displayed at checkout. Choose the computer lifecycle and capacity required by your workload; agent-provider access can have separate costs. You bring your own terminal agents. Claude Code, Codex CLI, OpenCode, Gemini CLI, and Pi can run in separate sessions and Git worktrees on the same persistent computer. Cursor Background Agents use Cursor's managed environment rather than the Matrix host. The web shell at app.matrix-os.com gives you terminals, a file manager, previews, and agent sessions from any browser. The Matrix CLI lets you attach to any running session from any terminal, across disconnects. Your devices are just viewers. The work lives in the cloud. For a deeper look at the underlying model, the article on [what it means to run a cloud computer for agents](/blog/cloud-computer-for-agents) covers the architecture in detail. ## Orchestration: Running Multiple Agents Without Losing Track [#orchestration-running-multiple-agents-without-losing-track] Parallel agents create a coordination problem. Which agent is working on what? Which tasks are queued? Which PRs are ready for review? Without orchestration, you end up checking five different terminal windows and losing track of what each agent was doing. That's not a workflow — it's chaos with extra steps. Matrix OS includes Symphony, which handles parallel task queues, tracks agent status, manages branch and diff review, and supports human-in-the-loop handoff. You see what each agent is doing, queue follow-up tasks, and review output in one place. The Hermes resident agent handles scheduled workflows and maintains live connections to GitHub, Linear, Slack, Gmail, Google Calendar, Google Drive, Sentry, and Datadog. Agents that fix bugs from Linear tickets, triage Sentry errors, or draft release notes from commit history aren't hypothetical — they run on Hermes. This is what separates an agent-ready remote dev environment from a cloud machine with a terminal. The orchestration layer is what makes parallel agent work manageable at the team level. ## The Workspace Design Question [#the-workspace-design-question] One thing that changes less obviously is how you think about workspace design. Human developers benefit from a setup that mirrors their local environment — familiar tools, familiar layout, familiar shortcuts. Agents don't care about the layout. They care about what's installed, what's accessible, and what state the filesystem is in when they start a task. That shifts workspace design toward environment reproducibility and tool availability. What dependencies are installed? What credentials are available? What branches are checked out? The [canvas-first workspace model](/technical) explores how the visual layer of a workspace changes when agents are the primary actors. ## Common Mistakes When Teams First Move to Agent-Driven Development [#common-mistakes-when-teams-first-move-to-agent-driven-development] **Using ephemeral sandboxes for long-running tasks.** Sandboxes work well for isolated, time-bounded work. They don't work for agents that need to run overnight or across multiple hours. The session ceiling will kill the task. **Running agents on a local machine.** Your laptop isn't always on. It sleeps, reboots, loses network. Any agent running locally stops when the machine does. The guide on [keeping Claude Code running after your laptop closes](/blog/keep-claude-code-running-after-laptop-closes) covers why this matters and how to fix it. **Treating agent output as final without review.** Agents produce good output, but they're not infallible. The workflow needs a review step. Human-in-the-loop handoff isn't optional — build it into your task queue from the start. **Running all agents in one session.** Isolated sessions matter. If one agent's work corrupts the environment, you don't want it taking down every other running task. Separate sessions with separate state is the right default. ## What Your Team Gains [#what-your-team-gains] When the environment is right, the workflow changes substantially. You queue tasks before you go to sleep and review output in the morning. You run three agents in parallel on separate branches and merge the best result. You get a Slack notification when an agent opens a PR, review it on your phone, and approve it without opening your laptop. The work doesn't stop when you stop. That's the actual shift. *** ## FAQs [#faqs] **What makes a remote dev environment suitable for AI agents vs. human developers?** Long-running agents need a runtime long enough for the task, stable project state, reliable tool access, and enough compute for the intended concurrency. Retained computers and time-bounded sandboxes can both work when their lifecycle matches the job. **Can I use Claude Code, Codex, and Cursor on the same remote environment?** Yes. Matrix OS runs Claude Code, Codex, Cursor, OpenCode, Gemini CLI, and Pi in isolated sessions on the same persistent machine. You bring your existing agents and point them at the environment — no switching required. **What happens to a running agent if I close my laptop?** On a persistent cloud environment like Matrix OS, a laptop sleep or local disconnect does not stop the remote computer. The agent can keep running, and the laptop acts as a client when you reconnect. A reboot of the remote host is different and should be handled with normal recovery controls. **How do teams manage multiple agents running in parallel without losing track?** Orchestration tooling handles this. Matrix OS includes Symphony for parallel task queues, agent status tracking, branch and diff review, and human-in-the-loop handoff. You see what each agent is doing and queue follow-up tasks from one interface. **Are ephemeral sandboxes a viable option for agent teams?** Yes, for isolated work that fits the sandbox lifecycle. Use a retained computer when repositories, services, and tools should remain available across tasks. Checkpoints are necessary in either model. **What integrations does an agent environment need to support?** At minimum: GitHub for code and PRs, a project management tool like Linear for task context, and an error monitoring tool like Sentry for bug triage. Connections to Slack or Gmail are useful for async review workflows. These integrations need to stay live even when no human session is active. **How much compute does a team need for parallel agent workloads?** It depends on the number of concurrent agents and the nature of their tasks. A solo developer running two or three agents in parallel can work well on 4 vCPU and 8 GB RAM. Teams running heavier parallel workloads benefit from 12 vCPU and 24 GB RAM or more, with the option to add machines as the workload grows. # Does Claude Code keep running after you close your laptop? URL: /blog/does-claude-code-keep-running-after-laptop-closes A local Claude Code process cannot make progress while your laptop sleeps. Learn what terminal persistence and remote compute change. **A local Claude Code process cannot make progress while your laptop sleeps.** If Claude Code runs on another computer that stays awake, closing your laptop does not suspend that remote computer. The important question is where the task executes. This answer concerns **Claude Code in a terminal**. Claude's web tasks and other managed remote workflows have their own execution lifecycle. Check the [official Claude Code overview](https://code.claude.com/docs/en/overview) to identify which surface you are using. ## Why Claude Code Stops When Your Laptop Closes [#why-claude-code-stops-when-your-laptop-closes] Closing a lid and putting a computer to sleep are not always the same action. Power settings and external-display configurations can change the behavior. If the operating system suspends, however, local commands and network activity pause. The process may resume on wake; it does not necessarily die or lose all its files. An active network request or child command can still fail. | Where the agent runs | What a sleeping laptop changes | | -------------------- | ------------------------------ | | \| Local terminal | The agent and local commands stop making progress until wake. | \| Local terminal inside tmux | tmux preserves the terminal session, but cannot override system suspend. | \| Remote computer inside a persistent terminal | The remote process can continue while the remote host stays running. | \| Provider-managed remote task | Execution follows that provider's task, timeout and billing rules. | Locking the screen alone is different from sleeping. A locked computer can still execute work; its power policy determines whether it later suspends. ## The tmux Approach and Its Limits [#the-tmux-approach-and-its-limits] On an always-running remote server, tmux can keep a terminal session alive when SSH disconnects. On your laptop, it cannot make a suspended processor run. You still need to manage the remote server, agent authentication and repository access. Keeping a laptop awake can be reasonable for a short supervised task. Moving execution to a remote computer is useful when the task needs to outlast the laptop's power or connection. Neither approach guarantees that an agent will finish: it can encounter a permission prompt, a provider limit, an error or a task it cannot solve. ## Running Claude Code on a Dedicated Cloud Computer [#running-claude-code-on-a-dedicated-cloud-computer] [Matrix](https://matrix-os.com) provides a cloud computer you can access through the desktop app, browser and CLI. Run Claude Code in that computer's Terminal, rather than in a local terminal on your Mac. Your laptop then displays the remote session. Follow [the step-by-step Matrix setup and reconnect tutorial](/blog/keep-claude-code-running-after-laptop-closes). It covers signing in, starting a bounded repository task, reconnecting and checking the output. If you already have a computer, start with the [Matrix quickstart](/docs/quickstart). ## What Persistence Actually Requires [#what-persistence-actually-requires] There are three separate things to check: 1. **Compute:** the cloud computer must remain running under the selected plan and lifecycle settings. 2. **Session:** the agent must run in a terminal session that can survive the client detaching. 3. **Progress:** files, test logs and Git changes should record what happened, even if the process later exits. A machine reboot stops processes. A provider authentication failure can interrupt an agent. Saved files do not imply that every agent's conversation can be restored or steered from every Matrix surface. Test reconnecting with your agent and use its supported resume flow when needed. ## Frequently Asked Questions [#frequently-asked-questions] ### Does Claude Code stop when I close my laptop? [#does-claude-code-stop-when-i-close-my-laptop] If it runs locally and the laptop sleeps, it pauses execution. If it runs remotely, the laptop closing does not itself suspend the remote host. ### Can I use tmux or screen to keep Claude Code running? [#can-i-use-tmux-or-screen-to-keep-claude-code-running] Yes, on a remote computer that remains awake. Running either locally does not defeat system sleep. ### What happens to the agent's work if my internet connection drops? [#what-happens-to-the-agents-work-if-my-internet-connection-drops] A detached remote terminal can continue. Reconnect to the same session and inspect its state; a disconnect is not proof that the agent finished or that its provider connection stayed healthy. Check files and logs before starting another run. ### Does this work with other AI coding agents besides Claude Code? [#does-this-work-with-other-ai-coding-agents-besides-claude-code] The same local-versus-remote distinction applies to terminal tools such as Codex CLI and Gemini CLI. Managed background agents already execute remotely and follow their provider's lifecycle. ### What should I try first? [#what-should-i-try-first] Run a small task with a visible output, reconnect once, and inspect the result before leaving a larger task unattended. Use the [Matrix walkthrough](/blog/keep-claude-code-running-after-laptop-closes) for the setup. # Codex alternatives in 2026: choosing the right coding agent URL: /blog/codex-alternative-2026 Compare Codex with Claude Code, Gemini CLI, OpenHands, and other coding agents by workflow, control, and runtime requirements. Codex Alternative in 2026 Codex is an active OpenAI coding agent, available through cloud workflows and developer tools including the CLI. Teams looking for a "Codex alternative" are therefore not replacing a discontinued product. They are comparing agent behavior, interfaces, deployment models, and control. This article compares the main options in 2026 and separates the agent decision from the runtime decision underneath it. For current capabilities, consult the primary documentation for [Codex](https://developers.openai.com/codex/), [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Cursor](https://docs.cursor.com/background-agent), and [OpenHands](https://docs.openhands.dev/). Product features and plan limits change faster than comparison articles. ## What Teams Are Actually Replacing [#what-teams-are-actually-replacing] When developers search for a Codex alternative, they are usually describing one of two situations. The first is model capability: they want an agent that handles multi-step coding tasks, not just autocomplete. The second is workflow fit: they need something that runs continuously against a real codebase, not something that responds to a single prompt and stops. Those are different problems. An agent that handles the first well can still fail at the second if the runtime underneath it is not built for persistent work. ## Which Codex alternatives should you compare? [#which-codex-alternatives-should-you-compare] ### Claude Code [#claude-code] Claude Code is a terminal-first coding agent from Anthropic. It can inspect a repository, edit files, run commands, and iterate against test results. It is a useful comparison when you want a CLI workflow and prefer Anthropic's models and tool conventions. It runs in a terminal, operates against your local filesystem by default, and supports tool use including shell commands and file writes. For developers comfortable with a CLI-first workflow, it fits naturally. When it runs locally, its process shares the lifecycle of the local computer. It can also be run on a remote machine when longer-lived compute is required. ### Gemini CLI [#gemini-cli] Gemini CLI is Google's open-source terminal agent. It is a natural candidate for teams that prefer Google's models or want a terminal-native tool with a broad context window. Like Claude Code, it runs locally by default. The same persistence constraint applies. ### Cursor [#cursor] Cursor is an AI-focused code editor with interactive and background agent workflows. It lowers friction for developers who want AI work embedded in an editor rather than managed primarily through a terminal. Cursor Background Agents run remotely and can continue after the local laptop disconnects. The tradeoff is that Cursor owns the managed agent runtime; it is not a general-purpose computer where you install any agent you choose. ### OpenHands [#openhands] OpenHands is an open-source software-development agent platform. It supports multiple model backends and gives teams more control over the surrounding stack. The tradeoff depends on how it is deployed. Self-hosting gives a team control but also makes the team responsible for compute, credentials, upgrades, and isolation. Check the current hosted and self-hosted options before choosing an operating model. ### Codex CLI (OpenAI) [#codex-cli-openai] Codex CLI brings OpenAI's coding agent into the terminal. It reads and edits a repository, runs commands under configurable approval and sandbox policies, and fits teams that want Codex inside an existing shell workflow. It is part of the current Codex product family, not a replacement for a discontinued standalone product. The same runtime questions apply when it is run locally: the process only stays active while its host computer stays active. ## The Infrastructure Problem Most Comparisons Skip [#the-infrastructure-problem-most-comparisons-skip] Switching agents is the easy part. Every agent listed above can be installed in minutes. The harder question is where the agent runs and what happens when your machine goes offline. Most agents run against your local filesystem in a terminal session. That session is only as durable as the device under it. The terminal is local, the runtime is local, and the session ends when the laptop sleeps. For tasks that complete in under a minute, this does not matter. For tasks that take hours, it is a structural problem. A refactor across a large codebase, a background triage loop watching a Sentry queue, a PR review pipeline that needs to run overnight — none of these fit inside a local session. The answer is not to pick a different agent. It is to move the runtime off your machine entirely. ## Running Multiple Agents Against Shared State [#running-multiple-agents-against-shared-state] One pattern that has emerged in 2026 is teams running more than one agent simultaneously against the same codebase. Claude Code on one branch, Codex CLI on another, Gemini CLI handling documentation. Each agent is good at something different. The problem is that each one wants its own environment, and stitching those environments together manually is its own engineering project. State lives in different places. Agents do not share context. Switching between them means rebuilding the environment each time. [Matrix OS](https://matrix-os.com) addresses this directly. It provisions a dedicated computer where Claude Code, Codex CLI, OpenCode, Pi, and Gemini CLI can run in separate sessions and worktrees. The machine stays on after your laptop closes, and local network disconnects do not stop its processes. Cursor's managed Background Agents remain in Cursor's own runtime. The [cloud computer for agents](/blog/cloud-computer-for-agents) model is distinct from a task sandbox. It is a real persistent computer with files, a database, and a runtime you own and can export. Agents run there continuously. You check in when you need to steer them. ## How the Alternatives Compare on Persistence [#how-the-alternatives-compare-on-persistence] | Agent / Platform | Persistent sessions | Agent-agnostic | Managed infrastructure | | ------------------------ | ------------------------------ | -------------- | ------------------------------- | | Claude Code (local) | Host-dependent | N/A | No | | Gemini CLI (local) | Host-dependent | N/A | No | | Cursor Background Agents | Managed remote jobs | No | Yes | | OpenHands | Deployment-dependent | Yes | Available hosted or self-hosted | | E2B | Configurable sandbox lifecycle | Yes | Yes | | Matrix OS | Persistent computer | Yes | Cloud or self-hosted | Limits, retention policies, and prices change frequently. Verify them in each provider's current documentation rather than treating a plan snapshot as an architectural guarantee. ## Choosing Based on What You Actually Need [#choosing-based-on-what-you-actually-need] If you use a single agent and your tasks complete within a session, any of the agents above will work. Pick the one whose model behavior fits your codebase and workflow. If you run tasks that take hours, need to survive a laptop close, or want to run more than one agent against the same project without rebuilding the environment each time, the agent choice is secondary to the runtime choice. The [Web4 operating system](/whitepaper) framing Matrix OS uses captures the underlying shift: the workspace is the durable unit, not the session. Agents come and go. The computer keeps running. For some teams, Codex remains the right agent and the missing piece is simply a better runtime. For others, model behavior, governance, editor integration, or open-source control will decide the tool. *** ## FAQs [#faqs] ### What is the best Codex alternative for multi-step coding tasks in 2026? [#what-is-the-best-codex-alternative-for-multi-step-coding-tasks-in-2026] There is no universal best alternative. Compare Claude Code, Gemini CLI, Cursor, and OpenHands against a representative repository and the same acceptance criteria. Include review quality, tool permissions, deployment model, and cost in the evaluation. ### Can I run Codex CLI and Claude Code at the same time? [#can-i-run-codex-cli-and-claude-code-at-the-same-time] Yes. Run them in separate Git worktrees and branches so their file changes and build artifacts do not collide. A remote computer is useful for uptime, but Git isolation is what keeps the work reviewable. ### What happens to my agent session when I close my laptop? [#what-happens-to-my-agent-session-when-i-close-my-laptop] If the agent process runs locally, laptop sleep normally pauses the machine and interrupts useful progress. A managed remote agent or an agent running on a persistent remote computer can continue independently of the laptop. ### Is OpenHands a good Codex alternative for teams? [#is-openhands-a-good-codex-alternative-for-teams] OpenHands is open source and supports multiple deployment options. It is a strong candidate when model choice and control matter, but evaluate the operational work required by the deployment option you select. ### How is Matrix OS different from just renting a VPS? [#how-is-matrix-os-different-from-just-renting-a-vps] A raw VPS can technically host any agent. The practical difference is that maintaining agent infrastructure should not become a separate engineering job. Matrix OS provisions the machine, manages the runtime, and provides a web shell, CLI access, and agent session management out of the box. The environment is yours and exportable. ### Does Cursor work as a Codex alternative for background agent tasks? [#does-cursor-work-as-a-codex-alternative-for-background-agent-tasks] Cursor is a strong alternative when an editor-centered workflow and Cursor-managed background execution fit the team. Choose a general-purpose persistent computer instead when you need direct control of the machine or want to run several terminal agents in one durable workspace. ### What should I prioritize when evaluating a Codex alternative: the model or the infrastructure? [#what-should-i-prioritize-when-evaluating-a-codex-alternative-the-model-or-the-infrastructure] For short tasks, the model matters most. For tasks that take hours, run overnight, or need to survive a disconnect, the infrastructure matters more. Most comparisons focus on model capability and skip the runtime question entirely — which is why teams often hit the same persistence wall regardless of which agent they switch to. # Modal alternatives for persistent agent jobs URL: /blog/modal-alternative-always-on-agent-jobs Compare Matrix OS, E2B, Daytona, and OpenHands for stateful agent work that does not fit a short-lived function runtime. Four platforms for always-on agent jobs Modal is built around functions, containers, jobs, schedules, and scalable compute. If an agent workload fits that programming model, Modal may handle it well. Running Claude Code on a long refactor, keeping a Codex session available across a migration, or returning to the same development services over several days is a different workload. The team should decide whether to adapt that work to Modal's application model or keep it inside a conventional persistent computer. If you are comparing Modal alternatives for stateful agent work, these four options draw the infrastructure boundary in different places. Verify current capabilities in the [Modal documentation](https://modal.com/docs), [E2B documentation](https://e2b.dev/docs), [Daytona documentation](https://www.daytona.io/docs/), and [OpenHands documentation](https://docs.openhands.dev/). *** ## What Makes an Agent Job "Always-On" [#what-makes-an-agent-job-always-on] It helps to be precise about the workload category before comparing platforms. An always-on agent job has a few defining properties: it runs for minutes or hours, not milliseconds; it reads and writes to a persistent filesystem; it may pause for human input and resume; and it should not be interrupted by a laptop sleeping, a network drop, or a session timeout. These requirements do not map directly to a simple function invocation. Modal provides persistence and application primitives, but a terminal-agent workflow may require different composition than it would on a retained development computer. The four alternatives below each handle this differently. *** ## 1. Matrix OS [#1-matrix-os] [Matrix OS](https://matrix-os.com) provisions a dedicated cloud computer per developer — a Hetzner-backed VPS with isolated compute, files, a database, and a runtime that belongs entirely to you. Agents run in persistent sessions on that machine, 24/7, regardless of whether your laptop is open. The key architectural difference from Modal is the retained computer. When you close your laptop, processes on that remote computer can keep running. When you reconnect, its files and services remain available, subject to normal process and host recovery limits. Matrix OS supports Claude Code, Codex, Cursor, OpenCode, Pi, and Gemini CLI running simultaneously in isolated sessions on the same machine, with shared file state. That combination is what makes long-horizon agent work practical: one durable environment, any agent, no rebuilding context when you switch. The Symphony orchestration layer handles parallel task queues, agent status tracking, branch and diff review, and human-in-the-loop handoff. The Hermes resident agent manages scheduled workflows, tool connections, and approval queues. Integrations include GitHub, Linear, Slack, Discord, Sentry, and Datadog. See [current Matrix plans and resources](/#pricing) and the terms displayed at checkout. Choose the computer lifecycle and capacity required by your workload; agent-provider access can have separate costs. Matrix OS is the right fit if you want a persistent, agent-agnostic environment and do not want maintaining that infrastructure to become another engineering job. If you use only one agent and that provider's own cloud capabilities already satisfy you, it may not be the strongest fit yet. Read more about the underlying design in [Cloud Computer For Agents](/blog/cloud-computer-for-agents). *** ## 2. E2B [#2-e2b] E2B provides sandboxed cloud environments designed for running AI-generated code safely. It is well-suited for short-lived execution: running code snippets, testing agent outputs in isolation, or giving an agent a clean environment for a discrete task. E2B centers on API-created sandboxes with configurable lifecycle controls. It is a closer fit when an application needs isolated execution on demand than when a developer wants to retain one named computer across projects. Verify current duration and pricing in E2B's documentation. For agent jobs that complete within a session window, E2B is a reasonable choice. For jobs that run overnight, span multiple days, or require a developer to reconnect and resume, the session model is a hard architectural limit. *** ## 3. Daytona [#3-daytona] Daytona is built around fast, disposable development environments. It uses Docker container isolation with a shared host kernel, which makes it efficient for spinning up and tearing down workspaces quickly. The pay-as-you-go pricing at $0.0504/vCPU/hour works well for burst workloads. Daytona centers on development infrastructure and isolated workspaces. Evaluate its current persistence and lifecycle controls if an agent must accumulate state across days; do not infer them from the product category alone. It is worth evaluating if your workflow is closer to "provision a clean environment, run a task, discard it" than "keep an agent running in the background indefinitely." *** ## 4. OpenHands [#4-openhands] OpenHands is model-agnostic and has a substantial open-source community. It supports multiple agents and gives you control over which models you point at a task. For developers who want to run agent workflows without being locked into a single provider's tooling, it is a serious option. OpenHands is an agent platform with hosted and self-hosted options. Evaluate those separately: self-hosting gives more control but makes your team responsible for the runtime, model access, upgrades, and isolation. The distinction matters because selecting an agent platform and selecting the lifecycle of its execution environment are related but separate decisions. *** ## Choosing Based on the Actual Constraint [#choosing-based-on-the-actual-constraint] The right question is not "which Modal alternative is best" but "what is the actual constraint in my agent workflow." If the constraint is isolated programmatic execution, evaluate E2B. If reproducible development workspaces are central, evaluate Daytona. If you want an open-source software-development agent platform, evaluate OpenHands and compare its hosted and self-hosted operating models. For a lifecycle-first evaluation framework, use [How to choose hosting for AI coding agents](/blog/ai-agent-hosting-guide). If the constraint is the one that keeps coming up in practice — agents that stop when the laptop closes, state that disappears between sessions, environments that need to be rebuilt every time you switch agents — that is the problem Matrix OS is built around. The machine stays on. The sessions persist. The agents run whether or not you are at your desk. That is a different product category from Modal, not a better version of it. Choose between them based on whether the primary abstraction should be a retained development computer, an API sandbox, an agent platform, or Modal's function-and-container model. *** ## The Underlying Architecture [#the-underlying-architecture] The reason these products differ so sharply is not feature gaps — it is architectural intent. Modal's design principle is statelessness. Cold starts are not a bug; they are the model. Ephemeral compute is efficient for the workloads Modal targets. A retained agent workspace prioritizes a computer, filesystem, and services that remain available between tasks. A platform built around jobs and functions can support state through its own primitives, but the workflow and ownership model are different. That is why the [always-on agent problem](/blog/keep-claude-code-running-after-laptop-closes) keeps surfacing as a distinct search query rather than a feature request against existing tools. Developers are not asking for a faster sandbox. They are asking for a different kind of environment entirely. *** ## FAQs [#faqs] **What is the main reason Modal does not work well for always-on agent jobs?** Modal is architected around functions, containers, jobs, and services. It offers persistence primitives, but a terminal-agent workspace must be composed within that model. Teams that want a conventional retained computer may prefer a different abstraction. **Can I run Claude Code, Codex, and Gemini CLI on the same persistent environment?** Matrix OS can run terminal agents such as Claude Code, Codex CLI, OpenCode, Pi, and Gemini CLI on one dedicated computer. Use separate Git worktrees and runtime resources for parallel tasks. Cursor Background Agents remain in Cursor's managed environment. **What happens to my agent session if my laptop closes?** On Modal and most sandbox platforms, a session tied to your local machine or a time-limited sandbox will stop or expire. On Matrix OS, the cloud computer keeps running regardless of whether your device is connected. You reconnect from any browser or terminal and the session is where you left it. **Is E2B a good Modal alternative for agent work?** E2B is well-suited to sandboxed code execution controlled through an API. Check its current pause, resume, duration, storage, and pricing behavior against the workload rather than relying on a plan snapshot. **What does "agent-agnostic" mean in this context?** It means the compute environment does not require you to use a specific agent or model. Platforms like Devin bring their own proprietary agent; you cannot point Claude Code or Codex at Devin's infrastructure. Agent-agnostic platforms let you choose which agent runs against your environment and switch without rebuilding state. **Is a raw VPS a viable alternative to all of these?** A well-configured VPS can handle persistent agent sessions. The honest framing is not that a VPS cannot do this — it is that configuring and maintaining the infrastructure behind agents adds operational overhead. The question is whether that overhead is worth taking on versus using a managed environment purpose-built for agent workloads. **What is the entry price for Matrix OS compared to these alternatives?** Matrix OS uses fixed monthly cloud-computer plans. E2B and Daytona use different resource and lifecycle models. Compare current prices using a representative month of compute, storage, concurrency, and operator time. *** The right platform depends on the shape of your workload. For stateless burst compute, Modal remains a strong choice. For persistent agent sessions that need to run without a local machine, the options above each address a different slice of that problem. Matrix OS is the one built specifically around that use case from the ground up. Learn more at [matrix-os.com](https://matrix-os.com). # Building an agent-native deal workspace inside Matrix URL: /blog/agent-native-deal-workspace-matrix How Matrix could combine deal flow, project plans, company files, email, document automation, KYC operations, and team review in one shared workspace. *Part of the [Matrix company OS series](/blog/company-os-ai-agents-series).* Corporate finance work is a useful test for a company operating system because every engagement crosses the same difficult boundaries. There is structured deal data, but the work does not fit neatly into a generic CRM. There are sensitive documents in OneDrive. Client and investor communication runs through email. Every mandate follows a recognizable process, but each has different counterparties, deadlines, documents, and judgment calls. Colleagues need a shared view without losing individual ownership. The usual answer is a collection of spreadsheets, folders, inboxes, and templates. AI gets added one task at a time, while the coordination layer remains manual. An agent-native deal workspace would make the deal—not the spreadsheet row or chat session—the durable unit of work. This post is a product blueprint informed by customer discovery. It describes where Matrix can go; it does not claim that all of these enterprise features are available today. ## Start with a deal object, not a generic contact database [#start-with-a-deal-object-not-a-generic-contact-database] A heavy CRM is often designed around sales activity. A corporate finance team needs a lighter operational record around the mandate itself. The core record might include: * mandate type and stage, * client entity and key contacts, * internal owner and working team, * counterparties or investor universe, * milestones and next decisions, * connected OneDrive folder, * relevant email threads, * KYC status and exceptions, * document set and latest approved versions, * activity and approval history. Structured fields make the pipeline filterable. The workspace around those fields carries the actual work. That distinction matters. Replacing Excel with another grid does not solve the problem. The product becomes useful when a stage change can create tasks, attach the right template, wake an agent, or ask an owner for missing information. ## Create every mandate from a template [#create-every-mandate-from-a-template] A project template should be executable company knowledge. It can define: * default stages and milestones, * folder structure, * required documents, * KYC checklist, * recurring tasks, * document templates, * agent skills and instructions, * approval rules, * reporting cadence, * naming conventions. When a new mandate opens, Matrix creates the workspace, plan, roles, and source connections from that template. The team starts with the firm's operating method rather than a blank project. Templates must also be versioned. An active deal should record which version created it, while administrators can decide whether later policy changes must propagate to existing workspaces. ## Keep OneDrive authoritative [#keep-onedrive-authoritative] For a Microsoft-centered firm, OneDrive and SharePoint should remain the document system of record. Matrix can connect a selected deal folder, track changes through Microsoft Graph, index supported content for authorized retrieval, and materialize files when an agent needs to work with them. The technical design is explored in [turning OneDrive and Google Drive into agent working memory](/blog/onedrive-google-drive-working-memory-ai-agents). The workspace should always point back to the authoritative file and version. Generated work begins as a Matrix draft. After review, Matrix writes it to an approved destination and records the resulting OneDrive item and version. That keeps the integration legible: * source files stay where company policy expects them, * agents receive only workspace-scoped context, * reviewers know which versions were used, * approved outputs return to the company folder, * permissions remain tied to Microsoft identity. ## Turn email into project activity without copying the whole inbox [#turn-email-into-project-activity-without-copying-the-whole-inbox] Email automation should be owner-aware and thread-specific. A user can connect Outlook with delegated access and associate selected threads, contacts, or mailbox folders with a deal. Microsoft Graph supports message change notifications and the creation of drafts as well as sending mail. A cautious first workflow should stop at a draft. For example: 1. A relevant inbound message is detected. 2. Matrix links it to a deal using explicit rules and known participants. 3. The workflow updates the activity timeline. 4. An agent identifies promised actions or missing responses. 5. The relationship owner receives a proposed follow-up. 6. Approval creates an Outlook draft. 7. Sending remains the employee's action until policy allows otherwise. The system should not indiscriminately scrape every employee mailbox into a common index. Access follows the employee, the workspace includes selected context, and any broader company mailbox automation requires administrative consent and clear policy. ## Make document automation evidence-driven [#make-document-automation-evidence-driven] Many professional-services documents are highly reusable without being fully generic. A robust document workflow separates: * fixed company language, * approved template structure, * structured deal data, * sourced facts, * calculated values, * agent-generated narrative, * reviewer edits. Every generated section should know which category it belongs to. Fixed legal language should not be casually rewritten. Facts should link to source records. Calculations should preserve inputs. Narrative can be drafted by an agent but remains visibly generated until reviewed. This allows high automation without pretending that the final document is low-risk. The useful target is not “AI writes 85%.” It is “the system assembles the repeatable 85%, exposes the variable 15%, and routes both through the right review.” ## Treat KYC as a controlled workflow, not an autonomous verdict [#treat-kyc-as-a-controlled-workflow-not-an-autonomous-verdict] KYC is an attractive automation target because it involves repetitive collection, classification, extraction, and follow-up. It is also a poor place for vague claims. The Financial Action Task Force recommendations cover customer due diligence and record keeping, but concrete obligations depend on jurisdiction, institution, transaction, and professional advice. Matrix can support operations around the process without declaring that a customer is compliant. A bounded workflow can: * detect new documents in an approved folder, * classify document types, * extract selected fields with confidence indicators, * compare the set against a configured checklist, * flag expired, duplicate, unreadable, or missing material, * propose a follow-up request, * organize reviewed files into the expected structure, * preserve source, reviewer, and action history. A designated person remains responsible for deciding whether the evidence is sufficient and what regulatory action follows. GDPR principles reinforce the need for purpose limitation and data minimization: personal data should be collected for specific purposes and limited to what is necessary. In product terms, a KYC agent should not gain open-ended access to every identity document the company has ever received. ## Give colleagues one operational view [#give-colleagues-one-operational-view] The workspace home should answer four questions: 1. Where is this deal now? 2. What changed recently? 3. What is blocked or at risk? 4. What needs a person's decision? A useful view could include: | Area | What it shows | | ----------- | --------------------------------------------------------- | | Deal header | Stage, owner, client, next milestone, health | | Plan | Tasks, dependencies, deadlines, and assignees | | Activity | Source changes, communications, agent runs, and decisions | | Documents | Required set, latest versions, and review status | | KYC | Checklist, exceptions, evidence, and owner | | Approvals | Proposed communications, writes, and high-risk actions | | Agents | Active, waiting, failed, and completed runs | This is where the [shared workspace model](/blog/shared-agent-workspaces-for-teams) becomes concrete. A partner can review status without reading every thread. An associate can see the exact exception to resolve. A new team member can enter an active mandate without reconstructing it from inbox history. ## The agents are attached to responsibilities [#the-agents-are-attached-to-responsibilities] Instead of one universal deal bot, the workspace can assign specialized agents: * **Intake agent:** checks that the workspace and folder structure are complete. * **KYC operations agent:** classifies evidence and maintains the checklist. * **Document agent:** assembles drafts from approved templates and sources. * **Follow-up agent:** prepares owner-reviewed email drafts. * **Reporting agent:** produces a periodic status report. * **Coordinator agent:** monitors the plan and surfaces exceptions. Each agent receives different sources, tools, and action policy. Specialization makes permissions and evaluation clearer than giving one agent access to everything. ## A practical first release [#a-practical-first-release] The first release should prove one mandate workflow end to end: 1. Create a deal from a template. 2. Connect one OneDrive folder. 3. Import or enter the lightweight deal record. 4. Generate the project plan and checklist. 5. Track document changes. 6. Draft one recurring report. 7. Route it to an owner for review. 8. Store the approved version and complete activity history. Email follow-ups and KYC classification can follow once the permission, review, and audit model works reliably. This is how we think Matrix grows from [a cloud computer for agents](/blog/cloud-computer-for-agents) into [a company OS built on existing tools](/blog/company-os-ai-agents-series): one complete, accountable workspace at a time. The opportunity extends beyond M\&A. Legal matters, consulting engagements, recruiting searches, audits, and complex sales processes share the same shape: a structured record surrounded by files, communication, plans, judgment, and repeated work. The deeper implementation paths are a [lightweight agent-native CRM](/blog/building-agent-native-crm-matrix), [safe email follow-up agents](/blog/building-safe-email-agents), [evidence-driven document automation](/blog/automating-professional-services-documents), and [AI-assisted KYC operations](/blog/building-ai-assisted-kyc-workflows). # Automating professional-services documents with AI URL: /blog/automating-professional-services-documents A Matrix architecture for assembling documents from approved templates, structured data, sourced facts, agent-written narrative, and human review. *Part of the [Matrix company OS series](/blog/company-os-ai-agents-series).* Professional-services documents are repetitive and bespoke at the same time. A monthly report, client update, mandate document, investment memo, or due-diligence request may reuse most of its structure and language. The remaining sections depend on current project facts, analysis, and professional judgment. That makes “generate the whole document from a prompt” the wrong abstraction. The safer and more useful target is to automate the repeatable 85% while making the variable 15% easier to review. This post describes how we would build that workflow in Matrix OS. It is a product direction, not a claim that every document connector described here is available today. ## Decompose the document before automating it [#decompose-the-document-before-automating-it] Every section should have a content type: | Content type | Example | Default treatment | | --------------------- | ---------------------------------------- | ------------------------------------ | | Locked language | Disclaimers or approved standard terms | Copy exactly from a versioned source | | Template structure | Headings, tables, and required sections | Render deterministically | | Structured data | Names, dates, amounts, owners, stages | Pull from validated fields | | Sourced fact | Market data or project status | Require source and observed version | | Calculation | Totals, percentages, and reconciliations | Execute with preserved inputs | | Generated narrative | Summary, explanation, or transition | Draft with visible provenance | | Professional judgment | Recommendation or conclusion | Assign to a qualified reviewer | Without this decomposition, a model can rewrite language it should preserve, invent values that should be queried, or hide judgment inside fluent prose. ## Templates are executable company knowledge [#templates-are-executable-company-knowledge] A template is more than a `.docx` file with placeholders. Matrix should treat it as a versioned package containing: * the base document, * field schema and validation, * approved clauses and their conditions, * instructions for generated sections, * required sources, * calculations, * review roles, * output naming and destination policy, * evaluation examples. When a company changes its standard language, the template version changes. An output records the version used, so reviewers can explain why an older project differs from a newer one. Templates can live as inspectable project assets, consistent with the [Matrix file-system model](/docs/guide/file-system), while approved outputs return to OneDrive or Google Drive. ## Build a document evidence graph [#build-a-document-evidence-graph] Before writing, the workflow assembles a structured evidence set: ```text field: transaction_value value: 42,000,000 EUR source: approved-model.xlsx / Summary!B14 observed_version: 19 validated_by: finance-owner ``` The generated draft can then link a sentence or table cell to its evidence. A reviewer can inspect the source without searching through several folders. Evidence has states: * available and current, * available but unverified, * conflicting, * missing, * stale relative to a configured deadline. The agent should not smooth over a conflict. It should leave a visible placeholder or route the field to an owner. ## Assemble first, generate second [#assemble-first-generate-second] The workflow order matters: 1. Resolve the template and version. 2. Collect structured fields and approved clauses. 3. Validate required inputs. 4. Run deterministic calculations. 5. Build tables and fixed sections. 6. Generate only the narrative sections. 7. Render a review artifact. 8. Run mechanical and factual checks. 9. Route role-specific review. 10. publish the approved version. Google Docs exposes document creation, retrieval, and atomic batch updates. That supports deterministic assembly and formatting without asking a model to reproduce the whole document format. The same principle applies to Microsoft document formats: use structured document operations for structure, and reserve models for language and interpretation. ## Review the risky parts, not every comma equally [#review-the-risky-parts-not-every-comma-equally] A reviewer needs a risk-weighted diff: * locked language changed unexpectedly, * a required field is missing, * a sourced fact changed since the prior version, * generated narrative introduces a number not present in evidence, * a calculation differs from its checked result, * a recommendation lacks an assigned reviewer, * an external link or attachment is new. This is more useful than presenting a 40-page document and asking someone to “check the AI.” Different roles can review different layers. Operations checks completeness. Finance owns calculations. A relationship owner checks tone and commitments. Legal or compliance reviews controlled sections where required. ## Preserve the review as structured data [#preserve-the-review-as-structured-data] Review comments should feed the system without silently changing the template. Matrix can distinguish: * one-off edit for this document, * correction to project data, * new company-wide writing preference, * template defect, * agent instruction defect, * source association error. An administrator can promote repeated feedback into a new template or skill version. The next document improves because the operating knowledge changed explicitly, not because an opaque model memory absorbed a comment. ## Write back through a controlled publishing step [#write-back-through-a-controlled-publishing-step] The generated document begins in the workspace as a draft. Publishing should verify: * output folder and file name, * current destination permissions, * conflicting existing versions, * required reviewers and approvals, * classification or retention metadata, * final format and source links. The publishing service then creates or updates the provider document, records its stable ID and version, and links the result back to the workflow run. This uses the [connected-drive architecture](/blog/onedrive-google-drive-working-memory-ai-agents) without turning a broad two-way folder sync into the authority boundary. ## A monthly report is the ideal first workflow [#a-monthly-report-is-the-ideal-first-workflow] Monthly reporting exercises the complete system without beginning with the highest-risk document: * a predictable schedule, * a known template, * recurring data sources, * narrative summarization, * a clear project owner, * an approved destination, * easy comparison with the prior month. The workflow can measure missing-input rate, time to first draft, reviewer edit distance, late approvals, and factual corrections. Those metrics help decide which sections are ready for more automation. The implementation fits the [trigger-to-outcome model](/blog/trigger-to-outcome-matrix-agent-workflows): schedule, gather evidence, assemble, draft, review, publish, record. ## Automation should make judgment more visible [#automation-should-make-judgment-more-visible] The goal is not a document no person has touched. The goal is to stop spending professional time on copying, reformatting, locating the latest number, and rebuilding standard language. Matrix can automate the repeatable layer because it already provides the place where agents work: persistent files, tools, processes, and review surfaces. The [company OS](/blog/company-os-ai-agents-series) adds the connections, shared ownership, and policy needed to make the output operational. The best document system does not hide the 15% that requires judgment. It brings that 15% forward. # Building a lightweight, agent-native CRM inside Matrix URL: /blog/building-agent-native-crm-matrix How Matrix could connect lightweight deal records to company files, email, project plans, workflows, and agents without becoming a heavy CRM. *Part of the [Matrix company OS series](/blog/company-os-ai-agents-series).* Many small professional-services firms run important pipelines in Excel. That is not necessarily because they have failed to discover CRM software. It is often because a spreadsheet matches the shape of the decision better than a heavyweight sales system does. An M\&A boutique cares about mandates, counterparties, stages, documents, deadlines, and judgment. A consulting firm cares about engagements, deliverables, staffing, risks, and client decisions. The structured record matters, but most of the work happens around it. The next useful product is not a bigger CRM. It is a lightweight record that agents can use as a coordination surface. This post describes a roadmap direction for Matrix OS. It is a product design, not a statement that a complete Matrix CRM is available today. ## The spreadsheet is doing three jobs [#the-spreadsheet-is-doing-three-jobs] A typical deal-flow spreadsheet combines: 1. **Database:** one row per opportunity or mandate. 2. **Interface:** filters, colors, comments, and manually ordered priorities. 3. **Coordination:** an implicit signal of what the team should do next. Traditional CRM migration focuses on the first job. It normalizes the rows into contacts, companies, opportunities, and activities. The result may be more structured but not more useful if the team still coordinates through email and meetings. An agent-native CRM should make the third job explicit. A record is not only something to store; it is context that can activate a workflow. ## Keep the object model small [#keep-the-object-model-small] The first Matrix model could use five objects: | Object | Purpose | | ------------ | ---------------------------------------------------------- | | Organization | The client, target, investor, counterparty, or partner | | Person | A contact with roles and organization relationships | | Project | A mandate, engagement, raise, or other bounded outcome | | Activity | A meeting, message, decision, file change, or agent action | | Task | An owned next step with status and timing | Industry-specific fields belong on project templates rather than in a universal schema. An M\&A mandate can add deal stage, transaction type, and KYC status. A recruiting search can add role, candidate stage, and interview plan. This keeps the shared core stable while allowing each workflow to speak the company's language. ## The project record should point to the work [#the-project-record-should-point-to-the-work] A CRM record often contains links and notes about work performed elsewhere. In Matrix, the record can live inside the workspace where the work happens. The project connects: * its [shared agent workspace](/blog/shared-agent-workspaces-for-teams), * approved OneDrive or Google Drive roots, * selected email threads and participants, * a plan created from a template, * active and completed workflows, * current documents and approvals, * a chronological activity record. The structured record remains filterable across the organization. Opening it reveals the actual operating context rather than an activity feed reconstructed from shallow integrations. ## Agents should propose field changes with evidence [#agents-should-propose-field-changes-with-evidence] An agent can infer that a project moved stages from an email or meeting note. It should not silently rewrite the database. A proposed update needs: ```text project: North field: stage current: diligence proposed: documentation evidence: [email-thread-184, meeting-note-22] confidence: high policy: owner-review ``` Low-risk derived fields, such as “last activity date,” may update automatically. Commercial or compliance-relevant fields should require an owner or designated reviewer. This evidence model also makes correction productive. If the owner rejects the change because the email referred to a different workstream, Matrix can improve the association rule without erasing what happened. ## Activity is a provider-neutral event stream [#activity-is-a-provider-neutral-event-stream] Email, file, task, and workflow integrations all describe events differently. Matrix needs a small internal event contract: ```text event type source system and stable source ID organization and workspace actor and authority occurred time and observed time bounded summary source link and version related people, project, and task ``` The event stream powers the timeline, workflow triggers, reporting, and follow-up detection. It also helps with idempotency: if a provider delivers the same notification twice, Matrix can avoid creating duplicate activity. The original system stays authoritative. The event is Matrix's traceable observation of it. ## Views should answer operational questions [#views-should-answer-operational-questions] The first views do not need the complexity of a mature CRM. They need to answer: * Which projects have no owned next step? * Which deadlines are approaching? * Which client threads need attention? * Which workflows are waiting for review? * Which projects have missing inputs? * What changed since the last team meeting? Agents can maintain these views, but the underlying filters should remain inspectable. A project should not become “at risk” only because a model produced an opaque score. The interface should expose the conditions and evidence behind the status. ## Import from Excel without preserving every accident [#import-from-excel-without-preserving-every-accident] A spreadsheet importer should map columns into the small core model, preserve the original row for traceability, and surface ambiguous values for review. The migration flow could be: 1. Upload or connect the source workbook. 2. Detect columns and example values. 3. Propose mappings to Matrix fields. 4. Identify duplicates and invalid states. 5. Let an operator approve the mapping. 6. Import into a staging workspace. 7. Compare counts and sampled records. 8. Publish the new shared view. We should resist carrying every color code, free-text convention, and hidden formula into the permanent schema. The goal is to preserve business meaning, not spreadsheet archaeology. ## Build the workflow before the dashboard [#build-the-workflow-before-the-dashboard] The proof of an agent-native CRM is not a polished pipeline chart. It is one reliable operational loop. For example: > A new project is created → Matrix applies a mandate template → the owner connects the project folder → required tasks and documents appear → agents monitor bounded sources → exceptions and proposed updates enter a shared review queue → the weekly report is assembled from the same state. That loop uses the architecture in [trigger-to-outcome workflows](/blog/trigger-to-outcome-matrix-agent-workflows) and the concrete model in [the agent-native deal workspace](/blog/agent-native-deal-workspace-matrix). The CRM becomes useful because it participates in work. It is not another place employees must remember to update after the work is done. ## The right measure is less coordination debt [#the-right-measure-is-less-coordination-debt] We would evaluate the product using operational outcomes: * percentage of active projects with a current owner and next step, * time from source event to visible project update, * number of manual duplicate entries removed, * reviewer correction rate for proposed changes, * time required to prepare a portfolio or pipeline review, * number of exceptions discovered before a deadline. A lightweight CRM succeeds when it reduces the team's need to reconstruct reality. The agent-native version succeeds when it keeps that reality current without taking unreviewed authority over it. That is the Matrix opportunity: a structured layer small enough to adopt, connected to the [company OS](/blog/company-os-ai-agents-series), and close enough to the work that agents can help maintain it responsibly. # Building AI-assisted KYC workflows with human review URL: /blog/building-ai-assisted-kyc-workflows How Matrix could support KYC intake, classification, extraction, exceptions, review, and records while leaving compliance decisions with people. *Part of the [Matrix company OS series](/blog/company-os-ai-agents-series).* KYC work contains exactly the mix that makes agent automation valuable and dangerous. Teams repeatedly collect documents, name files, extract fields, compare them with checklists, find missing information, and prepare follow-up requests. Agents can reduce that operational burden. But KYC is not merely a document-sorting problem. Customer due diligence and record-keeping obligations depend on the firm's role, jurisdiction, risk assessment, and applicable law. A model should not turn incomplete evidence into a confident compliance verdict. The right product boundary is **AI-assisted KYC operations with accountable human decisions**. This post is a product architecture for Matrix OS, not legal advice or a claim that a Matrix KYC product is available today. ## Separate the checklist from the decision [#separate-the-checklist-from-the-decision] A Matrix KYC template can encode the operational checklist: * required document categories, * accepted formats and age limits, * fields to extract, * entity-type variations, * folder and naming conventions, * internal owners, * escalation conditions, * review roles, * retention and deletion instructions. The checklist helps the system answer “what evidence is present, missing, inconsistent, or expired?” It should not answer “is this customer legally acceptable?” unless a qualified person applies the firm's policy and authority. The final decision remains an explicit human action with recorded evidence. ## Scope the workspace to one case [#scope-the-workspace-to-one-case] Identity documents and ownership information are sensitive personal data. The workflow should operate inside a case-specific workspace with narrow access. The source integration connects only approved folders or intake channels. The KYC agent receives only the case, template, and tools required for its step. A general reporting agent should not automatically inherit access to passports or beneficial-ownership documents. This follows GDPR principles described by the European Commission: processing should have a specific purpose and use only the personal data necessary for that purpose. It also follows the [Matrix working-memory design](/blog/onedrive-google-drive-working-memory-ai-agents), where provider access, organization policy, workspace scope, and run scope remain separate. ## Model evidence and exceptions explicitly [#model-evidence-and-exceptions-explicitly] The core records could be: ```text case party requirement evidence item extracted field exception review decision ``` An evidence item points to an authoritative provider file and version. Extracted fields carry source locations and confidence. Requirements have states such as missing, received, needs review, accepted, rejected, expired, or not applicable. Exceptions should be first-class objects: * name mismatch, * unreadable document, * missing page, * conflicting registration number, * expired identity document, * ownership percentages not reconciling, * unexpected jurisdiction, * source permission lost. The agent's job is to surface and explain exceptions, not bury them inside a summary. ## Use a staged intake pipeline [#use-a-staged-intake-pipeline] A practical workflow can proceed through bounded stages. ### 1. Detect [#1-detect] A provider change feed or controlled upload signals new material. Matrix reconciles the source folder rather than trusting the notification payload alone. ### 2. Classify [#2-classify] The agent proposes document type, related party, language, and likely requirement. Low confidence goes to review. ### 3. Extract [#3-extract] Configured fields are extracted with page-level provenance. Values are not written directly into accepted case data. ### 4. Validate [#4-validate] Deterministic checks evaluate dates, formats, duplicate files, field agreement, and checklist completeness. External verification sources, where authorized, remain distinct from model inference. ### 5. Review [#5-review] A designated person accepts or corrects classifications and extracted fields, then resolves exceptions. ### 6. Organize [#6-organize] Approved files can be renamed or moved according to policy through a reviewed write-back action. ### 7. Follow up [#7-follow-up] The agent drafts a bounded request for missing or corrected material. A person approves the recipient and message. ### 8. Record [#8-record] Matrix preserves the evidence versions, checks, reviewer actions, and resulting status. This is a specialized version of the [trigger-to-outcome workflow](/blog/trigger-to-outcome-matrix-agent-workflows). ## Avoid a single opaque risk score [#avoid-a-single-opaque-risk-score] A composite score can be convenient and misleading. It compresses different issues into one number and encourages reviewers to accept a threshold without understanding the cause. The interface should show decomposed signals: * checklist completeness, * evidence freshness, * unresolved identity conflicts, * source verification status, * ownership complexity, * policy-specific risk factors, * extraction confidence, * pending reviewer decisions. If a firm uses a formal risk model, Matrix should version that model and show the contributing fields. Agent-generated observations should remain distinguishable from deterministic checks and externally verified facts. ## Build retention and revocation into the workflow [#build-retention-and-revocation-into-the-workflow] KYC systems cannot treat storage as an afterthought. Each evidence category should have configured rules for: * reason for collection, * authorized roles, * retention start and end, * legal hold where applicable, * export restrictions, * deletion or anonymization, * derived data and generated summaries. When source access is revoked, Matrix should immediately remove the item from retrieval and stop dependent runs. The organization still needs a policy decision about retained records and derivatives; the agent should not decide that on its own. ## The activity record must support reconstruction [#the-activity-record-must-support-reconstruction] A reviewer or auditor should be able to reconstruct: * which template and policy version applied, * which source files and versions were considered, * which fields were extracted and from where, * which automated checks ran, * which exceptions appeared, * who reviewed each disputed item, * what final decision was recorded, * what follow-up or file operation occurred. NIST's Generative AI Profile emphasizes governance, measurement, and monitoring. The European Commission's AI Act overview likewise highlights logging and human oversight for regulated high-risk contexts. Whether a particular KYC tool falls into a specific legal category is a legal assessment; traceability and review are still sound product requirements. ## Start with organization, not adjudication [#start-with-organization-not-adjudication] The safest first release automates the least controversial work: 1. Monitor one approved intake folder. 2. Classify a narrow set of document types. 3. Extract a small field set with provenance. 4. Compare the file set with a firm-configured checklist. 5. Route every classification and exception to a person. 6. Organize only approved files. 7. Produce a case summary that explicitly avoids a compliance verdict. This gives a team immediate operational value while the firm validates accuracy, access controls, and review procedures. Inside an [agent-native deal workspace](/blog/agent-native-deal-workspace-matrix), the KYC workflow becomes one controlled workstream rather than a disconnected tool. Colleagues see its status and exceptions without gaining access to every underlying identity document. AI can remove a large amount of KYC coordination. Accountability should remain exactly where it belongs. # How we would build safe email follow-up agents in Matrix URL: /blog/building-safe-email-agents A product and technical architecture for connecting Outlook and Gmail, detecting follow-up opportunities, drafting replies, and keeping people in control. *Part of the [Matrix company OS series](/blog/company-os-ai-agents-series).* Email looks like an obvious agent workflow: read a thread, decide whether it needs attention, draft a response, and send it. The difficult part is everything hidden inside “read a thread.” Mailboxes mix clients, colleagues, personal information, confidential attachments, automated notifications, and messages unrelated to the workflow. Sending is also unusually consequential: a polished mistake leaves the company immediately. We think email agents should begin as **attention and drafting systems**, not autonomous senders. This is the architecture we would use to build them in Matrix OS. It is a roadmap design, not an announcement that these integrations are available today. ## Connect the employee, not a shadow inbox [#connect-the-employee-not-a-shadow-inbox] The default connection should use the employee's identity and delegated access. Microsoft Graph distinguishes delegated permissions, where an app acts for a signed-in user, from application permissions that operate without a user. Google similarly exposes separate Gmail scopes for metadata, reading, composing, and sending, and recommends choosing the narrowest scope possible. Matrix should make those distinctions visible during setup: * what mailbox is connected, * which folders or labels are in scope, * whether message bodies or only metadata are read, * whether Matrix can create drafts, * whether it can send, * who granted access, * when the connection expires or is revoked. An organization-wide service connection may eventually support shared mailboxes or controlled processes, but it should be an administrator decision with a separate policy—not a shortcut around employee consent. ## Watch narrowly, reconcile reliably [#watch-narrowly-reconcile-reliably] Both Microsoft and Google support event-driven mailbox updates, but neither should be treated as a perfect event log. Microsoft Graph supports change notifications for Outlook messages and incremental change tracking. Subscriptions expire and require renewal. Gmail delivers mailbox notifications through Cloud Pub/Sub; its watch must be renewed, and Google documents that notifications can occasionally be delayed or dropped. Gmail clients retrieve the actual changes using `history.list` from a stored history ID. The Matrix connector should: 1. Watch only configured folders or labels where possible. 2. Persist the provider cursor or history ID. 3. Treat a notification as a wake-up signal. 4. Retrieve authoritative changes after the cursor. 5. Deduplicate provider events. 6. Periodically reconcile if notifications are missed. 7. stop safely when authorization changes. This is the same durable trigger pattern described in [Matrix agent workflows](/blog/trigger-to-outcome-matrix-agent-workflows). ## Associate threads with work explicitly [#associate-threads-with-work-explicitly] The system needs to know which workspace owns a conversation. Useful association signals include: * a user explicitly attaches the thread, * participants match known project contacts, * a project-specific mailbox folder or label is used, * a stable reference appears in the subject or message, * the relationship owner confirms a suggestion. Participant overlap alone is not enough. The same adviser may appear across several mandates, and a person can discuss unrelated matters in one email chain. Matrix should store the provider thread ID and a source link, not silently copy every historical message into the project. The workspace index can materialize only the relevant content authorized for that task. ## Detect follow-up conditions, not just elapsed time [#detect-follow-up-conditions-not-just-elapsed-time] “No reply for two days” is a weak automation rule. A useful follow-up detector considers: * who owes the next action, * whether the last message asks a question or promises a deliverable, * the project stage and urgency, * business days and local holidays, * out-of-office responses, * whether a colleague replied elsewhere, * recent meetings or calls, * whether the owner dismissed an earlier reminder. The output should be a proposed task with evidence: ```text Suggested follow-up Reason: client requested revised figures; owner promised delivery Tuesday Last relevant message: source link Project status: figures approved, not yet sent Suggested owner: relationship owner ``` The agent can rank attention without pretending that every silent thread is overdue. ## Draft first, send later [#draft-first-send-later] Outlook supports creating a message or reply as a draft and sending it in a later operation. Gmail exposes composing and sending through authorization scopes. Matrix should exploit that separation. The initial action ladder can be: | Level | Capability | | ----- | -------------------------------------------------- | | 0 | Read approved metadata | | 1 | Read approved thread content | | 2 | Suggest a follow-up task | | 3 | Generate a Matrix draft | | 4 | Create a provider draft after review | | 5 | Send after explicit approval | | 6 | Policy-approved automatic sending for narrow cases | Most client-facing workflows should stop at level 4 or 5. Automatic sending belongs only to tightly bounded scenarios with tested templates, controlled recipients, clear opt-outs, and monitoring. ## The reviewer needs a communication brief [#the-reviewer-needs-a-communication-brief] The review screen should show more than the generated body: * intended recipients and CC list, * the exact thread being answered, * project and relationship owner, * facts and attachments referenced, * promises or deadlines introduced by the draft, * tone or language instructions, * differences from the approved template, * whether approval creates a draft or sends immediately. Recipients deserve special treatment. An agent should not add a new external recipient based only on text found in a message. Attachments should be checked against workspace and destination policy before they leave the organization. ## Keep sensitive content out of unnecessary memory [#keep-sensitive-content-out-of-unnecessary-memory] The email integration should separate: * provider message and thread identifiers, * minimal searchable metadata, * encrypted or ephemeral working content, * durable project facts explicitly accepted by a person, * generated drafts and approval history. Not every email body should become permanent company memory. Retention should follow the workflow purpose and company policy. When a source permission disappears, derived indexes should be invalidated and active workflows should lose access. This follows the same bounded-memory model we propose for [OneDrive and Google Drive](/blog/onedrive-google-drive-working-memory-ai-agents). ## Evaluate the assistant before expanding its authority [#evaluate-the-assistant-before-expanding-its-authority] Useful metrics include: * precision of “needs follow-up” suggestions, * dismissal and snooze rate, * percentage of drafts accepted with minor, major, or no edits, * recipient corrections, * factual correction rate, * time saved per accepted draft, * near misses caught during review, * messages sent without the required evidence or policy checks. The key progression is earned authority. A workflow should receive more automation only after its bounded use case performs reliably and its failure modes are understood. Email is not just another integration. It is where the company speaks. In a [shared Matrix workspace](/blog/shared-agent-workspaces-for-teams), agents can help colleagues notice and prepare communication while people retain authorship, judgment, and accountability. # Building the company OS for AI agents URL: /blog/company-os-ai-agents-series A practical guide to the Matrix architecture for shared workspaces, company data, reliable agent workflows, permissions, approvals, and review. A company OS for AI agents is a shared operating layer that connects the systems a business already uses to persistent agents, team workspaces, workflows, permissions, and human review. It is not another general-purpose chatbot, a replacement for every system of record, or an agent with unrestricted access to company data. It is the infrastructure that lets a company decide what agents know, what they may do, which outcomes require approval, and how colleagues work from the same state. This series explains the product and technical architecture Matrix OS is building toward. It is based on recurring customer needs across project-driven firms: lightweight deal tracking, shared files, email follow-up, project templates, document automation, controlled KYC operations, and one operational view for colleagues. The series describes our roadmap and design direction. Individual posts distinguish current Matrix foundations from capabilities we still intend to build. ## Why companies need an operating layer for agents [#why-companies-need-an-operating-layer-for-agents] Most companies already have systems of record: * OneDrive or Google Drive for files, * Outlook or Gmail for communication, * spreadsheets or CRMs for structured records, * project tools for plans and ownership, * templates for repeatable documents. Adding a separate AI assistant to each system can improve individual tasks, but it does not create shared operations. Context remains fragmented. One colleague cannot easily see what another person's agent did. Approvals live in messages. Generated work becomes detached from its evidence. The company OS provides the connective layer: | Layer | What it contributes | | ----------------- | ------------------------------------------------------------- | | Systems of record | Authoritative files, messages, contacts, and business records | | Matrix workspace | Shared project state, plans, drafts, decisions, and activity | | Agent runtime | Persistent execution, tools, skills, schedules, and recovery | | Trust layer | Identity, scoped permissions, policy, approval, and audit | | Human interface | Ownership, review, intervention, and collaboration | The premise extends our argument that [agents need a computer, not another chat box](/blog/cloud-computer-for-agents). Company agents need that computer to be shared, permission-aware, and accountable. ## Read the series by architectural layer [#read-the-series-by-architectural-layer] ### 1. Start with the company OS model [#1-start-with-the-company-os-model] The company OS model above connects existing systems rather than demanding a migration. It separates systems of record, the workspace, agent runtime, and human control. Read this first if you are evaluating the overall Matrix product direction or asking how business agents fit together beyond a single use case. ### 2. Make the workspace shared [#2-make-the-workspace-shared] [How we are building shared agent workspaces for entire teams](/blog/shared-agent-workspaces-for-teams) covers organization membership, project ownership, agent identities, roles, handoffs, review, and shared activity. Its central idea is simple: company work should belong to a durable project workspace rather than one employee's private assistant session. ### 3. Connect company files as working memory [#3-connect-company-files-as-working-memory] [OneDrive and Google Drive as working memory for AI agents](/blog/onedrive-google-drive-working-memory-ai-agents) is the technical integration design. It compares sync clients with provider APIs, then covers change feeds, stable file identity, permissions, indexing, provenance, and controlled write-back. Read it if your primary question is how agents can work with company files without copying an entire drive into an uncontrolled index. ### 4. Turn triggers into accountable outcomes [#4-turn-triggers-into-accountable-outcomes] [Building reliable company workflows with Matrix agents](/blog/trigger-to-outcome-matrix-agent-workflows) defines the execution loop: > Trigger → gather context → agent work → policy check → human review → action → shared record It applies that loop to KYC intake, monthly reporting, and email follow-up, including recovery, idempotency, and evaluation requirements. ### 5. Add the trust layer [#5-add-the-trust-layer] [Permissions, approvals, and audit for company AI agents](/blog/trust-layer-company-ai-agents) explains effective authority as the intersection of provider access, organization policy, workspace scope, agent capability, and run scope. It also describes action-bound approvals, evidence-rich audit records, workflow evaluations, prompt-injection boundaries, revocation, and incident recovery. ## Read the series by business workflow [#read-the-series-by-business-workflow] The architectural layers become easier to evaluate when applied to concrete work. ### Agent-native deal operations [#agent-native-deal-operations] [Building an agent-native deal workspace inside Matrix](/blog/agent-native-deal-workspace-matrix) brings deal flow, project templates, OneDrive, email, document generation, KYC status, agents, and colleague review into one operational view. It uses corporate finance as the example, but the same project shape appears in legal matters, consulting engagements, recruiting searches, audits, and complex sales. ### Lightweight operational CRM [#lightweight-operational-crm] [Building a lightweight, agent-native CRM inside Matrix](/blog/building-agent-native-crm-matrix) explains why spreadsheet-based teams may not want a heavyweight sales CRM. It proposes a small object model connected directly to project activity and agent workflows. ### Email follow-up [#email-follow-up] [How we would build safe email follow-up agents in Matrix](/blog/building-safe-email-agents) covers delegated Outlook and Gmail access, incremental mailbox updates, thread association, follow-up detection, provider drafts, recipient safety, and earned automation. ### Document automation [#document-automation] [Automating professional-services documents with AI](/blog/automating-professional-services-documents) separates locked language, templates, structured data, sourced facts, calculations, generated narrative, and professional judgment. It shows how to automate repeatable assembly while focusing review on the sections carrying risk. ### KYC operations [#kyc-operations] [Building AI-assisted KYC workflows with human review](/blog/building-ai-assisted-kyc-workflows) covers case-scoped access, document intake, classification, extraction, explicit exceptions, records, retention, and review. It deliberately keeps legal and compliance decisions with accountable people. ## The implementation sequence [#the-implementation-sequence] The posts describe a large product surface, but the build order can remain narrow: 1. Create one organization with members and roles. 2. Create one project workspace from a versioned template. 3. Connect one approved OneDrive or Google Drive folder. 4. Track source changes and provenance. 5. Run one durable reporting workflow. 6. Route the generated draft to an owner. 7. Publish the approved document back to the source system. 8. Record the complete activity and approval history. That path proves the identity, integration, workspace, runtime, review, write-back, and audit layers together. Email, CRM automation, and KYC operations can build on those same contracts. ## What we will measure [#what-we-will-measure] The company OS should be evaluated through operational outcomes, not the volume of agent activity. Useful measures include: * time from trigger to reviewed outcome, * percentage of runs requiring correction, * reviewer edit distance, * missing-source and stale-source detections, * policy denials and prevented duplicate actions, * time spent waiting for people or systems, * permission-revocation response time, * workspaces with a current owner and next step, * manual coordination removed from recurring workflows. The goal is not to maximize autonomy. It is to make useful work more continuous, shared, inspectable, and safe. ## The Matrix thesis [#the-matrix-thesis] Personal assistants begin with a conversation. The company OS begins with a workspace and an outcome. The systems a company trusts continue to own their records. Matrix supplies the persistent computer, integration boundary, shared project state, agent runtime, and human-control surface around them. That is how AI moves from isolated assistance into company infrastructure: one permissioned workspace and one accountable workflow at a time. # OneDrive and Google Drive as working memory for AI agents URL: /blog/onedrive-google-drive-working-memory-ai-agents How Matrix can connect company drives to agents with change feeds, scoped permissions, indexing, provenance, and controlled write-back. *Part of the [Matrix company OS series](/blog/company-os-ai-agents-series).* Company files already contain much of the context agents need. The difficult part is not uploading a PDF to a model. It is giving agents reliable, current, permission-aware access to thousands of changing files without creating a second uncontrolled document system. For Matrix OS, OneDrive and Google Drive should behave like connected working memory: searchable when authorized, traceable to the source, responsive to changes, and writable only through explicit policy. This post lays out the technical direction we are exploring. It is not an announcement that these integrations are generally available. ## The sync client is useful, but it is not the whole architecture [#the-sync-client-is-useful-but-it-is-not-the-whole-architecture] A Linux sync client can make cloud files look local. That is appealing because agents already know how to use a filesystem. It can also help with offline tooling, previews, and applications that expect paths. But a filesystem mirror alone does not answer the hardest questions: * Which user authorized access? * Did the source permission change? * Is the local file current? * Was an item deleted or merely moved? * Does a shared link grant access outside the workspace? * Which version did the agent use? * Should a local write update the source immediately? The more robust architecture combines provider APIs with a controlled local materialization layer. | Component | Purpose | | ------------------ | ------------------------------------------------------------------- | | Provider API | Identity, permissions, metadata, changes, and authoritative content | | Change processor | Converts provider events and cursors into durable internal events | | Metadata index | Tracks IDs, versions, locations, MIME types, and access state | | Content index | Stores permitted searchable representations and provenance | | Materializer | Produces local files only when a workflow needs them | | Write-back service | Applies reviewed changes with conflict and policy checks | The Matrix [storage model](/docs/guide/storage) remains useful for workspace artifacts. Connected drives remain external systems of record. ## Track files by stable identity, not only by path [#track-files-by-stable-identity-not-only-by-path] Paths are comfortable for people and fragile for synchronization. Folders are renamed. Files move. Two files can reuse the same name. Microsoft Graph's `driveItem` delta API returns a cursor for tracking changes over time and explicitly recommends tracking items by ID because renaming a folder does not cause every descendant to reappear with a new path. Google Drive's changes collection similarly returns the current state of changed files and uses stored page tokens to continue from a known point. Matrix should therefore maintain a provider-neutral record resembling: ```text provider: microsoft-graph tenant: organization-id drive: drive-id item: stable-item-id version: provider-version-or-etag location: human-readable-path permissions_version: observed-permission-state last_seen: timestamp ``` The human-readable path is presentation. The stable provider identity is the key. ## Use notifications to wake the system, then reconcile from a cursor [#use-notifications-to-wake-the-system-then-reconcile-from-a-cursor] Webhooks are signals, not a complete ledger. Microsoft Graph change notifications can tell an application that a resource was created, updated, or deleted. Subscription lifetimes vary by resource and subscriptions must be renewed. Microsoft also documents lifecycle events for reauthorization, removed subscriptions, and missed notifications. Google Drive's `changes.watch` sends a notification that new changes exist, but the notification does not contain the change details. The application must read the change feed using its saved page token. That leads to a resilient pattern: 1. Store the provider cursor durably. 2. Receive a notification or run a scheduled reconciliation. 3. Fetch every page after the stored cursor. 4. Process changes idempotently. 5. update the searchable representation and access state. 6. Commit the new cursor only after processing succeeds. 7. Periodically perform a broader reconciliation to detect drift. If a webhook is delayed or dropped, the cursor still recovers the sequence. If the same event arrives twice, idempotency prevents duplicate work. ## Index less than you can access [#index-less-than-you-can-access] An OAuth grant defines a technical maximum, not what every agent should automatically see. Matrix should separate four scopes: 1. **Provider grant:** what Microsoft or Google allows the integration to access. 2. **Organization policy:** which drives, sites, or folders may enter Matrix workflows. 3. **Workspace scope:** which sources are connected to a specific project. 4. **Run scope:** which items and operations an agent receives for one task. Both Microsoft and Google recommend least-privilege authorization. Google classifies some broad Drive scopes as restricted and recommends using the narrowest scope possible. Microsoft distinguishes user-delegated permissions from broader application permissions. The index should follow the same principle. Do not embed an entire tenant simply because an application permission makes it technically possible. Prefer explicit roots, metadata filters, and per-workspace inclusion. ## Retrieval needs provenance and freshness [#retrieval-needs-provenance-and-freshness] When an agent uses a passage, Matrix should be able to say where it came from. A retrieved chunk needs more than text and an embedding: * provider and stable file ID, * file name and source link, * observed version or ETag, * extraction timestamp, * page, sheet, slide, or section location, * workspace and permission context, * parser version, * classification or sensitivity metadata where available. Before a consequential action, the system can compare the indexed version with the provider's current version. If the source changed after retrieval, the run should refresh or ask for review rather than confidently acting on stale context. This is the difference between “memory” as a convenient model feature and memory as company infrastructure. ## Permissions can change independently of content [#permissions-can-change-independently-of-content] A file can remain byte-for-byte identical while its audience changes. That is why access-state reconciliation matters. Microsoft's OneDrive delta documentation includes mechanisms for identifying sharing changes in OneDrive for Business and SharePoint scenarios. Google Drive exposes permission resources and shared-drive behavior through its API. Matrix should treat these as security events: * remove inaccessible content from retrieval, * invalidate cached materializations, * stop or narrow active workflows, * record the policy transition, * avoid leaking the old content in summaries or derived indexes. Derived data is the hard case. If an agent generated a report from a file that later becomes inaccessible, the organization needs a retention policy for the report; deleting the source from the index does not automatically answer whether every derivative must disappear. ## Writes should be staged, version-aware, and reviewable [#writes-should-be-staged-version-aware-and-reviewable] Read access and write access should be separate product choices. A safe initial write path is: 1. Agent creates a workspace draft. 2. A person reviews the content and destination. 3. Matrix checks the destination permission and latest source version. 4. Matrix writes a new file or a new version according to policy. 5. The response ID, version, and link are recorded. Direct two-way folder synchronization can introduce rename loops, conflict copies, accidental deletions, and ambiguous ownership. It may be appropriate for selected workflows, but it should not be the default abstraction for agent writes. ## The first integration slice [#the-first-integration-slice] For a first OneDrive implementation, we would keep the surface intentionally narrow: * connect one organization through Microsoft identity, * select approved SharePoint or OneDrive folders, * index metadata and supported document text, * process changes incrementally through Graph, * materialize selected files into a Matrix workspace on demand, * generate drafts locally, * require review before writing to a designated output folder. Google Drive can follow the same provider-neutral contracts while using Google's scopes, change tokens, and shared-drive semantics. The result is not “mount every company file into an agent.” It is a controlled bridge between the company's source of truth and the [persistent environment where agents work](/blog/cloud-computer-for-agents). That bridge is a core part of [the company OS architecture](/blog/company-os-ai-agents-series): current context without uncontrolled copying, and useful automation without surrendering permissions or provenance. # How we are building shared agent workspaces for entire teams URL: /blog/shared-agent-workspaces-for-teams The product model for turning a personal cloud computer into a shared, permissioned workspace where colleagues and agents can coordinate work. *Part of the [Matrix company OS series](/blog/company-os-ai-agents-series).* The first generation of AI assistants is personal. You open your conversation, connect your account, and receive an answer that only you can see. That model breaks when the work belongs to a team. A colleague needs to know what the agent changed. A project owner needs to approve a client-facing document. Someone going on leave needs to hand over an active workflow without forwarding a pile of prompts. The company needs to remove access when a person leaves while retaining the project record. Matrix OS already provides a persistent workspace for files, terminals, apps, and agents. The next step is to make that workspace natively shared. This is a product design for capabilities on our roadmap. It describes how we believe team workspaces should behave, not only what is available today. ## The workspace belongs to the project [#the-workspace-belongs-to-the-project] Personal assistants make the user the owner of every interaction. A shared workspace makes the project the durable owner of its state. That means a project can outlive: * one chat session, * one agent or model, * one employee's access, * one device, * one integration token. The workspace holds the plan, connected resources, generated artifacts, approvals, and activity history. People and agents join it with scoped roles. This extends the architecture described in [Web 4 is an operating system](/whitepaper): interfaces come and go, but the computer and its state persist. For a company, identity and permissions must persist with that state too. ## People and agents need different identities [#people-and-agents-need-different-identities] An agent should never appear in the activity log as if it were the employee who launched it. We need distinct identities for: * organization members, * service accounts and integrations, * agents, * scheduled workflows, * external guests. Every action should record both the actor and the authority behind it. For example: “Reporting Agent created Draft 3 using Maria's delegated OneDrive access; Marcus approved it; the workflow stored the final file.” That chain is essential for trust. It lets a reviewer answer three different questions: 1. Who or what performed the operation? 2. Which permission allowed it? 3. Which person approved or owned the outcome? ## Roles should describe work, not infrastructure [#roles-should-describe-work-not-infrastructure] Traditional server permissions are too low-level for most teams. “Can write to this directory” does not explain whether someone may approve a client email. A Matrix team workspace needs product roles such as: | Role | Typical abilities | | ----------- | ------------------------------------------------------------- | | Owner | Configure the workspace, membership, policy, and integrations | | Operator | Start runs, assign work, resolve exceptions, and manage plans | | Reviewer | Read evidence and approve or reject bounded actions | | Contributor | Add context, files, comments, and task updates | | Viewer | Follow progress and inspect approved outputs | | Agent | Use explicitly granted tools within a run policy | The names may change, and organizations should eventually be able to customize them. The important point is that permissions map to meaningful actions. ## Sharing is more than simultaneous access [#sharing-is-more-than-simultaneous-access] Putting multiple people in the same interface is not collaboration. A shared agent workspace needs explicit coordination primitives. ### Ownership [#ownership] Every active run, task, and approval has an owner. “The AI is doing it” is not an ownership model. ### Presence and status [#presence-and-status] Colleagues can see whether work is queued, running, waiting for input, blocked, ready for review, or complete. Matrix already treats long-running sessions as inspectable work; team status makes that legible without opening every terminal. ### Handoffs [#handoffs] A handoff transfers responsibility while preserving context. The next person receives the goal, current state, relevant sources, unresolved decisions, and recent actions—not a summary pasted into a new chat. ### Review [#review] Review is an object with a proposed action, evidence, risk level, reviewer, decision, and timestamp. It should not be buried in a message thread. ### Notification [#notification] Matrix can surface the same workspace through different shells. A reviewer might receive a notification in [Matrix Messages](/docs/messages), open the workspace on [mobile](/docs/mobile), and inspect the full artifact on the desktop. ## Integrations must remain user-aware [#integrations-must-remain-user-aware] External systems already have their own access models. The team workspace should preserve them rather than flattening them. Microsoft Graph's delegated access model limits an application to data the signed-in user can access, while application permissions allow background access without a user. That difference should be visible in Matrix. A delegated connection might support personal email follow-up drafts. A company-administered application connection might support a shared reporting process. The workspace should show which mode a workflow uses, who consented, what scopes were granted, and when the grant expires or changes. When a member loses access to a OneDrive folder, Matrix must not keep presenting stale indexed content as if the access still exists. When an integration is disconnected, dependent workflows should stop safely and explain what they need. ## Shared memory should be inspectable [#shared-memory-should-be-inspectable] Team memory is not one giant vector database. We see at least four kinds of memory: * **Source references:** links to authoritative files, messages, and records. * **Workspace state:** plans, owners, statuses, decisions, and approvals. * **Working artifacts:** drafts, extracted data, intermediate calculations, and notes. * **Organization knowledge:** reusable policies, templates, terminology, and skills. Each kind has a different retention and permission boundary. Source references follow the source system. Workspace state belongs to the project. Working artifacts may be temporary. Organization knowledge should be versioned and curated. The current [Matrix file system model](/docs/guide/file-system) gives agents and users inspectable artifacts. Team workspaces extend that principle: shared memory should be visible, attributable, and removable. ## Activity history is part of the interface [#activity-history-is-part-of-the-interface] Most products hide audit logs in an administrator screen. For agentic work, the activity record should be part of the everyday product. A useful project timeline might show: * a new source file was detected, * a workflow extracted required fields, * the agent flagged a missing item, * a colleague supplied the item, * the agent generated a draft, * a reviewer requested a change, * the final action was approved and completed. That history is both operational and evaluative. Teams can find bottlenecks, understand why an output exists, and improve the instructions that produced it. ## The first team workspace we want to prove [#the-first-team-workspace-we-want-to-prove] The smallest credible team version is not a general social network. It is one shared project with: * organization membership, * a workspace template, * connected resources, * assigned agents and owners, * a common activity timeline, * a queue for input and approvals, * permission-aware links to source material. If a colleague can open the workspace and answer “what is happening, what needs me, and what changed?” without asking the person who started the workflow, we have crossed the important line from personal assistant to company infrastructure. Shared AI should not mean that everyone shares a chatbot. It should mean that people and agents share an accountable place to work. Read the broader architecture in [building a company OS on existing tools](/blog/company-os-ai-agents-series), then see how files can become [permission-aware working memory for agents](/blog/onedrive-google-drive-working-memory-ai-agents). # Building reliable company workflows with Matrix agents URL: /blog/trigger-to-outcome-matrix-agent-workflows A practical architecture for reliable agent workflows that gather context, produce work, request human review, take action, and leave a shared record. *Part of the [Matrix company OS series](/blog/company-os-ai-agents-series).* “Automate our reporting” sounds like one task. In practice, it is a chain of decisions spread across several systems. The workflow must know when to start, which projects count, where the latest numbers live, what changed since last month, which template to use, who must review the draft, where the approved report belongs, and who should receive it. A model can write the prose. The product challenge is reliably moving from a trigger to an accountable outcome. We are designing Matrix workflows around a simple loop: > **Trigger → gather context → agent work → policy check → human review → action → shared record** This post describes a roadmap architecture. The workflow surface discussed here is a direction for Matrix OS, not a statement that every trigger and connector is currently available. ## Start with a goal, not an automation canvas [#start-with-a-goal-not-an-automation-canvas] Workflow products often begin with boxes and arrows. Users usually begin with an outcome. * “When KYC documents arrive, organize them and tell me what is missing.” * “Every month, prepare a project report for review.” * “When a client email has no reply after two business days, draft a follow-up.” Matrix should capture five things before generating a workflow: 1. **Trigger:** What observable event or schedule starts the work? 2. **Outcome:** What artifact or state means the work is complete? 3. **Sources:** Which systems and records may the workflow use? 4. **Policy:** What may happen automatically, and what requires approval? 5. **Owner:** Which person is responsible when the workflow cannot decide? The system can propose the intermediate steps, but those five fields define the contract. ## Model the workflow as durable state [#model-the-workflow-as-durable-state] Agent work is nondeterministic; workflow state should not be. A run needs an explicit state machine: ```text queued -> gathering_context -> working -> awaiting_input | awaiting_review -> acting -> complete -> failed | canceled ``` Each transition records its inputs, outputs, actor, and timestamp. Long waits are normal. A run may pause for a client document for three days or for a partner's approval until Monday. The persistent computer model behind [Matrix cloud coding](/docs/guide/cloud-coding) already keeps processes and artifacts available beyond one browser session. Company workflows add durable business state above those processes so work can resume without guessing what happened before an interruption. ## Triggers wake workflows; they do not decide outcomes [#triggers-wake-workflows-they-do-not-decide-outcomes] Triggers can come from: * a schedule, * a new or changed file, * an incoming email, * a form submission, * a changed CRM record, * a person pressing Run, * another workflow completing. Provider notifications are not always complete event payloads. Google Drive, for example, documents that change notifications indicate that new changes exist; the application then reads the changes feed. Microsoft Graph subscriptions expire and must be renewed, and lifecycle notifications can signal missed events or required reauthorization. Matrix should therefore convert external triggers into internal, deduplicated events. The event wakes a workflow, which then reconciles authoritative state before acting. This avoids fragile assumptions such as “one webhook equals one new file” or “no webhook means nothing changed.” ## Gather only the context required for this run [#gather-only-the-context-required-for-this-run] The context step resolves references at execution time: * current project plan, * files in approved source folders, * relevant email thread, * last accepted report, * company template and instructions, * known exceptions and prior reviewer feedback. It also records versions. If a document changes while an agent is working, the workflow can refresh, flag the conflict, or require a new review. This is where [OneDrive and Google Drive as agent working memory](/blog/onedrive-google-drive-working-memory-ai-agents) connects to the workflow runtime. The agent receives bounded context with provenance instead of broad, invisible access to a company corpus. ## Separate reasoning from authority [#separate-reasoning-from-authority] An agent can decide that an email is probably ready. That does not mean it should have the authority to send it. Matrix workflows should represent actions as proposals: ```text action: send_email recipient: client@example.com draft: workspace://follow-up-3 evidence: [thread, project-status, company-policy] risk: external-communication required_review: project-owner ``` Policy then determines whether the proposal can execute automatically, requires one reviewer, requires two reviewers, or is prohibited. This separation lets companies change their risk posture without rewriting every prompt. Internal folder organization might be automatic. External communication might always require approval. A workflow involving identity documents might require a designated compliance role. ## Design the human review around the decision [#design-the-human-review-around-the-decision] “Approve this agent run” is too vague. A reviewer should see: * the exact proposed action, * the artifact or diff, * the sources used, * unresolved uncertainty, * policy checks, * the consequence of approval, * the person who owns the workflow. The review surface should make rejection useful. A reviewer can correct data, edit the draft, change the destination, provide an instruction, or stop the workflow. That feedback becomes structured evidence for improving the template or skill later. The team experience belongs in a [shared agent workspace](/blog/shared-agent-workspaces-for-teams), where colleagues can find pending decisions without tracking down the person who launched the run. ## Three workflows to prove the model [#three-workflows-to-prove-the-model] ### 1. KYC document intake [#1-kyc-document-intake] **Trigger:** New files arrive in an approved client folder. **Context:** Required-document checklist, client record, file metadata, and current folder state. **Agent work:** Classify files, extract bounded fields, detect duplicates, and identify missing or expired items. **Review:** A designated person checks ambiguous classifications and any proposed client request. **Action:** Organize approved files and update the checklist. **Record:** Sources, extracted fields, exceptions, reviewer decision, and final location. The agent assists the process; it does not determine whether the company has satisfied its legal obligations. ### 2. Monthly project reporting [#2-monthly-project-reporting] **Trigger:** A monthly schedule. **Context:** Project plan, completed work, open risks, financial inputs, prior report, and current template. **Agent work:** Reconcile sources, draft narrative sections, and flag missing inputs. **Review:** Project owner edits and approves the report. **Action:** Save the approved version and notify the distribution list. **Record:** Source versions, changes from prior month, approvals, and final document link. ### 3. Email follow-up preparation [#3-email-follow-up-preparation] **Trigger:** An owned client thread has no reply after a configured period. **Context:** Thread, deal stage, promised next step, calendar context, and communication policy. **Agent work:** Decide whether a follow-up is appropriate and prepare a draft. **Review:** The relationship owner approves or dismisses it. **Action:** Create an Outlook draft first; sending can remain a separate approval. **Record:** Why the follow-up was suggested, sources, final copy, and outcome. ## Reliability is a product feature [#reliability-is-a-product-feature] A serious workflow runtime needs more than retries. * **Idempotency:** Replayed events do not duplicate emails or files. * **Checkpoints:** Long runs resume from completed stages. * **Timeouts:** Waiting states escalate to a person instead of hanging forever. * **Compensation:** Partial actions have a documented recovery path. * **Version checks:** Writes do not silently overwrite newer work. * **Observability:** Owners can see latency, failures, and review bottlenecks. * **Evaluation:** Teams can sample outputs and track correction rates over time. NIST's Generative AI Profile emphasizes governance, measurement, and management alongside model capability. In product terms, an automated workflow should expose enough evidence to evaluate whether it remains safe and useful after launch. ## Build one complete outcome at a time [#build-one-complete-outcome-at-a-time] The temptation is to ship a large gallery of triggers and actions. We would rather prove a small number of complete workflows. A complete workflow handles the happy path, missing input, revoked access, conflicting versions, reviewer changes, API failure, cancellation, and audit history. Only then does it become company infrastructure. Matrix already provides the foundation: a [persistent computer for agents](/blog/cloud-computer-for-agents), files, apps, long-running sessions, and multiple interfaces. The company workflow layer turns those primitives into repeatable outcomes that colleagues can own together. The goal is not to remove people from the loop. It is to remove the coordination work that prevents people from exercising judgment where it matters. Next, see how these primitives come together in [an agent-native deal workspace](/blog/agent-native-deal-workspace-matrix), then examine the shared [permissions, approvals, and audit layer](/blog/trust-layer-company-ai-agents) underneath every workflow. # Permissions, approvals, and audit for company AI agents URL: /blog/trust-layer-company-ai-agents A Matrix architecture for governing what company agents can know and do, when people must review them, and how outcomes remain traceable. *Part of the [Matrix company OS series](/blog/company-os-ai-agents-series).* Companies will not trust agents because the model sounds careful. They will trust a system when its authority is bounded, its actions are reviewable, and its failures are recoverable. That trust cannot live in one system prompt. It needs a product layer spanning identity, permissions, data access, action policy, approvals, logs, evaluations, and incident response. We think of this as the **trust layer** of the company OS. This post describes the architecture we want to build into Matrix OS. It is a roadmap direction rather than a claim that every enterprise control below exists today. ## Identity comes before autonomy [#identity-comes-before-autonomy] Every operation needs an actor. Matrix should distinguish: * a human organization member, * an external guest, * a connected provider identity, * an agent, * a workflow definition, * a specific workflow run, * an organization-owned service connection. An agent run does not become the employee who launched it. The record should preserve both identities: the agent performed the step; the employee or policy supplied its authority. This is the foundation of the [shared workspace design](/blog/shared-agent-workspaces-for-teams). Without distinct identities, permissions and audit become stories rather than facts. ## Permission is an intersection [#permission-is-an-intersection] An agent's effective access should be the intersection of several grants: ```text provider permission ∩ organization policy ∩ workspace scope ∩ agent capability ∩ workflow run scope = effective authority ``` If OneDrive allows a user to read a site but the Matrix workspace is connected only to one folder, the agent receives the folder. If the workflow is a read-only report, it receives no write action even when the provider token technically supports one. Microsoft and Google both recommend least-privilege scopes. Matrix should go further by narrowing broad provider grants at the product layer. ## Capabilities are safer than generic tools [#capabilities-are-safer-than-generic-tools] “Microsoft Graph access” is not a useful policy unit. “Read files from Project North” or “create an Outlook draft for the relationship owner” is. A capability definition needs: * action and resource pattern, * permitted actor types, * workspace boundary, * input constraints, * output and destination constraints, * required evidence, * review rule, * rate or volume limits, * expiration. Agents receive capabilities for a run rather than long-lived provider credentials. The execution service holds the integration secret and validates every request against policy. This separation also protects customer VPSes: provider credentials remain in the integration boundary rather than being exposed to arbitrary shell processes. ## Approvals should bind to exact actions [#approvals-should-bind-to-exact-actions] An approval is meaningful only if the reviewed object cannot silently change afterward. A Matrix approval should bind to: * action type, * exact content or content hash, * recipients or destination, * source versions, * policy version, * expiration time, * reviewer identity. If the draft changes, the recipient changes, or a material source changes, the approval becomes stale. The workflow must request a new decision. Approval policies can vary: | Risk | Example | Policy | | ---------- | ------------------------------ | ----------------------------- | | Low | Update internal derived status | Automatic with log | | Medium | Create a provider draft | Owner review | | High | Send external communication | Explicit approval | | Restricted | Export identity documents | Designated role or prohibited | The agent proposes. Policy authorizes. The executor acts. ## Audit needs evidence, not just prose [#audit-needs-evidence-not-just-prose] “Agent completed the task” is not an audit record. Every consequential step should capture: * actor and authority, * timestamp and workspace, * tool or capability invoked, * normalized request and result, * source IDs and observed versions, * policy decision, * approval where required, * generated artifact or diff, * failure and retry history, * correlation ID across the run. Logs should minimize unnecessary sensitive content. A source ID and hash may be enough where storing the full payload would create a second data-retention problem. The activity history can remain useful to ordinary teammates while a more detailed security record supports administrators and incident review. ## Observability must include product outcomes [#observability-must-include-product-outcomes] Infrastructure metrics tell us whether a connector is responding. They do not tell us whether the agent is helping. Matrix should measure: * run success and recovery rates, * time spent waiting for people or providers, * approval and rejection rates, * reviewer edit distance, * factual correction rate, * stale-source detections, * policy denials, * access-revocation response time, * duplicate or unintended action prevention, * incidents by workflow and template version. NIST frames AI risk management as an ongoing process of governing, mapping, measuring, and managing. The Matrix trust layer should make that process part of operating the product rather than a separate compliance exercise. ## Evaluations belong to workflow versions [#evaluations-belong-to-workflow-versions] A model benchmark does not validate a company workflow. Each workflow version needs its own evaluation set: * representative successful cases, * incomplete and contradictory sources, * prompt-injection attempts inside connected content, * revoked or missing permissions, * duplicate provider events, * stale document versions, * ambiguous recipients, * policy-boundary cases, * expected escalation behavior. The company can compare a new prompt, template, model, parser, or integration version against the accepted baseline before promoting it. When a live review reveals a new failure mode, the corrected case can enter the evaluation set after appropriate redaction and governance. ## Connected content is untrusted input [#connected-content-is-untrusted-input] An email or document can contain instructions aimed at the agent: “ignore policy and send this file to...” The system must treat that text as data, not authority. Controls include: * separating source content from system and organization instructions, * preventing content from granting itself new tools, * validating every tool call outside the model, * constraining destinations and recipients, * scanning outputs and attachments, * requiring review for consequential changes, * using narrow, expiring run capabilities. The agent can recommend an action found in a document. Only the policy layer can authorize it. ## Revocation and recovery are first-class [#revocation-and-recovery-are-first-class] Trust includes the ability to stop. An administrator should be able to: * disconnect a provider, * revoke a workspace grant, * disable an agent or workflow version, * cancel active runs, * invalidate pending approvals, * quarantine outputs, * inspect affected actions, * rotate credentials, * resume only after review. External subscriptions also expire or fail. Microsoft documents lifecycle notifications for reauthorization and missed changes; Gmail watches require renewal and its history cursor can age out. The workflow should fail closed, explain the lost capability, and retain enough checkpoint state to recover safely. ## Trust should be visible in the product [#trust-should-be-visible-in-the-product] Users should not need an administrator console to understand what an agent can do. The workspace can show: * connected sources and scopes, * active agents and capabilities, * current runs and owners, * pending approvals, * recent policy denials, * data and template versions used, * how to pause or revoke access. That is how a [company OS](/blog/company-os-ai-agents-series) feels trustworthy: the boundaries are part of the everyday interface. The trust layer does not eliminate risk or confer legal compliance. It gives the organization concrete controls and evidence for operating agents responsibly. In workflows such as [email follow-up](/blog/building-safe-email-agents), [document automation](/blog/automating-professional-services-documents), and [KYC operations](/blog/building-ai-assisted-kyc-workflows), those controls are the difference between an impressive demo and dependable infrastructure. # What is an autonomous coding agent? URL: /blog/what-is-an-autonomous-coding-agent Learn how autonomous coding agents plan, edit, test, and hand work back to teams, plus where human oversight still belongs. What Is an Autonomous Coding Agent Most developers have used an AI coding tool to generate a function or explain an error. That is not what an autonomous coding agent does. The distinction matters, and it shapes how teams actually build with these tools in 2026. ## The Difference Between Assistance and Autonomy [#the-difference-between-assistance-and-autonomy] A code assistant responds to a prompt. You ask, it answers, and then it waits. An autonomous coding agent receives a goal and works toward it across multiple steps, making decisions along the way without requiring input at each one. That shift from prompt-response to goal-execution changes the unit of work. Instead of asking an agent to write a function, you ask it to fix the failing tests in a given module, push a branch, and open a draft PR when done. The agent reads the codebase, runs the tests, makes changes, reruns the tests, and handles the full sequence on its own. The degree of autonomy varies by agent and by task. Some handle narrow, well-scoped work reliably. Others navigate larger codebases with less hand-holding. The practical ceiling in 2026 is not model intelligence — it is the environment the agent runs in. ## What an Autonomous Coding Agent Actually Does [#what-an-autonomous-coding-agent-actually-does] At the mechanics level, an autonomous coding agent combines a language model with a set of tools: reading and writing files, running shell commands, calling APIs, searching a codebase, and observing the output of its own actions. The agent loop works roughly like this: * receives a task description * plans a sequence of steps * executes each step using available tools * observes the result and adjusts * continues until the task is complete or human input is needed The tools available to the agent define what it can do. An agent with only file read/write access is limited. An agent with shell access, a running dev server, and access to your issue tracker can do substantially more. ## Common Agents Teams Use in 2026 [#common-agents-teams-use-in-2026] Several autonomous coding agents have become standard in developer workflows. Claude Code, developed by Anthropic, operates in the terminal and handles complex, multi-file tasks with strong reasoning about code structure. OpenAI's Codex CLI brings similar capabilities from the command line. Cursor's agent mode works within the editor. Gemini CLI and OpenCode round out the common options. Each has different strengths, pricing models, and context window behaviors. Teams that have moved past experimenting with a single agent often end up using two or three for different task types — which creates an environment problem that is separate from the agent quality question. ## How Teams Actually Use Autonomous Coding Agents [#how-teams-actually-use-autonomous-coding-agents] ### Bug Triage and Remediation [#bug-triage-and-remediation] One of the most reliable uses is directing an agent at a failing test or a Sentry error and asking it to trace the cause, propose a fix, and apply it. The agent reads the stack trace, navigates the relevant files, makes the change, and runs the test suite. A developer reviews the diff rather than doing the investigation themselves. This works well because the task is bounded. The success condition is clear: the test passes, or the error no longer reproduces. The agent has a concrete signal to work toward. ### Background Code Review and Refactoring [#background-code-review-and-refactoring] Teams use agents for refactoring work that is well-understood but time-consuming: updating deprecated API calls across a codebase, migrating to a new library version, standardizing error handling patterns. These tasks do not require continuous developer attention. They require a capable agent, a clear brief, and a persistent environment to run in. The persistent environment part is where most setups break down. If the agent runs on a laptop, the work stops when the machine sleeps. If it runs in a short-lived sandbox, the session expires before the task finishes. The work needs somewhere to live that does not depend on a local device staying on. ### Parallel Task Execution [#parallel-task-execution] More advanced teams run multiple agents simultaneously against different parts of the codebase. One agent handles a bug fix on a feature branch while another drafts documentation for a recently merged module. Because the agents work in isolated sessions with shared file state, the outputs do not collide. This is where environment architecture becomes a first-class concern. Running Claude Code and Codex simultaneously on the same machine, against the same repository, requires a setup most developers do not have by default. ### Scheduled and Triggered Workflows [#scheduled-and-triggered-workflows] Some agent work does not need to happen right now. It needs to happen at 2 AM before the morning standup, or when a new issue is filed in Linear, or when a staging deployment fails. Scheduled and event-triggered agent tasks are a meaningful part of how teams reduce the manual overhead of recurring work. This requires an agent that is always available to receive a trigger — not one that spins up on demand with no memory of prior context. ## The Environment Problem [#the-environment-problem] The agent is only as useful as the environment it runs in. A well-scoped task given to a capable agent will still fail if the environment has no persistent state, no access to the right tools, or no way to run across a multi-hour window. This is the practical constraint that separates teams getting real output from agents versus teams still experimenting. The question is not which agent is best. The question is where the agent runs, what it has access to, and whether the session survives long enough to finish the work. Running agents locally is the default, but it ties the agent's availability to the developer's machine. [Keeping Claude Code running after your laptop closes](/blog/keep-claude-code-running-after-laptop-closes) requires a different approach entirely — one where the compute lives in the cloud and the local device is just a viewer. ## What a Persistent Cloud Environment Changes [#what-a-persistent-cloud-environment-changes] When the agent runs on a dedicated cloud computer rather than a local machine, several things become possible that were not before. Tasks can run overnight without a developer staying at their desk. Multiple agents can run in parallel on the same machine, sharing a filesystem and a database, without interfering with each other. The developer can check progress from a phone, close the browser, and return to find the work continuing. The environment also becomes portable. The files, the running processes, the agent sessions — they belong to the developer, not to the agent provider. Switching from Claude Code to Codex for a particular task does not mean rebuilding the environment from scratch. That framing is what [Matrix OS](https://matrix-os.com) is built around: a dedicated cloud computer where autonomous coding agents run in persistent sessions. The agent is replaceable. The environment belongs to the user. That separation is what makes multi-agent workflows practical rather than theoretical. See [current Matrix plans and resources](/#pricing) and the terms displayed at checkout. Choose the computer lifecycle and capacity required by your workload; agent-provider access can have separate costs. The Symphony orchestration layer handles parallel task queues, agent status tracking, and branch and PR review. Hermes, a resident agent built into Matrix, handles scheduled workflows, tool connections, and approval routing. The full web shell is accessible from any browser. For teams running more than one agent, or doing work that needs to survive a laptop closing, the [cloud computer model](/blog/cloud-computer-for-agents) is a different architecture than a sandbox or an IDE plugin. It is closer to what teams end up building themselves on a raw VPS — without that maintenance becoming a separate engineering job. ## Where Human Oversight Fits [#where-human-oversight-fits] Autonomous does not mean unsupervised. The most productive teams using coding agents in 2026 treat human oversight as a design decision, not an afterthought. The practical pattern is human-in-the-loop at decision points: the agent works autonomously through execution steps, but a developer reviews the diff before a PR is opened, or approves a destructive operation before it runs. The agent handles investigation and implementation. The developer handles judgment calls. This requires tooling that makes it easy to inspect what the agent did, not just what it produced. A diff view, a task log, and a clear handoff point are the minimum. Teams that skip this end up with agents that produce output no one trusts enough to ship. ## Choosing Tasks That Fit [#choosing-tasks-that-fit] Not every task is a good fit for an autonomous agent. Tasks that work well share a few properties: the success condition is observable, the scope is bounded, the agent has access to the tools it needs, and the cost of a wrong step is recoverable. Tasks that do not work well: anything requiring aesthetic judgment without a clear rubric, anything that depends on context the agent cannot read, anything where a wrong action is irreversible without a checkpoint. The practical skill is not prompt engineering. It is task decomposition — breaking work into pieces that fit the agent's actual capabilities and the environment's actual constraints. *** ## Frequently Asked Questions [#frequently-asked-questions] **What is the difference between an AI code assistant and an autonomous coding agent?** A code assistant responds to individual prompts and waits for the next one. An autonomous coding agent receives a goal and works through multiple steps to complete it — using tools like file access, shell commands, and API calls — without requiring input at each step. **Which autonomous coding agents are commonly used in 2026?** Claude Code, OpenAI Codex CLI, Cursor's agent mode, Gemini CLI, and OpenCode are the most widely used. Each has different strengths. Teams often use more than one depending on the task type. **Why does the environment matter as much as the agent?** The agent can only do what its environment supports. If the session expires, the machine sleeps, or the agent lacks access to the right tools, the task fails regardless of model quality. Persistent, well-provisioned compute is what separates reliable agent output from unreliable experimentation. **How do teams run multiple agents simultaneously?** Running multiple agents in parallel requires isolated sessions on a shared machine with a common filesystem. This is not the default setup for most developers. It requires either a self-managed remote server or a platform purpose-built for multi-agent execution. **What does human-in-the-loop mean in an agent workflow?** The agent handles execution steps autonomously but pauses at defined decision points for human review or approval. Common checkpoints include reviewing a diff before a PR is opened, approving a destructive file operation, or confirming a deployment. **What tasks are best suited for autonomous coding agents?** Bug triage and remediation, refactoring across a codebase, documentation generation, and scheduled maintenance tasks all fit well. The common properties are a clear success condition, bounded scope, tool access, and recoverable failure states. **Does an autonomous coding agent need to run on a local machine?** No. Running agents locally is the default, but it ties availability to the developer's machine. Cloud-hosted environments let agents run continuously in persistent sessions without depending on a laptop staying on — which is necessary for overnight tasks, parallel workloads, and multi-agent setups. # What to test during a Matrix OS free trial URL: /blog/matrix-os-free-trial Understand Matrix trial eligibility, the card requirement, checkout and renewal, then test one complete cloud-computer workflow. Creating a Matrix account and starting a hosted computer are separate steps. Eligible first-time customers can start a **three-day trial for their first primary cloud computer**. A card is required. Checkout shows the amount due today, the trial deadline and the selected monthly price that will apply unless you cancel first. ## Check the offer before you start [#check-the-offer-before-you-start] Use [current Matrix pricing](/#pricing) and the offer displayed at checkout as the reference for plan prices, resources, region options and eligibility. Product plans can change; this guide deliberately does not maintain another price table. The first-primary-computer offer is not a trial for every computer. Additional computers and accounts that are not eligible follow the terms displayed during their checkout. Creating an account alone does not provision a running machine. ## Start your first computer [#start-your-first-computer] 1. Open [Matrix Cloud](https://app.matrix-os.com) and sign in. 2. Choose a plan and available region appropriate for your workload. 3. Review the checkout amount, card requirement, trial end and renewal price. 4. Complete checkout and wait for the computer to become ready. 5. Open Terminal and authenticate the agent you want to use. The [quickstart](/docs/quickstart) covers the full path. To use the native client, follow [desktop installation and browser approval](/docs/desktop). The desktop app connects to your cloud computer; installing it does not itself provision compute or authenticate every coding agent. ## Evaluate one complete workflow [#evaluate-one-complete-workflow] Choose one repository and a small, observable result. For example, ask an agent to fix one failing test, run the tests and explain its diff. Start with sample data and the access required for that task. During the trial, check: | Question | Evidence to inspect | | --------------------------------------- | -------------------------------------------------------------------- | | Can I start my agent? | Successful authentication and a real command completing. | | Does the environment fit my repository? | Dependencies install and the normal test command runs. | | Can I reconnect? | The same named session and an inspectable output or saved file. | | Can I review the result? | A diff, test log and files you can open. | | Does the plan fit? | Adequate resources and lifecycle behavior for the intended workload. | Remote compute can continue independently of your laptop while the computer and process remain running. It does not guarantee task completion, uninterrupted provider access or automatic recovery after every failure. Test the behavior you depend on before leaving important work unattended. ## Understand the separate costs [#understand-the-separate-costs] The Matrix computer and an agent's inference access are separate parts of the setup. Bring or configure the supported agent credentials and review that provider's terms. A running computer does not automatically mean every agent is authenticated or funded. Choose a plan from the current resource and lifecycle descriptions. A small supervised experiment and sustained parallel background work can have different requirements. Do not assume the cheapest computer has the same background behavior as every other plan. ## What happens when the trial ends? [#what-happens-when-the-trial-ends] Unless you cancel before the displayed deadline, the selected paid plan begins according to checkout. Use the supported billing management flow described in [Settings and billing](/docs/settings-billing), and verify the cancellation status and effective date shown there. If the offer or price shown in your account differs from an older article, use your current checkout and billing screen. Contact [Matrix support](/contact) when the account state needs clarification. ## Frequently asked questions [#frequently-asked-questions] ### Is the trial card-free? [#is-the-trial-card-free] No. The eligible hosted-computer trial requires a card. Account creation and documentation access are separate from starting hosted compute. ### Does every new computer receive a trial? [#does-every-new-computer-receive-a-trial] No. The offer applies to an eligible first primary computer. Review the terms for additional computers before confirming checkout. ### Can I use the desktop app during the trial? [#can-i-use-the-desktop-app-during-the-trial] Yes, once the computer is ready and the desktop has been approved through your browser. See the [desktop guide](/docs/desktop). ### What should I do before the trial deadline? [#what-should-i-do-before-the-trial-deadline] Finish the bounded test, review the result and decide whether the selected plan fits. If it does not, cancel before the displayed deadline and check the billing confirmation. ### What is the fastest useful test? [#what-is-the-fastest-useful-test] Follow [the Claude Code setup and reconnect walkthrough](/blog/keep-claude-code-running-after-laptop-closes), using a small repository task with a result you can inspect. # Cursor Background Agents vs Matrix OS URL: /blog/point-cursor-background-agent-at-matrix-os Understand where Cursor Background Agents run, when to use them, and when a persistent Matrix OS computer is the better fit. Cursor Background Agents and Matrix OS Cursor Background Agents already run on remote infrastructure managed through Cursor. You do not point that managed runtime at an arbitrary SSH host, and you do not need to keep your laptop awake while a background task runs. Check [Cursor's Background Agent documentation](https://docs.cursor.com/background-agent) for current runtime, security, and repository-access details. Matrix OS solves a related but different problem. It gives you a persistent computer where you can run terminal agents such as Claude Code, Codex CLI, Gemini CLI, and OpenCode, keep the repository and tools in place, and inspect the same workspace from a browser or terminal. The useful question is therefore not how to install a Cursor Background Agent on Matrix OS. It is which runtime model fits the work. ## How do Cursor Background Agents work? [#how-do-cursor-background-agents-work] A Cursor Background Agent receives a task, works in a remote environment, and returns a branch or pull request for review. Cursor owns the agent experience and the surrounding runtime. That makes it a convenient choice when your team already works in Cursor and wants a task-oriented handoff without operating another machine. The tradeoff is control. The environment is part of Cursor's product, so its lifecycle, supported configuration, and review flow follow Cursor's model. Treat details such as available regions, base images, network controls, and pricing as product settings that may change. ## What does Matrix OS provide instead? [#what-does-matrix-os-provide-instead] Matrix OS provisions a durable computer rather than a job-specific agent environment. The repository, shells, dev servers, logs, and artifacts remain on that computer between sessions. You choose which terminal agents to install and how to divide work between them. That model is useful when: * several agents need separate worktrees against the same repository, * a dev server or database needs to stay available between tasks, * the team wants direct shell and filesystem access, * work needs to continue independently of a developer's laptop, * artifacts should remain inspectable after an agent finishes. Matrix does not turn Cursor's managed Background Agent into a self-hosted agent. You can still use Cursor as an editor or remote development client where its supported workflows allow, while running terminal-native agents directly on the Matrix computer. ## Cursor Background Agents and Matrix OS compared [#cursor-background-agents-and-matrix-os-compared] | Question | Cursor Background Agents | Matrix OS | | ----------------- | ----------------------------------- | --------------------------------------------- | | Primary unit | Delegated task | Persistent computer and workspace | | Runtime owner | Cursor | Matrix Cloud or your self-hosted environment | | Agent choice | Cursor's agent workflow | Terminal agents you install | | Repository state | Prepared for the task | Remains on the computer | | Shell access | Through Cursor's supported workflow | Direct browser and terminal access | | Multi-agent setup | Managed within Cursor | Separate sessions and worktrees you control | | Best fit | Cursor-centric task delegation | Durable, agent-agnostic development workspace | This is not a quality ranking. The two products draw the boundary in different places. ## When should you choose a Cursor Background Agent? [#when-should-you-choose-a-cursor-background-agent] Choose Cursor's managed agent when the task is well scoped, the repository can be prepared in its environment, and the desired output is a branch or pull request. It is the shorter path for teams that want Cursor to own both the agent and the runtime. Before using it on a private repository, review Cursor's current documentation for data handling, network access, secrets, and repository permissions. Give the agent only the access required for the task. ## When should you choose Matrix OS? [#when-should-you-choose-matrix-os] Choose Matrix when you want a computer that remains useful across many tasks and agents. It is especially relevant when local environment setup is expensive, several agents need coordinated branches, or the team wants to inspect running processes and files directly. A practical setup is one worktree per agent, one named terminal per task, and a normal pull-request review queue. The cloud computer supplies uptime; Git supplies isolation and an auditable handoff. See [Git worktrees for AI coding agents](/blog/git-worktrees-for-coding-agents) for the repository pattern and [Agents need a computer, not another chat box](/blog/cloud-computer-for-agents) for the product model. ## Can the two be used together? [#can-the-two-be-used-together] Yes, but as adjacent tools rather than one runtime hosting the other. A team can delegate suitable tasks to Cursor Background Agents while using Matrix for terminal agents, persistent services, or work that requires a controlled long-lived environment. Keep branches isolated and merge through the same review process. The important distinction is ownership: Cursor runs its Background Agents; Matrix hosts the agents and processes you run on your Matrix computer. ## FAQs [#faqs] ### Can I point a Cursor Background Agent at a Matrix OS SSH host? [#can-i-point-a-cursor-background-agent-at-a-matrix-os-ssh-host] Not through the standard managed Background Agent workflow. Cursor runs those agents in its own remote environment. Matrix can host terminal agents directly and can serve as a remote development computer through supported editor or SSH workflows. ### Does a Cursor Background Agent stop when I close my laptop? [#does-a-cursor-background-agent-stop-when-i-close-my-laptop] No. Background Agents run remotely, so closing the laptop does not stop the remote task. Local Cursor features that execute on your laptop have different lifecycle constraints. ### Does Matrix OS require Cursor? [#does-matrix-os-require-cursor] No. Matrix is agent-agnostic. You can use Claude Code, Codex CLI, Gemini CLI, OpenCode, and other terminal tools supported by your environment. ### Which option gives me more control over the runtime? [#which-option-gives-me-more-control-over-the-runtime] A Matrix computer exposes the filesystem, shells, and services directly. Cursor's managed runtime offers less infrastructure work in exchange for following Cursor's environment and workflow. # Cursor vs Windsurf vs Claude Code in 2026 URL: /blog/cursor-vs-windsurf-vs-claude-code Compare Cursor, Windsurf, and Claude Code by interface, autonomy, deployment model, and fit for different development workflows. Cursor vs Windsurf vs Claude Code Cursor, Windsurf, and Claude Code overlap, but they begin from different interfaces and operating models. Compare them by the work you want to delegate, the review surface your team prefers, and who should own the remote runtime. Product details change quickly, so verify current models, quotas, and plan features in each vendor's documentation. The distinctions below focus on workflow rather than a temporary feature list. Primary references: [Cursor documentation](https://docs.cursor.com/), [Windsurf documentation](https://docs.windsurf.com/), and [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/overview). ## What Each Tool Is, Precisely [#what-each-tool-is-precisely] ### Cursor [#cursor] Cursor is a code editor based on VS Code with inline assistance, multi-file agent workflows, and managed Background Agents. Available models and modes depend on the current plan. Interactive editor work uses the local workspace. Cursor Background Agents are different: they run remotely in Cursor-managed environments and return work for review. ### Windsurf [#windsurf] Windsurf also takes an editor-first approach, with an agent experience designed to stay aware of the code and actions inside the workspace. Its current remote and background capabilities should be checked against the vendor's documentation when evaluating it. The editor remains the primary review surface, even as some execution may happen remotely. ### Claude Code [#claude-code] Claude Code is different in shape. It is a terminal-native agent — you run it from the command line, point it at a repository, and give it a task. There is no editor UI. It reads files, edits them, runs shell commands, and reports back. The model is Anthropic's Claude, and the tool is designed for agentic, multi-step work rather than inline assistance. Claude Code is naturally suited to terminal workflows and can run on a local or remote computer. Anthropic also provides integrations and remote workflows, so it should not be reduced to a local-only CLI. ## The Core Comparison [#the-core-comparison] Here is how the three tools compare across the dimensions that matter most for daily use: * **Interface** — Cursor: editor (VS Code fork). Windsurf: editor (standalone). Claude Code: terminal / CLI. * **Session model** — all three offer interactive workflows; remote and background execution differs by product and plan. * **Multi-file editing** — all three support it. * **Runs without supervision** — Cursor and Claude Code support remote/background patterns; verify Windsurf's current offering. * **Persistence across device sleep** — available when execution is remote, regardless of which local UI initiated the task. * **Model flexibility** — Cursor: high (configurable). Windsurf: moderate. Claude Code: fixed (Claude). * **Best for** — Cursor: inline, interactive coding. Windsurf: inline, context-aware coding. Claude Code: autonomous, long-running tasks. ## Where Cursor Wins [#where-cursor-wins] Cursor is the right tool when you want to stay in the driver's seat. The inline tab completion is fast, the multi-file Composer is mature, and model configurability gives you real control over cost and capability. If you are writing code and want the AI to assist rather than act, Cursor fits that workflow well. The VS Code foundation also means existing extensions, keybindings, and muscle memory transfer without friction. The learning curve is shallow for anyone already in that ecosystem. For managed Background Agents, Cursor also owns the execution environment. That convenience is useful, but it gives the team less direct control than running an agent on its own computer. ## Where Windsurf Wins [#where-windsurf-wins] Windsurf's Flows architecture gives the model better visibility into what you just changed and what you are about to touch. For developers who find Cursor's suggestions occasionally out of sync with their current intent, Windsurf can feel more coherent. It is also a cleaner editor for people who want to leave VS Code behind entirely. The surface is purpose-built rather than adapted. Windsurf's capabilities and packaging evolve quickly. Test the current product with your repository instead of assuming that an editor-first tool is limited to autocomplete. ## Where Claude Code Wins [#where-claude-code-wins] Claude Code is built for tasks, not conversations. You describe what needs to happen — fix the failing tests, triage the error log, draft the changelog — and it works through the steps. It can call tools, read files, run commands, and iterate without prompting after every action. The terminal interface makes Claude Code easy to place on infrastructure you control. That is the clearest distinction from a vendor-managed background runtime: the team can choose the host, shell tools, process supervision, and repository layout. The tradeoff is control granularity. You are not steering line by line — you are setting intent and inspecting artifacts. For developers who want tight, interactive control over every suggestion, that autonomy can feel like a loss of precision. ## The Persistence Problem [#the-persistence-problem] Any of the tools can be constrained by laptop sleep when the relevant process runs locally. Managed remote agents and agents running on a remote computer continue independently of the local device, subject to their own lifecycle policies. Separate the interface question from the runtime question. An editor can submit work to a managed remote agent, while a terminal agent can run on a remote computer that your team controls. The practical answer is to move the agent off the local machine entirely. [Running Claude Code on a hosted cloud computer](/blog/keep-claude-code-running-after-laptop-closes) means the session persists regardless of what happens to your laptop. The agent keeps working; your device becomes a viewer rather than the runtime. [Matrix OS](https://matrix-os.com) is built specifically for this pattern — a dedicated cloud computer where agents like Claude Code run in persistent sessions, handling background tasks while the developer's local environment stays free. The work lives on the cloud computer. Shells come and go, but the computer keeps running. ## Choosing Based on Workflow [#choosing-based-on-workflow] The right tool depends on what kind of work you are doing, not which tool has the longest feature list. For interactive work where you want to stay close to the code as it is written, Cursor or Windsurf may fit. Test both against the same task because model availability, context handling, and agent behavior change over time. For tasks that should run without your attention, compare Cursor's managed Background Agents with Claude Code on local, vendor-managed, or team-controlled remote compute. The right choice depends on the required control and review workflow. The [cloud computer model for agents](/blog/cloud-computer-for-agents) is not a niche use case. It is the natural infrastructure for any developer who wants agents doing real work between human check-ins. ## What These Tools Are Not [#what-these-tools-are-not] None of these tools replaces the others in every context. Their boundaries also change as vendors add agent, editor, and remote-execution features. Treating them as competing for the same job is the wrong frame. They occupy different positions in the development workflow. A developer using Claude Code for background tasks and Cursor for interactive sessions is not doubling up — they are covering different parts of the work. The [canvas-first workspace model](/technical) points toward an architecture where agents and developers share a persistent environment rather than competing for the same local machine. That framing makes the tool selection question cleaner: pick the right agent for the right task, and give each one the runtime it needs. ## FAQs [#faqs] **Can you use Cursor and Claude Code together?** Yes. They serve different roles. Cursor handles interactive, line-by-line editing. Claude Code handles autonomous, multi-step tasks. Running both means you have an interactive assistant for active coding sessions and an agent for background work. The two do not conflict. **Is Windsurf better than Cursor for AI-assisted coding in 2026?** Neither is strictly better. Windsurf's Flows architecture provides tighter real-time context awareness. Cursor offers more model flexibility and a larger extension ecosystem. The right choice depends on whether you prioritize model choice or editor-context coherence. **Why does Claude Code need a persistent runtime?** Claude Code is designed for multi-step, autonomous tasks. If the machine running it sleeps or disconnects mid-task, the session terminates and progress is lost. A persistent cloud runtime — like the one Matrix OS provides — keeps the agent running regardless of local device state. **Does Claude Code work with an editor?** Claude Code is terminal-first, but Anthropic supports editor integrations and other interfaces. Cursor and Windsurf remain more editor-centered products. **Which tool is best for long-running background tasks?** Use a managed background agent when you want the vendor to own execution. Use Claude Code on a persistent computer when you want direct control of the runtime. Evaluate current lifecycle limits and review tools before choosing. **Can Cursor continue after the laptop closes?** Cursor Background Agents run remotely and can continue independently of the laptop. Interactive features that execute in the local workspace still depend on the local computer. **What is the main architectural difference between these three tools?** Cursor and Windsurf are editor-embedded assistants — they assist a developer who is actively writing code. Claude Code is an autonomous agent that receives a task and executes it. The architectural difference is the degree of human involvement required during execution. *** The session model is the unit that matters. Not the feature list, not the model provider, not the editor UI. Pick the tool whose session model matches the kind of work you are actually doing. # Gemini CLI vs Claude Code in 2026 URL: /blog/gemini-cli-vs-claude-code Compare Gemini CLI and Claude Code by context, tool use, workflow, cost model, and support for remote agent environments. Gemini CLI vs Claude Code Two terminal-based AI coding agents. Both capable. Both free to start. And if you have spent any time with either, you already know they feel different in ways that matter beyond benchmark scores. This comparison is for developers who have used at least one of them and are deciding whether to switch, combine, or commit. It covers how each agent behaves in practice, where each falls short, and what to consider when your workflow depends on agents running reliably across long sessions. Because models, quotas, and tool permissions change, verify details in the [Gemini CLI repository](https://github.com/google-gemini/gemini-cli) and [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/overview). ## What Each Agent Actually Is [#what-each-agent-actually-is] ### Claude Code [#claude-code] Claude Code is Anthropic's terminal agent. It runs as a CLI tool inside your existing shell and uses Claude's models to read, write, and reason about code in your project. It handles multi-step tasks: refactoring across files, writing tests, debugging, generating documentation, executing shell commands as part of a task chain. The agent works directly with your local filesystem. It reads context from the files you point it at, maintains conversation state within a session, and can run subagents for parallel subtasks. The model behind it is Claude Sonnet or Opus depending on your API plan. ### Gemini CLI [#gemini-cli] Gemini CLI is Google's open-source terminal agent, released in mid-2025. It connects to Gemini models and operates similarly — invoke it from the terminal, give it a task, and it reads files, writes code, and executes commands. The headline technical detail is its context window: up to one million tokens, among the largest available at this tier. Gemini CLI is free within Google's rate limits under a personal Google account. That pricing structure makes it accessible for experimentation without committing to API spend. ## Where They Differ in Practice [#where-they-differ-in-practice] ### Context Handling [#context-handling] Gemini CLI's large context window is a real practical advantage for certain tasks. Loading an entire codebase, a long conversation history, or multiple large files into a single session is less likely to hit a ceiling. If you work on large monorepos or need the agent to hold significant state simultaneously, this matters. Claude Code's context window is smaller, but its handling of that context is precise. Anthropic has invested heavily in instruction-following fidelity — Claude Code tends to stay on task and respect constraints set at the start of a session. For tasks that require careful adherence to a spec or a defined set of rules, that precision is often more useful than raw window size. ### Tool Use and Shell Integration [#tool-use-and-shell-integration] Both agents can execute shell commands, read and write files, and chain operations. Claude Code's tool use is mature and well-documented. It handles multi-step agentic tasks reliably and has a clear model for when it asks for confirmation versus acts autonomously. Gemini CLI's tool use is capable and improving quickly. Because it is open-source, the community has been active in extending its integrations. If you need to customize or extend the agent's tooling at the code level, Gemini CLI gives you more surface to work with. ### Model Quality for Code Tasks [#model-quality-for-code-tasks] Honest comparison here is difficult, because model quality is task-dependent and both improve with each release. As of 2026, Claude Sonnet and Opus remain strong benchmarks for code generation, refactoring, and multi-file reasoning. Gemini's models have closed the gap significantly, particularly on generation tasks where the large context window lets the model see more of the codebase before writing. For complex debugging and reasoning chains, Claude Code tends to produce more reliable step-by-step analysis. For generation tasks over large codebases, Gemini CLI's context advantage is tangible. ### Cost Structure [#cost-structure] Gemini CLI is free within rate limits under a personal Google account. Heavier usage means paying for Gemini API tokens. Claude Code requires Anthropic API access, billed by usage. Neither is free at production scale, but Gemini CLI's entry point is lower for developers who want to experiment or run lighter workloads. ## The Workflow Question Neither Answers Well [#the-workflow-question-neither-answers-well] Both agents share a structural limitation that has nothing to do with model quality: they run on your local machine. The terminal is local. The session is only as persistent as the device under it. Close your laptop, lose your session. The agent stops. Any long-running task either fails or restarts from scratch. This is not a criticism of either tool specifically — it is the nature of running an agent process locally. But it becomes a real constraint when you want an agent to work through a task queue overnight, handle a long refactor while you are in meetings, or run in parallel with another agent on the same codebase. If you have hit this wall with Claude Code specifically, the article on [keeping Claude Code running after your laptop closes](/blog/keep-claude-code-running-after-laptop-closes) covers the difference between local sleep and remote execution and what the options are. ## Running Both Agents Without Rebuilding Your Environment [#running-both-agents-without-rebuilding-your-environment] The framing of Gemini CLI versus Claude Code assumes you are choosing one. Many developers do not want to choose. Different tasks suit different models, and model quality shifts with each release. Locking into one agent means rebuilding your setup every time you want to try the other. This is the environment problem. Each agent expects a certain shell context, file structure, and set of dependencies. Running both locally means managing two configurations on the same machine, or switching between them manually. [Matrix OS](https://matrix-os.com) provisions a dedicated cloud computer where Gemini CLI and Claude Code can run in separate sessions and Git worktrees. You can assign different tasks to each and inspect both from the browser or terminal. Laptop sleep and local disconnects do not stop processes on the remote computer; Git checkpoints and process supervision remain important for recovery from restarts or failures. The point is not that Matrix OS makes either agent better. It is that the environment stops being the constraint. You pick the agent for the task, not the task for the agent you happen to have configured. For a fuller look at what a persistent cloud environment changes about how agents work, the [cloud computer for agents](/blog/cloud-computer-for-agents) post covers the architectural reasoning. ## A Direct Comparison [#a-direct-comparison] | | Gemini CLI | Claude Code | | ------------------------------- | ----------------------- | ----------------------------- | | Context window | Up to 1M tokens | Smaller, varies by model tier | | Pricing entry point | Free within rate limits | API usage-based | | Open-source | Yes | No | | Code generation (large repos) | Strong | Strong | | Instruction-following precision | Good | Very good | | Multi-step reasoning | Good | Very good | | Shell and tool use | Capable, extensible | Mature, well-documented | | Session persistence | Local only | Local only | | Simultaneous multi-agent use | Requires external setup | Requires external setup | ## Which One to Use [#which-one-to-use] Use Gemini CLI if: you work on large codebases where context window size is the binding constraint, you want to experiment without API spend, or you need to extend the agent's tooling at the source level. Use Claude Code if: instruction-following fidelity matters more than raw context size, you are running complex multi-step tasks that require the agent to stay precisely on spec, or you are already in the Anthropic ecosystem. Use both if: you want to route tasks by model strength, run agents in parallel, or avoid being locked to one provider's roadmap. That last case is where the environment setup matters as much as the agent choice. *** ## FAQs [#faqs] ### What is the main difference between Gemini CLI and Claude Code? [#what-is-the-main-difference-between-gemini-cli-and-claude-code] Gemini CLI is Google's open-source terminal agent with a large context window and a free entry tier. Claude Code is Anthropic's terminal agent with strong instruction-following and mature multi-step tool use. Both operate in your shell and can read, write, and execute code. The practical difference comes down to context size versus reasoning precision, and cost structure. ### Can I run Gemini CLI and Claude Code at the same time? [#can-i-run-gemini-cli-and-claude-code-at-the-same-time] Yes, but not without deliberate setup. Both agents run as local processes and can technically operate simultaneously on the same machine. The challenge is shared file state and session management. On a dedicated cloud computer like Matrix OS, both agents run in isolated sessions with shared file state, so you can assign tasks to each without conflicts. ### Is Gemini CLI free to use? [#is-gemini-cli-free-to-use] Gemini CLI is free within rate limits under a personal Google account. Usage beyond those limits means paying for Gemini API tokens. It is not free at production scale, but the entry point is lower than Claude Code for developers experimenting or running lighter workloads. ### Does Claude Code work better than Gemini CLI for coding tasks? [#does-claude-code-work-better-than-gemini-cli-for-coding-tasks] It depends on the repository, task, model available on your plan, and evaluation criteria. Test both agents against the same representative tasks and compare correctness, review effort, tool behavior, latency, and cost. Neither is universally better. ### Why do both agents stop when I close my laptop? [#why-do-both-agents-stop-when-i-close-my-laptop] Both agents run as local processes tied to your terminal session. When the laptop sleeps or the session disconnects, the process stops. This is a structural property of running agents locally, not a limitation specific to either agent. Running them on a persistent cloud computer resolves this — the session continues on the remote machine regardless of what your local device does. ### Can I use Gemini CLI and Claude Code on the same codebase without conflicts? [#can-i-use-gemini-cli-and-claude-code-on-the-same-codebase-without-conflicts] With the right setup, yes. The key requirement is isolated sessions with shared file state, so each agent reads and writes to the same files without stepping on each other's operations. This requires either careful manual session management locally or a purpose-built environment that handles isolation for you. ### Which agent should I start with if I am new to terminal-based AI agents? [#which-agent-should-i-start-with-if-i-am-new-to-terminal-based-ai-agents] Gemini CLI is a reasonable starting point — the free tier removes the cost barrier for experimentation. Claude Code is worth adding once you have a clearer sense of your workflow, particularly if you find yourself running tasks that require the agent to follow detailed instructions across multiple steps. Most developers who use agents seriously end up working with more than one. # How to stop parallel coding agents fighting over ports and databases URL: /blog/avoid-parallel-agent-port-database-conflicts Isolate ports, databases, containers, caches, and test artifacts when Claude Code, Codex, and other agents run in parallel. Separate Git worktrees prevent file collisions, but parallel coding agents can still fight over ports, databases, containers, caches, and test artifacts. Assign every agent a unique runtime namespace and generate its environment from that assignment before starting any dev server or test suite. ## Why do agents still collide in separate worktrees? [#why-do-agents-still-collide-in-separate-worktrees] Two agents in separate worktrees may still connect to: * port 3000, * the same local PostgreSQL database, * the same Redis keyspace, * the same Docker Compose project, * the same browser-test output directory, * the same cloud development resources, * the same rate-limited third-party account. These collisions create flaky tests and misleading results even when Git is clean. One agent may reset the shared test database while another is asserting against it. Both agents blame their code because neither sees the other process. ## Give every agent its own runtime slot [#give-every-agent-its-own-runtime-slot] Assign a short safe slug and derive all resources from it: | Agent | Slug | Web port | API port | Database | Compose project | | -------------- | ---------------- | -------: | -------: | -------------------- | -------------------- | | Claude billing | `claude-billing` | 3101 | 4101 | `app_claude_billing` | `app_claude_billing` | | Codex tests | `codex-tests` | 3102 | 4102 | `app_codex_tests` | `app_codex_tests` | Store the values in an ignored worktree-specific file: ```bash AGENT_SLOT=claude-billing WEB_PORT=3101 API_PORT=4101 DATABASE_URL=postgresql://localhost/app_claude_billing COMPOSE_PROJECT_NAME=app_claude_billing ``` Validate slugs before interpolating them into identifiers or shell commands. Prefer a small allowlisted pattern such as lowercase letters, numbers, and hyphens. ## How should each agent get a separate database? [#how-should-each-agent-get-a-separate-database] Use one database, schema, or disposable container per agent. A separate database provides the clearest boundary for migrations and fixtures. If schemas are used, confirm the application and migration tool correctly respect the schema on every connection. Never let an unattended development agent run destructive tests or migrations against production. Use synthetic or appropriately minimized development data. ## How do you run Docker Compose from several worktrees? [#how-do-you-run-docker-compose-from-several-worktrees] Compose project names determine container, network, and volume namespaces. Give each agent a unique project name and avoid fixed container names in Compose files. Fixed host ports will still collide, so parameterize them. ## Which test outputs and caches need isolation? [#which-test-outputs-and-caches-need-isolation] Configure unique output directories for screenshots, coverage, traces, and temporary downloads. Shared read-only package caches can save time, but tools that mutate caches unsafely may need per-agent locations. External APIs also require coordination. Separate credentials do not remove account-level rate limits or spending caps. Use mocks when possible and track aggregate usage. ## What should you check before starting each agent? [#what-should-you-check-before-starting-each-agent] Before an agent starts work, verify: 1. Its branch and worktree are correct. 2. Assigned ports are free. 3. The database name belongs to its slot. 4. No production hostname appears in environment variables. 5. Its Compose project name is unique. 6. Output directories are scoped to the worktree. 7. The expected test command succeeds in isolation. On a persistent Matrix computer, use named terminal sessions to keep each runtime identifiable and [Symphony](/symphony) to inspect parallel work. For the Git layer, read [Git worktrees for coding agents](/blog/git-worktrees-for-coding-agents). ## Common questions about parallel-agent runtime conflicts [#common-questions-about-parallel-agent-runtime-conflicts] ### Why do tests fail only when two agents run? [#why-do-tests-fail-only-when-two-agents-run] Look for shared databases, fixed ports, global temporary directories, Compose names, rate limits, and tests that assume exclusive access to mutable data. ### Is a different port enough? [#is-a-different-port-enough] No. Ports solve listener collisions. Databases, queues, caches, files, containers, and external accounts can still be shared. ### Should every agent get a separate VM? [#should-every-agent-get-a-separate-vm] That provides stronger isolation and may be appropriate for untrusted or resource-heavy work. For trusted development tasks, worktrees plus explicit runtime namespaces are often faster and cheaper. # Best cloud development environments for AI coding agents URL: /blog/best-cloud-dev-environments-for-ai-agents A practical framework for comparing persistent computers, cloud IDEs, task sandboxes, Codespaces, Coder, Daytona, VPS setups, and Matrix OS. The best cloud development environment for an AI coding agent depends on the job. Use a task sandbox for isolated delegation, a cloud IDE for repository-centered interactive development, a raw VPS for infrastructure control, or a persistent agent computer when multiple CLIs, services, files, and review workflows must stay available across devices. ## Which type of cloud environment do you need? [#which-type-of-cloud-environment-do-you-need] | Type | Examples to evaluate | Best for | Main tradeoff | | ------------------------- | --------------------------------- | ----------------------------------- | --------------------------------------- | | Agent task cloud | Claude Code web, Codex cloud | Delegated repository tasks | Less like a continuously owned computer | | Cloud IDE/dev environment | GitHub Codespaces, Coder, Daytona | Reproducible developer environments | Lifecycle varies by platform and policy | | Raw VPS | Major cloud/VPS providers | Full control | You operate everything | | Persistent agent computer | Matrix OS | Long-running multi-agent workspace | Ongoing compute and product commitment | This table is a category map, not a universal ranking. Test current features, security controls, regions, prices, and lifecycle behavior directly. ## What should you test before choosing? [#what-should-you-test-before-choosing] ### Does the process keep running? [#does-the-process-keep-running] Does the agent continue when the client disconnects? What happens after inactivity, a reboot, platform maintenance, or a spending limit? Do not confuse preserved files with a process that is still executing. ### Can it run the real development stack? [#can-it-run-the-real-development-stack] Can the agent run the real package manager, test suite, database, browser automation, containers, and preview server? A capable model cannot compensate for a toy runtime. ### Can each agent be isolated? [#can-each-agent-be-isolated] Can every concurrent agent receive its own worktree, branch, ports, database, and credentials? How is network and secret access restricted? ### Can a human review the actual work? [#can-a-human-review-the-actual-work] Can a person inspect live logs, diffs, test results, previews, and approval requests without reconstructing context from chat? ### How do people and tools authenticate? [#how-do-people-and-tools-authenticate] How do browser, CLI, mobile, Git provider, and team access work? Look for supported device flows and scoped credentials instead of copied tokens. ### Who operates the environment? [#who-operates-the-environment] Who patches the host, secures the edge, manages backups, handles incidents, and restores state? “Flexible” often means “you own it.” ### What does real usage cost? [#what-does-real-usage-cost] Model active compute, storage, idle time, parallel workers, data transfer, and operator time. A per-hour environment and an always-on monthly computer solve different utilization patterns. ## Where each environment type works well [#where-each-environment-type-works-well] **Task clouds** minimize setup for delegated work. They are a good default when a clean repository task can run in a provider-managed environment. **Codespaces and cloud development platforms** emphasize reproducible environments and interactive development. Evaluate idle policies and whether background processes remain alive for the required duration. **Coder and Daytona-style platforms** are worth evaluating when teams want programmatic or self-hosted development-environment infrastructure. Compare deployment model, templates, orchestration, lifecycle, and operator burden using current first-party documentation. **A raw VPS** is the most composable option. It also makes you responsible for every missing layer between a server and a safe developer product. **Matrix OS** is built around a dedicated computer for agents and people: persistent terminals, repositories, files, apps, previews, browser and CLI access, and orchestration through Symphony. It supports a managed cloud path and a [self-host path](/docs/self-host). ## Run the same task in every shortlisted environment [#run-the-same-task-in-every-shortlisted-environment] Run the same bounded repository task in each shortlisted environment. Record: * setup time, * time to first passing test, * behavior after closing the client, * behavior after the idle window, * reconnection quality, * diff and preview review flow, * secret exposure surface, * total compute and operator cost. One useful test is a dependency upgrade that runs unit tests, starts a preview, and opens a draft PR. Close the client halfway through. Record whether the process continues, how you reconnect, and what evidence is waiting for review. That tells you more than a feature checklist. ## Common questions about cloud environments for coding agents [#common-questions-about-cloud-environments-for-coding-agents] ### Is a cloud IDE enough for autonomous agents? [#is-a-cloud-ide-enough-for-autonomous-agents] Sometimes. Verify process lifetime, unattended permissions, resource limits, secrets, parallel isolation, and review artifacts. Interactive editor quality alone does not answer those questions. ### Is a VPS the cheapest option? [#is-a-vps-the-cheapest-option] It may have the lowest compute line item. Include engineering time for setup, security, access, backups, updates, monitoring, and recovery. ### What is the best environment for multiple agents? [#what-is-the-best-environment-for-multiple-agents] One that supplies isolated workspaces and runtime resources, persistent execution, constrained credentials, observable logs and diffs, and a human-controlled integration queue. # Claude Code remote options: Remote Control vs web vs VPS vs Matrix OS URL: /blog/claude-code-remote-options Compare the main ways to run or control Claude Code remotely, including laptop requirements, persistence, setup, and best use cases. Claude Code can be used remotely in four distinct ways: control a local session from another device, delegate a task to Claude Code on the web, run the CLI on your own VPS, or run it on a managed persistent computer such as Matrix OS. The best option depends on where your code and processes need to live. ## Claude Code remote options compared [#claude-code-remote-options-compared] | Option | Runtime location | Works while laptop sleeps | Long-lived personal environment | Infrastructure work | | -------------------------- | ------------------------- | ------------------------: | ------------------------------: | ---------------------: | | Claude Code Remote Control | Laptop | No | Yes, on laptop | Low | | Claude Code on the web | Anthropic-managed cloud | Yes | Task-oriented | Low | | VPS plus `tmux` | Your server | Yes | Yes | High | | Matrix OS | Dedicated Matrix computer | Yes | Yes | Managed or self-hosted | ## When should you use Claude Code Remote Control? [#when-should-you-use-claude-code-remote-control] Remote Control is the closest match when you already have a local Claude Code session with uncommitted files, local services, or hardware-specific context. You can continue interacting from another supported device while the actual process stays on your computer. Choose it when preserving the exact local environment matters and the laptop can remain powered and awake. Do not choose it as an uptime solution: the phone is a remote control, not a replacement runtime. ## When should you use Claude Code on the web? [#when-should-you-use-claude-code-on-the-web] Claude Code on the web is useful for assigning GitHub-based tasks to an Anthropic-managed remote environment. It removes laptop uptime from the task and minimizes server setup. Choose it for clean, delegated work that fits its repository and environment model. A personal persistent computer may fit better when you need durable local services, files beyond a single repository, multiple agent CLIs, custom infrastructure, or one workspace you repeatedly return to. ## When should you run Claude Code on your own VPS? [#when-should-you-run-claude-code-on-your-own-vps] A VPS is the flexible DIY route. Install Claude Code and the project toolchain, secure SSH, and run the session under `tmux` or `zellij`. You control the server, network, storage, and lifecycle. Choose it when infrastructure control is worth the maintenance. Read the complete [Claude Code VPS setup guide](/blog/run-claude-code-on-vps) before exposing a server to the internet. ## When does a persistent agent workspace make sense? [#when-does-a-persistent-agent-workspace-make-sense] Matrix OS supplies a dedicated remote computer with persistent files, named terminal sessions, browser access, previews, and support for several coding agents. The session remains attached to the Matrix computer when the laptop disconnects. Symphony adds a review surface for parallel agent work. Choose Matrix when you want a durable multi-tool development environment but do not want to assemble the product layer around a raw VPS. Choose self-hosted Matrix when you want that interface on infrastructure you operate. ## Which option should you choose? [#which-option-should-you-choose] * Existing local state and a laptop that stays awake: **Remote Control**. * Fire-and-forget GitHub task with minimal setup: **Claude Code on the web**. * Full infrastructure ownership: **VPS plus a persistent terminal**. * Persistent development computer with browser and multi-agent workflows: **Matrix OS**. The options can coexist. A developer may use Remote Control for a local hardware bug, Claude Code on the web for an isolated repository task, and Matrix for long-running work that needs durable services and multiple agents. ## Check the environment before choosing [#check-the-environment-before-choosing] 1. Must the work use uncommitted files that exist only on my laptop? 2. Must it continue after every personal device disconnects? 3. Does it need services or files beyond one repository? 4. Will I run more than one coding-agent CLI? 5. Who owns updates, access control, backups, and recovery? 6. What evidence will I review before merging? For the core persistence problem, read [how to keep Claude Code running after closing your laptop](/blog/keep-claude-code-running-after-laptop-closes). To try the managed path, use the [Matrix quickstart](/docs/quickstart). ## Common questions about remote Claude Code [#common-questions-about-remote-claude-code] ### Is Remote Control the same as Claude Code on the web? [#is-remote-control-the-same-as-claude-code-on-the-web] No. Remote Control lets another device interact with a session running on your computer. Claude Code on the web runs the task in a remote environment. ### Is Matrix OS a Claude model provider? [#is-matrix-os-a-claude-model-provider] No. Matrix supplies the computer and workspace in which supported coding-agent tools run. You authenticate each agent through its own supported flow. ### Which option keeps arbitrary dev servers running? [#which-option-keeps-arbitrary-dev-servers-running] A VPS or persistent Matrix computer is designed around a long-lived environment you control. Verify the lifecycle and idle-shutdown rules of any task-oriented cloud environment before relying on a long-running service. # Git worktrees for AI coding agents: a practical guide URL: /blog/git-worktrees-for-coding-agents Give Claude Code, Codex, and other agents isolated working directories and branches without cloning the repository repeatedly. Git worktrees let multiple AI coding agents use the same repository history while editing separate working directories and branches. Create one worktree per writing agent, start each agent inside its assigned directory, and merge results through an ordered review queue. ## Why are branches alone not enough for parallel agents? [#why-are-branches-alone-not-enough-for-parallel-agents] A Git branch separates history, but one working directory can only have one checked-out state at a time. If two agents write into that directory concurrently, they share files, the index, generated output, package locks, and build artifacts. One package install can rewrite the lockfile while another agent is editing it. A formatter can touch both agents' files. Git then shows one mixed diff with no reliable ownership. A worktree gives each agent its own filesystem view: ```text ~/projects/app-main main ~/projects/app-billing agent/billing ~/projects/app-tests agent/tests ``` The worktrees share Git objects, so they use less disk and fetch time than several unrelated clones. ## How do you create a worktree for each agent? [#how-do-you-create-a-worktree-for-each-agent] ```bash cd ~/projects/app-main git fetch origin git status --short git worktree add ../app-billing -b agent/billing origin/main git worktree add ../app-tests -b agent/tests origin/main git worktree list ``` Do not hide uncommitted changes before creating parallel work. Decide whether to commit, stash, or move them deliberately. ## How do you start agents in the worktrees? [#how-do-you-start-agents-in-the-worktrees] ```bash cd ~/projects/app-billing claude ``` In another terminal: ```bash cd ~/projects/app-tests codex ``` Put the directory, branch, allowed scope, required tests, and stopping conditions in each task prompt. Ask the agent to report `git status --short` and the commit SHA when it finishes. ## What do worktrees fail to isolate? [#what-do-worktrees-fail-to-isolate] Worktrees separate tracked files, but external state can still collide: * package caches may be shared, * dependency directories are per worktree unless configured otherwise, * dev servers need unique ports, * tests need separate databases or schemas, * containers need unique project names, * browser-test artifacts need separate output directories. Create uncommitted per-worktree environment files and document the assigned resources. Continue with [avoiding port and database conflicts](/blog/avoid-parallel-agent-port-database-conflicts). ## How do you review and remove an agent worktree? [#how-do-you-review-and-remove-an-agent-worktree] Inspect the diff and tests for one branch, merge it, then update the remaining branches before review. A useful sequence is: ```bash git -C ../app-billing diff origin/main...HEAD git -C ../app-billing status --short ``` After the branch is merged and no longer needed: ```bash git worktree remove ../app-billing git branch -d agent/billing git worktree prune ``` Never remove a worktree with valuable uncommitted changes. Inspect status and preserve the work first. ## Common questions about Git worktrees for coding agents [#common-questions-about-git-worktrees-for-coding-agents] ### Can two worktrees use the same branch? [#can-two-worktrees-use-the-same-branch] Git normally prevents checking out the same branch in multiple worktrees. Give every active agent its own branch. ### Do worktrees isolate databases and ports? [#do-worktrees-isolate-databases-and-ports] No. They isolate working directories and branch state. You must separately configure runtime resources. ### Are separate clones safer? [#are-separate-clones-safer] Separate clones provide stronger repository-level separation but cost more disk and synchronization work. Worktrees are usually the simplest balance for concurrent branches on one trusted computer. # Grok Bot vs Matrix OS: which workspace fits your agents? URL: /blog/grok-bot-vs-matrix-os Compare Grok Bot and Matrix OS for task templates, cloud computers, agent choice, review workflows, and ownership. Grok Bot and Matrix OS both give AI agents a computer to work on. Their starting points differ: Grok Bot leads with specialized bots and ready-made jobs; Matrix leads with a private workspace where you and your agents can work with files, tools, and apps. This comparison is written by the Matrix team. It separates documented capabilities from our recommendations. It is not a claim that Matrix has full Grok Bot feature parity. ## Start with the job [#start-with-the-job] [Grok Bot](https://x.ai/bot) makes the promise easy to understand: give a bot a job and see the result. Its [marketplace](https://x.ai/bot/marketplace) presents task-specific starting points. This is useful if your priority is finding an existing workflow quickly. Matrix is a good fit when the workspace itself matters: you want the source material, agent sessions, proposed changes, and resulting files together. [Matrix recipes](/recipes) provide task briefs for research, weekly reports, bug fixes, campaigns, meeting follow-ups, and software-spend reviews. Today you copy the instructions, provide inputs, and run them with your agent. One-click recipe installation is planned. ## Compare the workflows [#compare-the-workflows] | Question | Grok Bot | Matrix OS | | ------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | How do I start? | Choose a bot or task-oriented starting point. | Open your cloud workspace and give an agent a task; recipes supply reusable briefs. | | What does the computer retain? | Bots on an account share computer files, browser cookies, and credentials, according to the documentation. | Projects, files, and application state persist in your workspace. | | Can I inspect the work? | Computer access and screen takeover are documented. | Use the workspace’s files, terminals, apps, and available previews to inspect results. | | What can I automate? | Skills, routines, automation controls, and run history are documented; availability varies. | Background and scheduled work requires Builder or Max and configuration for the workflow. Starter sleeps when inactive. | | How do recipes work? | Task-specific bots and marketplace entries help package a job. | Current recipes are manual task briefs with inputs, expected outputs, and review instructions. | | What about coding agents? | Evaluate the Grok workflow against your repository and tool needs. | Run supported coding agent harnesses in the workspace and review their files and changes. Setup, accounts, and usage limits apply. | ## A shared computer needs clear boundaries [#a-shared-computer-needs-clear-boundaries] Grok’s [computer documentation](https://docs.x.ai/grok-bot/computer-and-apps) says that separate bot screens are not security boundaries: files, browser sessions, and credentials are shared within the account’s computer. Screen takeover helps with tasks such as signing in or handling a CAPTCHA. For either product, decide which accounts and data belong in the workspace. An agent’s ability to click a button does not mean a workflow should authorize every action. Keep publication, outbound messages, spending, and destructive changes behind an explicit review step when that is what your task requires. Matrix recipes include those instructions in the task brief. They are instructions to the agent, not a replacement for runtime permissions or connected-service access controls. ## Recurring work needs more than a prompt [#recurring-work-needs-more-than-a-prompt] Grok documents [skills, routines, and automations](https://docs.x.ai/grok-bot/skills-routines-and-automations), including testing, pausing, and reviewing runs. Some teaching features are gradually available. Verify availability in your account rather than assuming every demonstration is included. In Matrix, a weekly-report recipe runs once unless you separately ask for a schedule. To make it reliable as a recurring job, define its sources, timing, permissions, destination, and failure behavior. Builder and Max support the always-on computer needed for that work; agent usage limits and connected services still matter. ## Which should you choose? [#which-should-you-choose] Choose Grok Bot if a packaged bot already matches your job and you prefer its integrated workflow. Try that job with your own inputs and check both its successful output and its approval behavior. Choose Matrix if you want a persistent computer where you can work alongside agents, inspect files and terminals, and adapt a task across tools. Start with one [Matrix recipe](/recipes), then expand the workflow once its output is useful. For a fair trial, give both systems the same source material and acceptance criteria. Ask each to produce a sourced brief, a proposed patch, or a report that you can inspect. Compare setup effort, missing information, review steps, and repeatability—not only the polish of the first response. ## What Matrix still needs to prove [#what-matrix-still-needs-to-prove] The next step is to make the complete recipe lifecycle visible: installation, connected accounts, permissions, first-run preview, scheduling, run history, and recovery from failures. A polished landing-page example is not evidence that these capabilities have shipped. The most useful demo is a real task with an inspectable result. Our [recipe examples](/#recipes) illustrate the intended task and output; the [documentation](/docs) explains current setup. Check [plans](/#pricing) before choosing unattended work. # How to keep Codex CLI running after you close your laptop URL: /blog/keep-codex-running Run Codex CLI on a persistent remote computer so terminal work continues after your laptop sleeps or disconnects. To keep Codex CLI running after closing your laptop, start it on a remote computer that remains online and use a persistent terminal session. Closing the laptop then disconnects your interface rather than suspending the computer executing Codex. Codex cloud is another remote option, but it is a different workflow from a long-lived CLI environment. ## Why does Codex CLI stop when the laptop sleeps? [#why-does-codex-cli-stop-when-the-laptop-sleeps] Codex CLI works against the files and tools available on the machine where the command runs. If that machine is your laptop, sleep freezes or stops useful execution. An SSH connection alone is not sufficient either: a process attached directly to a dropped shell can terminate. You need two layers: 1. An underlying computer that stays running. 2. A terminal session that survives client disconnection. ## Use Codex cloud for delegated repository tasks [#use-codex-cloud-for-delegated-repository-tasks] Codex cloud is the low-operations option for delegated cloud tasks. Choose it when your work fits the cloud task and repository workflow. It removes the need to keep a laptop awake or maintain a VPS. A persistent personal computer is a better fit when the task depends on long-lived services, files outside one repository, several agent CLIs, custom databases, or a development environment you want to revisit continuously. ## Use a VPS when you want to operate the environment [#use-a-vps-when-you-want-to-operate-the-environment] Provision a secured Linux VPS, create a non-root user, install the project toolchain, and install Codex using OpenAI’s current official installer. Sign in through the supported Codex login flow. Do not copy private credential files from another computer. Run Codex inside a persistent terminal: ```bash tmux new -s codex cd ~/projects/my-repo codex ``` Detach with `Ctrl-b`, then `d`. Reconnect later with `tmux attach -t codex`. A persistent terminal survives an SSH disconnect. It does not survive a stopped server, reboot, crash, full disk, or out-of-memory event by itself. ## Use a persistent workspace for a long-lived CLI environment [#use-a-persistent-workspace-for-a-long-lived-cli-environment] Matrix gives Codex a dedicated remote computer with files, terminals, browser access, and persistent named sessions. After following the [Matrix quickstart](/docs/quickstart), start Codex in a named session: ```bash matrix run -it --session codex-main -- bash -lc 'cd ~/projects/my-repo && codex' ``` Detach with `Ctrl-\ Ctrl-\` and return through the browser or Matrix CLI. The session runs on the Matrix computer, so your laptop can sleep. ## What should a persistent Codex session be allowed to do? [#what-should-a-persistent-codex-session-be-allowed-to-do] Put every writing session on a dedicated branch or worktree. Define the allowed scope, tests, and stopping conditions. Keep production credentials out of the workspace and require human review before merging or deploying. For repeatable non-interactive automation, Codex also supports `codex exec`. Treat it like CI. Constrain inputs, permissions, network access, time, and output artifacts. An open-ended prompt with a writable shell is not a job definition. ## Common questions about persistent Codex CLI sessions [#common-questions-about-persistent-codex-cli-sessions] ### Is Codex cloud the same as Codex CLI on a VPS? [#is-codex-cloud-the-same-as-codex-cli-on-a-vps] No. Codex cloud runs tasks in OpenAI’s cloud workflow. A VPS runs the CLI in a server environment you provision and operate. ### Can Codex and Claude Code run on the same remote computer? [#can-codex-and-claude-code-run-on-the-same-remote-computer] Yes. Give them separate terminal sessions, branches or worktrees, ports, and development databases. See [running Claude Code and Codex in parallel](/blog/run-claude-code-and-codex-in-parallel). ### Does `tmux` keep Codex alive through a server reboot? [#does-tmux-keep-codex-alive-through-a-server-reboot] No. It preserves a session across terminal disconnects, not machine shutdowns. Reboot recovery requires a deliberate restart mechanism and careful handling of interactive agent state. # Matrix OS vs GitHub Codespaces for AI coding agents URL: /blog/matrix-os-vs-github-codespaces Compare Matrix OS and GitHub Codespaces for cloud development, persistent processes, repositories, agent CLIs, idle shutdown, and ongoing workspaces. GitHub Codespaces is a repository-centered cloud development environment built around dev containers and GitHub. Matrix OS is a persistent cloud computer for files, terminals, services, apps, and coding agents across projects. Codespaces is usually better for standardized repository onboarding. Matrix fits long-running agent work that needs an ongoing computer. ## Matrix OS and GitHub Codespaces compared [#matrix-os-and-github-codespaces-compared] | Question | GitHub Codespaces | Matrix OS | | --------------------------------------- | ---------------------------------- | ----------------------------------------------------------- | | Primary unit | Repository/dev container | Persistent computer/workspace | | GitHub integration | Native | Via Git and GitHub CLI | | Environment definition | `devcontainer.json` | Computer plus project tooling | | Default idle behavior | Stops after inactivity | Builder and Max are always-on; Starter sleeps when inactive | | Files after stop | Preserved until retention/deletion | Persist on the Matrix computer | | Running process after environment stops | Stops | Runs while the Matrix computer remains active | | Multiple agent CLIs | Possible | First-class product use case | | Broader apps and files | Repository-oriented | Computer-oriented | GitHub documents a default Codespaces idle timeout of 30 minutes, configurable within policy limits. Closing a browser does not immediately stop a codespace, but an inactivity timeout eventually can. When a codespace stops, running processes stop even though saved files remain. Terminal input and output reset the inactivity timer. Check your organization’s policy and the [current timeout documentation](https://docs.github.com/en/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces) when planning unattended work. ## When is GitHub Codespaces the better choice? [#when-is-github-codespaces-the-better-choice] Codespaces is compelling when a repository already has a good dev-container definition and the team wants every contributor to receive a consistent, disposable environment closely integrated with GitHub and VS Code. It is a good fit for onboarding, contributions, workshops, and repository-scoped work where automatic stopping is acceptable or desirable for cost control. ## When is Matrix OS the better choice? [#when-is-matrix-os-the-better-choice] Matrix is organized around a long-lived computer rather than a disposable repository environment. Repositories, named terminals, files, previews, apps, and multiple agent CLIs can occupy the same workspace. A developer can detach from an agent session and return from another device. This is useful when work spans several repositories and tools, requires long-running services, or benefits from a persistent review and orchestration surface such as [Symphony](/symphony). ## Will the files and processes both persist? [#will-the-files-and-processes-both-persist] Both products can preserve files. That does not imply both keep processes executing under every lifecycle condition. * **File persistence:** changes still exist when the environment resumes. * **Process persistence:** the test, server, or agent process continues executing while you are away. For background agents, verify both. A stopped environment can preserve every file while terminating the actual task. ## How do the cost models differ? [#how-do-the-cost-models-differ] Compare the billable unit, included storage, active compute, idle behavior, retention, and the operational value of a prebuilt product layer. Codespaces can be efficient when automatic shutdown avoids unused compute. An always-on computer can be more appropriate when uninterrupted background execution is the requirement. ## Common questions about Matrix OS and GitHub Codespaces [#common-questions-about-matrix-os-and-github-codespaces] ### Will Claude Code keep running in Codespaces after I close the tab? [#will-claude-code-keep-running-in-codespaces-after-i-close-the-tab] Closing the tab does not immediately stop the codespace. It continues until stopped manually or by lifecycle rules such as inactivity timeout. When the codespace stops, its running processes stop. ### Can Matrix OS use GitHub repositories? [#can-matrix-os-use-github-repositories] Yes. Authenticate with GitHub’s supported CLI flow and clone repositories onto the Matrix computer. See the [Matrix quickstart](/docs/quickstart). ### Which is better for a classroom? [#which-is-better-for-a-classroom] Codespaces is strong for repository-defined, disposable environments. Matrix can suit labs that need the same persistent computer, agents, files, and workflows across sessions. The correct choice depends on curriculum, identity, cost, and reset requirements. # Matrix OS vs a VPS for AI coding agents URL: /blog/matrix-os-vs-vps Compare Matrix OS with a raw VPS for persistent coding agents across setup, access, terminals, security, maintenance, and control. A raw VPS and Matrix OS can both give coding agents a computer that stays online. Choose a raw VPS if you want to assemble and operate the full environment. Choose Matrix Cloud if you want that work handled for you. Self-hosted Matrix sits between them: you operate the server and keep Matrix’s workspace layer. ## Matrix OS and a raw VPS compared [#matrix-os-and-a-raw-vps-compared] | Capability | Raw VPS | Matrix Cloud | Self-hosted Matrix | | --------------------------- | ---------------- | -------------------------- | ----------------------------- | | Infrastructure control | Highest | Managed | High | | Initial setup | Manual | Provisioned | Installer plus operator setup | | Persistent shell tooling | You configure it | Included | Included | | Browser workspace | You add it | Included | Included | | Coding-agent installation | Manual | Setup choices and terminal | Installer/tool packs | | TLS, routing, auth | You operate | Managed | You operate | | Updates and backups | You operate | Managed | You operate | | Multi-agent review surfaces | You build them | Matrix/Symphony | Matrix/Symphony | For unattended work, choose Builder or Max. Starter sleeps when inactive. See [current plans](/#pricing) for availability and limits. ## When is a raw VPS the better choice? [#when-is-a-raw-vps-the-better-choice] Choose a raw VPS when you want complete control over the distribution, network, storage, access layer, regions, providers, observability, and installed services. You also need to be comfortable owning their security and reliability. It is also the direct choice for teams with established infrastructure automation. If Terraform, configuration management, identity-aware proxies, patching, backups, and monitoring are already standard, adding another developer host may be routine. ## When is Matrix Cloud the better choice? [#when-is-matrix-cloud-the-better-choice] Choose Matrix Cloud when the goal is to start running agents rather than assemble the surrounding workstation. Matrix provisions a dedicated computer and provides browser access, named terminals, files, previews, CLI attachment, managed routing, authentication, backups, updates, and agent-oriented workflows. This is especially useful for developers who want Claude Code, Codex, OpenCode, or another CLI to keep working after their laptop disconnects and want one place to return for review. ## When does self-hosted Matrix make sense? [#when-does-self-hosted-matrix-make-sense] Self-hosted Matrix is the middle path: install Matrix’s browser shell, gateway, persistent sessions, local data services, and coding-agent tooling on a VPS you control. You still own DNS, TLS, firewalling, backups, server updates, and edge hardening. The current self-host path is intended for operators comfortable running Linux infrastructure. Review its preview limitations in the [self-host documentation](/docs/self-host). ## What does the raw VPS price leave out? [#what-does-the-raw-vps-price-leave-out] The cheapest VPS price is not the whole cost. Include: * setup and maintenance time, * backups and restore testing, * access control and credential lifecycle, * TLS and routing, * incident recovery, * terminal and browser tooling, * developer time spent rebuilding drifted environments. Managed is not automatically better. If your team already has this infrastructure, another VPS may be routine. If the first session takes an afternoon of SSH, TLS, terminal, and backup setup, the low server price is hiding the expensive part. ## Which one should you choose? [#which-one-should-you-choose] * Choose **raw VPS** for maximum control and minimum abstraction. * Choose **Matrix Cloud** for the shortest path to a managed persistent agent computer. * Choose **self-hosted Matrix** for Matrix’s workspace layer on infrastructure you operate. For a DIY walkthrough, read [how to run Claude Code on a VPS](/blog/run-claude-code-on-vps). For the managed route, follow the [Matrix quickstart](/docs/quickstart). ## Common questions about Matrix OS and raw VPS setups [#common-questions-about-matrix-os-and-raw-vps-setups] ### Is Matrix OS itself a VPS provider? [#is-matrix-os-itself-a-vps-provider] Matrix Cloud provisions a dedicated hosted computer as part of the service. The product adds workspace, access, persistence, and agent workflows around the underlying compute. ### Can I install Matrix OS on my existing VPS? [#can-i-install-matrix-os-on-my-existing-vps] Matrix has a self-host installer for supported apt-based Linux servers. Review the current requirements and security responsibilities before using it publicly. ### Is a raw VPS more private? [#is-a-raw-vps-more-private] Privacy depends on provider, configuration, access controls, logging, backups, and operator behavior. A raw interface is not automatically a more private system. Compare the actual data and security model for your use case. # How to run Claude Code and Codex in parallel URL: /blog/run-claude-code-and-codex-in-parallel Use Claude Code and Codex together with isolated worktrees, bounded responsibilities, independent runtimes, and one review queue. You can run Claude Code and Codex in parallel on the same project when each agent has a separate Git worktree, branch, terminal, port range, and development database. Give them independent deliverables and merge their work through one human-controlled review queue. ## What work should Claude Code and Codex do in parallel? [#what-work-should-claude-code-and-codex-do-in-parallel] A useful split produces artifacts that can be evaluated independently: * Claude Code fixes a specific backend issue while Codex adds frontend tests. * Codex implements a bounded change while Claude Code reviews the resulting branch. * Claude Code investigates a failure while Codex reproduces it in a separate environment. * Each agent attempts the same bug on separate branches for comparison. A human chooses one approach. Avoid assigning both agents to “work on the feature.” That usually produces two partial implementations, two different assumptions about the API, and a merge conflict in the files that matter most. ## How do you isolate both agents in the same repository? [#how-do-you-isolate-both-agents-in-the-same-repository] ```bash git fetch origin git worktree add ../repo-claude -b agent/claude origin/main git worktree add ../repo-codex -b agent/codex origin/main ``` Start each tool from its own directory: ```bash cd ../repo-claude && claude cd ../repo-codex && codex ``` Do not let two writing agents share a checkout even if they promise to edit different files. Generated files, formatters, package locks, Git state, and test artifacts are shared surfaces. ## How do you keep both agents running remotely? [#how-do-you-keep-both-agents-running-remotely] ```bash matrix run -it --session claude-billing -- bash -lc 'cd ~/projects/repo-claude && claude' matrix run -it --session codex-tests -- bash -lc 'cd ~/projects/repo-codex && codex' ``` Detach with `Ctrl-\ Ctrl-\`. Both processes remain on the Matrix computer after the laptop disconnects. [Matrix Symphony](/symphony) is designed to make multiple agent runs and their review state easier to inspect. ## Why are separate worktrees not enough? [#why-are-separate-worktrees-not-enough] File isolation is not enough. Assign unique values such as: ```bash # Claude worktree PORT=3101 DATABASE_URL=postgresql://localhost/repo_claude # Codex worktree PORT=3102 DATABASE_URL=postgresql://localhost/repo_codex ``` Use disposable data for migrations and destructive tests. Never give either agent production credentials merely because the remote computer is isolated from your laptop. ## How do you review and merge two agent branches? [#how-do-you-review-and-merge-two-agent-branches] Review the first completed branch, rerun its tests, and merge it. Then rebase the second branch onto the updated target and run tests again. Parallel agents create work concurrently. Integration is still an ordered engineering decision. Track useful throughput rather than agent count: * reviewable tasks completed, * tests passing after integration, * conflicts per branch, * human review time, * rework caused by incorrect assumptions. ## Common questions about using Claude Code and Codex together [#common-questions-about-using-claude-code-and-codex-together] ### Is it better to have Claude review Codex or vice versa? [#is-it-better-to-have-claude-review-codex-or-vice-versa] Either can provide a useful second pass, but model review is not a substitute for tests and accountable human review. Keep the reviewer agent read-only until you deliberately request a follow-up patch. ### Can both agents use the same database? [#can-both-agents-use-the-same-database] They can for read-only work. Concurrent tests, fixtures, migrations, and writes should use separate databases or schemas. ### Which agent should get which task? [#which-agent-should-get-which-task] Route by demonstrated performance in your repository, not general reputation. Track completion quality, review time, test success, and rework for each task class. # How to run Claude Code on a VPS URL: /blog/run-claude-code-on-vps Install Claude Code on a remote Linux server, keep it alive with a persistent terminal, secure access, and reconnect after your laptop closes. To run Claude Code on a VPS, provision a Linux server, create a non-root user, install your development toolchain and Claude Code, authenticate through Claude’s supported login flow, clone the repository, and run the agent inside `tmux` or another persistent terminal. The VPS now provides the uptime, so your laptop can disconnect or sleep. ## What size VPS do you need? [#what-size-vps-do-you-need] Claude Code itself is not the only workload. Budget for the repository, package manager, language server, tests, database, builds, and preview server. | Workload | Starting point | Watch for | | ---------------------------------- | ------------------- | ----------------------------- | | One agent, small project | 2 vCPU, 4 GB RAM | Large dependency installs | | Agent plus dev server and database | 4 vCPU, 8 GB RAM | Browser tests and builds | | Multiple agents | 8+ vCPU, 16+ GB RAM | Concurrent tests and disk use | These are starting points, not guarantees. Measure CPU, memory, disk, and build time against your own repository. ## 1. How should you secure the VPS user? [#1-how-should-you-secure-the-vps-user] Use your provider’s console to create an Ubuntu or Debian-style VPS. Connect using the provider’s documented SSH process, update the system, create a developer user, and use SSH keys rather than a reusable password. Keep the application, database, and agent ports behind the firewall unless you intentionally proxy them through an authenticated TLS endpoint. Do not run an autonomous coding agent as `root`. A mistaken command should not automatically become a machine-wide change. ## 2. How do you install Claude Code on the VPS? [#2-how-do-you-install-claude-code-on-the-vps] Install Git, your language runtime, build tools, and Claude Code using Anthropic’s current official instructions. Commands change, so verify the install method against the official documentation on publication day. Launch `claude` interactively and complete its supported account authentication. Do not copy browser cookies, laptop private keys, or undocumented credential files to the server. ## 3. How should the VPS access GitHub? [#3-how-should-the-vps-access-github] The GitHub CLI provides a supported browser/device flow: ```bash gh auth login --hostname github.com --web mkdir -p ~/projects cd ~/projects git clone git@github.com:owner/repo.git ``` If you use SSH, generate a new key on the VPS and register only its public key. Give the server access only to repositories it needs. ## 4. How do you keep Claude Code running after SSH disconnects? [#4-how-do-you-keep-claude-code-running-after-ssh-disconnects] Install and start `tmux`: ```bash tmux new -s claude cd ~/projects/repo claude ``` Detach with `Ctrl-b`, then `d`. Later, reconnect and attach: ```bash ssh developer@your-server tmux attach -t claude ``` `tmux` protects the terminal session from an SSH disconnect. It does not survive a stopped VPS or reboot by itself. It also cannot save a process killed by low memory, a full disk, expired credentials, or a crash. A common mistake is to start `claude` directly after SSH login, close the laptop, and assume the server will keep it alive. The server is still running, but the foreground process may receive a hangup when SSH disappears. Start `tmux` first. ## 5. What should an unattended VPS session be allowed to do? [#5-what-should-an-unattended-vps-session-be-allowed-to-do] Use a dedicated branch, restrict the task, require tests, and stop before deployment or destructive operations. Keep production credentials off the development VPS. Add spending alerts with the model provider and infrastructure provider, and inspect disk usage before large builds. ## When is a managed workspace easier than a raw VPS? [#when-is-a-managed-workspace-easier-than-a-raw-vps] A raw VPS gives maximum control, but you own SSH hardening, TLS, session tooling, backups, updates, browser access, routing, and recovery. Matrix Cloud provisions a dedicated remote computer with persistent terminals, files, browser access, and agent workflows around it. Matrix can also be [self-hosted on your own VPS](/docs/self-host). If you want the persistent machine without operating every layer, follow the [Matrix quickstart](/docs/quickstart). For the full tradeoff, see [Matrix OS versus a raw VPS](/blog/matrix-os-vs-vps). ## Common questions about running Claude Code on a VPS [#common-questions-about-running-claude-code-on-a-vps] ### Will Claude Code keep running after SSH disconnects? [#will-claude-code-keep-running-after-ssh-disconnects] Only if it is running inside a persistent session such as `tmux`, `screen`, or a durable platform terminal. A foreground process tied directly to a dropped SSH connection can terminate. ### Does a VPS make unattended Claude Code safe? [#does-a-vps-make-unattended-claude-code-safe] No. It improves uptime, not judgment. Use least privilege, isolated branches, no production secrets, bounded tasks, logs, tests, and human review. ### Is a cheap VPS enough? [#is-a-cheap-vps-enough] It may be enough for one agent on a small repository. Builds, test suites, browser automation, databases, and parallel agents determine the real requirement. # How to run Claude Code overnight safely URL: /blog/run-claude-code-overnight-safely Use scoped tasks, isolated branches, least privilege, checkpoints, and review gates for safer unattended Claude Code sessions. To run Claude Code overnight safely, put the task in an isolated branch or worktree, remove production access, define an explicit stopping condition, require tests and a written summary, and keep deployment and destructive changes behind human approval. A persistent computer solves uptime. It does not make an unbounded prompt safe. ## What should you give Claude Code overnight? [#what-should-you-give-claude-code-overnight] Choose work with clear inputs, measurable outputs, and a reversible result: * add tests to named modules, * upgrade one dependency and report failures, * reproduce and attempt one documented bug, * draft release notes from merged pull requests, * run a static-analysis cleanup on a defined directory, * prepare a pull request without merging it. Avoid broad instructions such as “fix everything,” production deployments, irreversible migrations, billing changes, secret rotation, or tasks that require product judgment at every step. ## Put limits around the run [#put-limits-around-the-run] ### Isolate the files [#isolate-the-files] Create a dedicated worktree and branch. The agent should not share a mutable checkout with you or another writing agent. ### Remove credentials it does not need [#remove-credentials-it-does-not-need] Use the minimum repository and service permissions required. Do not place production database credentials, cloud administrator keys, customer exports, or unrestricted deployment tokens in the environment. ### Keep dangerous commands gated [#keep-dangerous-commands-gated] Keep approval requirements for destructive commands and external writes. “Unattended” should mean the agent can continue safe development work, not that every command is pre-approved. ### Define where the task stops [#define-where-the-task-stops] Name the directories it may edit, the tests it must run, and the conditions that require it to stop and leave a question. ### Stop at a reviewable artifact [#stop-at-a-reviewable-artifact] The acceptable overnight output is a branch, diff, log, report, or draft pull request. A human decides whether it ships. ## A prompt we would use for an overnight run [#a-prompt-we-would-use-for-an-overnight-run] ```text Work only on issue #318 in the current worktree. Allowed: - edit packages/billing and its tests - run the billing unit and integration tests - create commits on the current branch - open a draft pull request Stop and report instead of proceeding if: - the fix requires a production credential or deployment - a database migration would remove or rewrite data - the change expands outside packages/billing - the relevant tests fail for a reason unrelated to your changes Before finishing, provide: 1. root cause 2. files changed 3. tests run and exact result 4. remaining risks 5. draft PR link, if created ``` ## How do you keep Claude Code running all night? [#how-do-you-keep-claude-code-running-all-night] If Claude Code runs locally, laptop sleep stops useful execution. Run it on a secured VPS under a persistent terminal or on a managed Matrix computer. On Matrix: ```bash matrix run -it --session overnight-318 -- bash -lc 'cd ~/projects/issue-318 && claude' ``` Detach with `Ctrl-\ Ctrl-\`. The remote session continues after your laptop disconnects. See the full [persistent Claude Code guide](/blog/keep-claude-code-running-after-laptop-closes). ## What should you review in the morning? [#what-should-you-review-in-the-morning] Do not start with the prose summary. Start with `git status`, the commits, and the diff. Then inspect test output, new dependencies, permission changes, generated files, and network-facing configuration. Rerun important tests in a clean environment. We would reject an overnight result that says “all tests pass” but does not preserve the command and output. The artifact matters more than the claim. If the task touched authentication, authorization, payments, cryptography, migrations, CI secrets, deployment, or dependency supply chains, use a specialist human review before merging. ## Common questions about overnight Claude Code runs [#common-questions-about-overnight-claude-code-runs] ### Can Claude Code safely deploy overnight? [#can-claude-code-safely-deploy-overnight] That is a much higher-risk workflow than preparing a reviewable change. Keep production deployment behind explicit approval unless you have a mature, constrained automation system with rollback and monitoring. ### Should I use full permissions for an overnight run? [#should-i-use-full-permissions-for-an-overnight-run] No. Grant the least capability that completes the task. Convenience during one run is not worth turning a prompt mistake into an account-wide or production-wide change. ### What should an overnight agent produce? [#what-should-an-overnight-agent-produce] A reviewable artifact: a branch, draft pull request, test log, investigation report, or patch. It should not silently merge or deploy its own work. # How to run Gemini CLI remotely on an always-on computer URL: /blog/run-gemini-cli-remotely Run Gemini CLI on a persistent cloud computer, reconnect from any device, and avoid unsafe credential and terminal setups. Run Gemini CLI remotely by installing it on an always-on Linux computer, authenticating it there through a supported Google flow, cloning the repository, and starting the CLI inside a persistent terminal. Your laptop or phone becomes the client. The remote computer owns the files, processes, and uptime. ## How do you install Gemini CLI on a remote server? [#how-do-you-install-gemini-cli-on-a-remote-server] Google’s Gemini CLI requires a supported Node.js version. Verify the current requirement in the official documentation, then install the CLI: ```bash npm install -g @google/gemini-cli gemini --version gemini ``` Complete the displayed authentication flow. Depending on the account and provider mode, you may also need a Google Cloud project or API configuration. Keep credentials in the remote user’s protected environment and never paste secrets into prompts or shared logs. ## How do you keep Gemini CLI running after SSH disconnects? [#how-do-you-keep-gemini-cli-running-after-ssh-disconnects] SSH to the server as a non-root user and start a persistent terminal: ```bash tmux new -s gemini cd ~/projects/my-repo gemini ``` Detach with `Ctrl-b`, then `d`, and reconnect with `tmux attach -t gemini`. If you start `gemini` directly in the SSH shell, a dropped connection can take the process with it. Secure the server with SSH keys, firewall rules, updates, backups, and a trusted access layer. Do not put an unauthenticated web terminal on the public internet. ## When does a managed persistent workspace help? [#when-does-a-managed-persistent-workspace-help] Matrix supports coding agents inside the same persistent computer and named-session model. Install the chosen tool during setup or from the terminal, authenticate it through its own flow, then run: ```bash matrix run -it --session gemini-main -- bash -lc 'cd ~/projects/my-repo && gemini' ``` Detach with `Ctrl-\ Ctrl-\`. You can return from the browser or CLI without restarting the repository environment. See [Matrix coding-agent documentation](/docs/coding-agents). ## Can Gemini CLI share a server with other coding agents? [#can-gemini-cli-share-a-server-with-other-coding-agents] If Gemini CLI runs alongside Claude Code, Codex, or OpenCode, do not point several writing agents at one checkout. Create separate worktrees and assign distinct branches, terminal sessions, ports, and databases. ```bash git worktree add ../repo-gemini -b agent/gemini origin/main ``` Require a diff, tests, and a summary before accepting work. Remote execution improves availability. It does not remove the need for review. ## Common questions about remote Gemini CLI sessions [#common-questions-about-remote-gemini-cli-sessions] ### Does Gemini CLI continue when my laptop sleeps? [#does-gemini-cli-continue-when-my-laptop-sleeps] Only when Gemini CLI is running on another computer that stays online and the terminal session is persistent. A locally running CLI cannot continue useful execution while the laptop sleeps. ### Can I use Gemini CLI through a phone? [#can-i-use-gemini-cli-through-a-phone] Use the phone as a browser or secure terminal client connected to the remote computer. Complex code review is still better performed on a larger screen. ### Can Gemini CLI share a repository with another agent? [#can-gemini-cli-share-a-repository-with-another-agent] It can share Git history, but concurrent writing agents should use separate worktrees and branches to avoid overwrites and ambiguous diffs. # How to run multiple Claude Code sessions in parallel URL: /blog/run-multiple-claude-code-sessions Run parallel Claude Code sessions without agents overwriting files, sharing branches, or fighting over ports and databases. You can run multiple Claude Code sessions at once. Give each one its own Git worktree, branch, and terminal. If the sessions start applications or tests, they also need separate ports and development data. For two read-only sessions, opening two terminals in the same checkout is probably enough. It stops being enough when both agents write files. One agent runs a formatter while another edits the same module. The resulting diff belongs cleanly to neither task. ## What does each Claude Code session need? [#what-does-each-claude-code-session-need] Think of every agent as a developer who needs an isolated desk: | Resource | Share it? | Recommended setup | | ---------------------- | ---------: | ----------------------------------------------- | | Git history | Yes | One repository | | Working directory | No | One worktree per agent | | Branch | No | One branch per task | | Terminal | No | One named session per agent | | Application port | No | Assign a unique port | | Development database | Usually no | Separate database or schema | | Production credentials | No | Do not give unattended agents production access | Claude Code also supports subagents and isolated worktree sessions. A subagent is useful when one main session needs a bounded investigation. Separate top-level sessions fit tasks that should produce independent branches and reviews. ## How do you run multiple sessions on the same repository? [#how-do-you-run-multiple-sessions-on-the-same-repository] Start from a clean main checkout: ```bash git fetch origin git worktree add ../project-billing -b agent/billing origin/main git worktree add ../project-tests -b agent/tests origin/main git worktree add ../project-docs -b agent/docs origin/main ``` Open a terminal in each directory and start Claude Code: ```bash cd ../project-billing claude ``` Give each session a result you can review on its own. “Improve the application” is not a parallel task. “Fix issue 318, run the billing tests, and leave the result on the current branch” is. ## How do you install the Matrix CLI? [#how-do-you-install-the-matrix-cli] Install the `matrix` command on the computer you use to connect. Choose Homebrew, npm, or the standalone installer: ```bash # Homebrew (macOS or Linux) brew install finnaai/tap/matrix # npm (requires Node.js 20 or newer) npm install -g @finnaai/matrix # Standalone binary (no Node.js required) curl -fsSL https://get.matrix-os.com | sh ``` Then sign in and check the connection: ```bash matrix login --profile cloud matrix doctor matrix whoami ``` You can also try the CLI without installing it globally with `npx --yes @finnaai/matrix ` or `pnpm dlx @finnaai/matrix `. See the [Matrix CLI documentation](/docs/cli) for installation details and command options. If you would rather delegate the setup, follow the [Matrix Quickstart](/docs/quickstart) and paste its setup prompt into Claude Code, Codex, or another terminal agent. The agent can install the CLI, start the login flow, verify the connection, set up a persistent session, and help authenticate GitHub. You still approve browser or device-login prompts yourself; the setup does not require giving the agent your local private keys or credentials. ## How do you keep parallel sessions running remotely? [#how-do-you-keep-parallel-sessions-running-remotely] On a Matrix computer, named sessions keep the agent processes on the remote machine: ```bash matrix run -it --session billing -- bash -lc 'cd ~/projects/project-billing && claude' matrix run -it --session tests -- bash -lc 'cd ~/projects/project-tests && claude' ``` Detach without terminating the session with `Ctrl-\ Ctrl-\`. The processes continue on the Matrix computer after your laptop disconnects. You can reconnect later through the browser or CLI. Matrix does not remove the need for Git isolation. It gives those isolated sessions a computer that stays online, plus durable terminals, files, previews, and a common review surface. [See how persistent Claude Code sessions work](/blog/keep-claude-code-running-after-laptop-closes). ## Why do isolated worktrees still collide? [#why-do-isolated-worktrees-still-collide] Assign each worktree a small environment file that is not committed: ```bash # billing worktree PORT=3101 DATABASE_URL=postgresql://localhost/project_billing # tests worktree PORT=3102 DATABASE_URL=postgresql://localhost/project_tests ``` If every branch points at the same mutable database, the sessions are not isolated. One agent may reset fixtures while another is halfway through an integration test. The second agent reports a flaky test even though the database caused it. Use disposable databases or containers for destructive migrations and review anything that targets a shared environment. ## How should you merge parallel agent work? [#how-should-you-merge-parallel-agent-work] Parallel execution should converge into a serial review queue: 1. Require each agent to run the relevant tests. 2. Inspect its diff and terminal log. 3. Rebase or merge the branch onto the latest target branch. 4. Run integration tests again. 5. Merge one branch. 6. Refresh the remaining branches before accepting them. The highest agent count is not the goal. Useful throughput is completed, reviewed work with a low collision rate. ## When not to parallelize [#when-not-to-parallelize] Keep work sequential when tasks modify the same central files, depend on an unsettled architecture decision, require the same test fixture, or would produce a merge conflict larger than the time saved. Two agents editing the same database schema and API contract are usually not independent tasks. For a managed view of long-running parallel sessions, branches, diffs, and review status, see [Matrix Symphony](/symphony). For the isolation mechanics, continue with [Git worktrees for coding agents](/blog/git-worktrees-for-coding-agents). ## Common questions about parallel Claude Code sessions [#common-questions-about-parallel-claude-code-sessions] ### Can two Claude Code sessions edit the same repository? [#can-two-claude-code-sessions-edit-the-same-repository] They can, but they should not edit the same working directory concurrently. Give each session a separate Git worktree and branch. ### How much memory do parallel Claude sessions need? [#how-much-memory-do-parallel-claude-sessions-need] The agent process is only part of the load. Language servers, package installs, test runners, browsers, databases, and dev servers often use more memory. Start with two sessions, observe memory and CPU, then scale. ### Should I use Claude subagents or separate sessions? [#should-i-use-claude-subagents-or-separate-sessions] Use subagents for delegated research or bounded supporting work inside one parent task. Use separate sessions for independently reviewable changes that need isolated files and terminals. # How to run OpenCode on a VPS URL: /blog/run-opencode-on-vps Install OpenCode on a remote Linux server, configure a model provider safely, and keep sessions available after disconnecting. To run OpenCode on a VPS, create a secured non-root Linux account, install OpenCode using its current official instructions, configure your chosen model provider, clone the repository, and launch OpenCode inside `tmux`, `zellij`, or another persistent terminal. The session then survives your laptop disconnecting. ## What does the OpenCode VPS need? [#what-does-the-opencode-vps-need] Choose enough CPU, memory, and disk for the project’s build, test, database, and language-server workload. Add a non-root developer user, SSH key authentication, a firewall, security updates, and backups. Do not expose development ports directly unless they sit behind deliberate authentication and TLS. ## How do you install and authenticate OpenCode? [#how-do-you-install-and-authenticate-opencode] Use OpenCode’s official installer and verify the version. Its provider flexibility is useful, but it also means authentication differs by model provider. Use the provider’s supported environment or login method, grant the smallest necessary scope, and avoid placing keys in shell history, prompts, committed files, or logs. Then authenticate GitHub and clone the repository: ```bash gh auth login --hostname github.com --web mkdir -p ~/projects cd ~/projects git clone git@github.com:owner/repo.git ``` Generate VPS-specific SSH credentials if needed and register only the public key. ## How do you keep OpenCode running after disconnecting? [#how-do-you-keep-opencode-running-after-disconnecting] ```bash tmux new -s opencode cd ~/projects/repo opencode ``` Detach using `Ctrl-b`, then `d`. Reconnect later with: ```bash ssh developer@your-server tmux attach -t opencode ``` This protects against a network disconnect. It does not make the process reboot-proof or protect it from resource exhaustion. If a large test run exhausts memory, `tmux` will faithfully preserve a session containing a killed process. ## When does a persistent workspace remove useful setup work? [#when-does-a-persistent-workspace-remove-useful-setup-work] Matrix can install OpenCode as a developer tool and run it beside other coding agents on the same dedicated computer: ```bash matrix run -it --session opencode-main -- bash -lc 'cd ~/projects/repo && opencode' ``` Matrix adds managed browser access, persistent named sessions, files, previews, and review surfaces around the underlying computer. See the [coding-agent guide](/docs/coding-agents) or [self-host Matrix on a VPS](/docs/self-host). ## Can OpenCode run beside Claude Code or Codex? [#can-opencode-run-beside-claude-code-or-codex] Use one worktree per writing agent. Give OpenCode a defined branch and task, assign unique application resources, and keep production credentials out of the environment. Require tests and review before merging. ## Common questions about running OpenCode on a VPS [#common-questions-about-running-opencode-on-a-vps] ### Which model does OpenCode use on a VPS? [#which-model-does-opencode-use-on-a-vps] OpenCode supports multiple providers. The VPS does not determine the model. Your OpenCode configuration and provider credentials do. ### Does OpenCode keep running after SSH disconnects? [#does-opencode-keep-running-after-ssh-disconnects] Only when it runs inside a persistent session or platform terminal. A process attached directly to the dropped SSH shell may terminate. ### Should OpenCode run as root? [#should-opencode-run-as-root] No. Use a non-root development account and least-privilege credentials so a mistaken command has a smaller blast radius. # How to use Claude Code from your phone URL: /blog/use-claude-code-from-phone Start, monitor, and resume Claude Code work from a phone without leaving your laptop awake or exposing an insecure terminal. There are three practical ways to use Claude Code from a phone: Claude Code Remote Control, Claude Code on the web, or a browser/terminal connected to a persistent remote computer. The right choice depends on whether the work must use your laptop’s existing environment or can run entirely in the cloud. ## Which Claude Code mobile setup should you use? [#which-claude-code-mobile-setup-should-you-use] | Method | Where the process runs | Laptop must remain on? | Best for | | --------------------------- | ----------------------------- | ---------------------: | ---------------------------------------------------------- | | Claude Code Remote Control | Your local computer | Yes | Continuing a local session from another device | | Claude Code on the web | Anthropic-managed environment | No | Delegating GitHub-based tasks | | VPS plus mobile SSH | Your VPS | No | Operators who want infrastructure control | | Matrix OS browser workspace | Your Matrix computer | No | Persistent files, terminals, previews, and multiple agents | Remote Control changes where you type. It does not move the process off your computer. If the laptop sleeps or loses power, that session cannot keep working. Claude Code on the web runs remotely, but it is a different workflow from maintaining a long-lived development computer with your own services and files. ## How do you use a persistent Claude Code session from your phone? [#how-do-you-use-a-persistent-claude-code-session-from-your-phone] First provision a Matrix computer and finish the [Matrix quickstart](/docs/quickstart). In its terminal, authenticate GitHub through GitHub’s supported browser flow, clone the repository, and start a named agent session: ```bash matrix run -it --session mobile-work -- bash -lc 'cd ~/projects/my-repo && claude' ``` Detach with `Ctrl-\ Ctrl-\`. The process remains on the remote Matrix computer. From your phone, open `app.matrix-os.com`, sign in, and open the terminal to inspect or steer the session. Closing the phone browser closes the viewer. The process continues on the remote computer. ## What is actually practical on a phone? [#what-is-actually-practical-on-a-phone] Mobile is a good control surface for: * checking whether tests completed, * answering a blocking question, * reading a short diff summary, * stopping a session that is going in the wrong direction, * approving the next bounded step, * confirming that a draft pull request exists. Large diffs are miserable on a phone. So are merge conflicts, visual regressions, and permission changes. Use mobile access to steer and triage. Do the serious review on a larger screen. ## Do not expose a raw terminal to the internet [#do-not-expose-a-raw-terminal-to-the-internet] Avoid opening SSH or a web terminal with only a weak password. Use a managed authenticated workspace or secure a self-managed server with SSH keys, a trusted network or VPN, TLS, firewall rules, updates, and backups. Never paste private keys or long-lived API credentials into a mobile chat. ## What should you do before leaving your desk? [#what-should-you-do-before-leaving-your-desk] Before disconnecting: 1. Put the task on its own branch or worktree. 2. State the exact allowed scope. 3. Require tests and a written summary. 4. Tell the agent to stop before deployment, secret changes, or destructive migrations. 5. Detach from the remote session instead of terminating it. When you check from your phone, do not ask only “did it work?” Look for changed files, test output, logs, and a draft PR. Agents are very good at producing a confident summary of an incomplete result. For the broader persistence model, read [how to keep Claude Code running after your laptop closes](/blog/keep-claude-code-running-after-laptop-closes). To compare all remote approaches, read [Claude Code remote options](/blog/claude-code-remote-options). ## Common questions about using Claude Code from a phone [#common-questions-about-using-claude-code-from-a-phone] ### Can Claude Code run directly on iPhone or Android? [#can-claude-code-run-directly-on-iphone-or-android] The practical workflow is to use the phone as a client while Claude Code runs on a laptop or remote environment. A phone is not usually the development host for a real repository, toolchain, test suite, and dev server. ### Does Claude Remote Control keep working when my laptop sleeps? [#does-claude-remote-control-keep-working-when-my-laptop-sleeps] No remote interface can keep a local process executing while its underlying computer is asleep. Use a remote cloud environment if the laptop must be allowed to sleep. ### Can I review a Claude Code pull request from my phone? [#can-i-review-a-claude-code-pull-request-from-my-phone] Yes, but use mobile review for triage and small diffs. Save complicated behavioral and security review for a larger screen and a reproducible development environment. # How to run Claude Code in the cloud URL: /blog/claude-code-cloud Run terminal-based Claude Code on Matrix, authenticate it, complete a bounded repository task, and reconnect to inspect the result. Running **Claude Code in the cloud** means the terminal agent executes on a remote computer instead of your laptop. On Matrix, you connect to that computer through the desktop app, browser or CLI, run Claude in its repository directory, and inspect the resulting files and tests. This guide covers terminal-based Claude Code on a Matrix computer. Claude's own managed web tasks are a different execution path; see the [official overview of Claude Code surfaces](https://code.claude.com/docs/en/overview) before choosing a setup. ## When a cloud computer helps [#when-a-cloud-computer-helps] A remote computer is useful when a repository needs a stable tool environment, a task should outlast a laptop connection, or several isolated agent tasks need access to the same project history. It is less useful when a short local task already works well and remote access would only add setup. Local sleep pauses execution. A remote host can keep working while the laptop sleeps, provided the host remains running and the task is not waiting on authentication, permissions or human input. Remote compute removes one dependency; it does not guarantee completion. ## Set up Claude Code on Matrix [#set-up-claude-code-on-matrix] 1. Open [Matrix Cloud](https://app.matrix-os.com) or install the [Matrix desktop app](/docs/desktop). 2. Sign in, select a computer and complete provisioning if needed. 3. Open **Terminal** and create a separate session for a sample task. 4. Prepare your repository using its normal setup instructions. 5. Check Claude is installed and follow its supported authentication flow. ```bash pwd git status --short claude --version claude ``` If the executable is missing, use [Claude's official installation instructions](https://code.claude.com/docs/en/overview). Matrix sign-in does not automatically authenticate Claude or grant access to a private repository. Authenticate the tools on the remote computer. The [Matrix quickstart](/docs/quickstart) covers provisioning and CLI access. Use the [setup and reconnect tutorial](/blog/keep-claude-code-running-after-laptop-closes) for a complete first task. ## Choose the computer for the workload [#choose-the-computer-for-the-workload] Use [current plans and pricing](/#pricing) to compare resources and lifecycle behavior. A short supervised task and sustained background work can require different plans. Review the terms shown at checkout, including trial eligibility and any automatic renewal. Agent-provider access can have separate costs and limits. Check both the computer and Claude's access requirements before estimating the cost of repeated runs. ## Make the first task reviewable [#make-the-first-task-reviewable] Start with a small repository and one acceptance test. For example: ```text Fix the one failing test in this sample repository. Preserve the test's intended behavior and keep the change small. Run the tests, summarize the diff and stop for review. Do not commit, push or deploy. ``` Watch the start of the task to resolve any permissions it needs. When it finishes, inspect `git diff` and rerun the relevant tests. A completion message is not a substitute for checking the output. ## Reconnect to the same work [#reconnect-to-the-same-work] Keep the session name and computer selection. Disconnect the viewing client, reopen Matrix and return to the same Terminal session. Check whether the task is running, finished or awaiting input, then inspect the files it changed. From the CLI, list sessions before connecting: ```bash matrix login --profile cloud matrix shell ls matrix shell connect -c your-session-name ``` Replace `your-session-name` with the existing session you intend to inspect. The connect command can create a session when it does not exist; that is not recovery of an old conversation. Files can persist after a process exits, but a reboot stops processes. Provider errors and credential expiry can interrupt an agent. Inspect the last output and use the agent's supported resume path rather than assuming every reconnection restores all context. ## Parallel tasks and recurring work [#parallel-tasks-and-recurring-work] Give each writing agent a separate worktree, branch, terminal and any required port or test database. Sharing one checkout is not safe isolation just because the agents have different task descriptions. Follow [the parallel Claude and Codex guide](/blog/run-claude-code-and-codex-in-parallel). Recurring work adds a scheduler, credentials, retained state and failure handling. Confirm the actual [Hermes setup](/hermes) or [Symphony workflow](/symphony) available to your computer before relying on it. A terminal task does not automatically become a scheduled integration or a notification to a team channel. ## Matrix, a raw VPS or a managed agent? [#matrix-a-raw-vps-or-a-managed-agent] Choose a raw VPS if you want to operate the server, access controls and terminal tools yourself. Choose a provider-managed agent task if that provider's repository and review flow meets your needs. Choose a Matrix computer when you want direct terminal/file access and a workspace you can return to across tasks and terminal agents. Compare the same small workload across your options: setup steps, correct output, human review effort, lifecycle behavior and current cost. Keep claims about another product tied to its current documentation rather than a general category label. # 12 Claude Code tips for shorter review cycles URL: /blog/claude-code-tips-cut-review-cycles Twelve practical ways to give Claude Code clearer constraints, produce smaller diffs, and reduce avoidable review rounds. Code review is where momentum dies. You hand off a PR, wait a day, get comments, fix things, wait again. If you're using Claude Code, you already have an AI coding agent capable of serious work — but most developers are running it at maybe 40% of its potential. The rest is in how you prompt, structure, and run it. These 12 techniques focus on one outcome: fewer review cycles, faster merges, and code that actually passes the first time. *** ## 1. Write the Acceptance Criteria Before the Prompt [#1-write-the-acceptance-criteria-before-the-prompt] Ambiguity at the start is the single biggest driver of review rework. Before you type anything to Claude Code, write out what "done" looks like. Be specific: what should the function return, what edge cases matter, what should it explicitly not do. A prompt that opens with "here's what passing looks like" gives Claude Code a target. A prompt that opens with "add a feature" gives it permission to guess. *** ## 2. Give Claude Code Your Existing Test Suite First [#2-give-claude-code-your-existing-test-suite-first] If your repo has tests, load them into context before asking for new code. Claude Code will write to match what it sees — same assertion style, same mock setup, same naming conventions. This alone takes a significant bite out of the "your test doesn't follow our conventions" comment. *** ## 3. Use CLAUDE.md to Encode Your Team's Standards [#3-use-claudemd-to-encode-your-teams-standards] Claude Code reads a `CLAUDE.md` file at the root of your project. This is where you put the things your team reliably argues about in reviews: error handling patterns, logging conventions, variable naming, which libraries to reach for. Write it once. Every session after that, Claude Code follows those rules without being reminded. Reviewers stop commenting on style because the style is already right. *** ## 4. Break Large Tasks Into Scoped Sub-Tasks [#4-break-large-tasks-into-scoped-sub-tasks] Asking Claude Code to "refactor the auth module" produces a large, hard-to-review diff. Asking it to "extract the token validation logic into a separate function with its own tests" produces something a reviewer can evaluate in five minutes. Smaller, scoped tasks mean smaller PRs. Smaller PRs get reviewed faster and merged with fewer comments. This is one of the most reliable levers for cutting cycle time. *** ## 5. Ask for the Diff Explanation Before You Open the PR [#5-ask-for-the-diff-explanation-before-you-open-the-pr] Before you submit, ask Claude Code to explain what it changed and why. Read that explanation. If you can't follow it, the reviewer won't be able to either. This catches the "what is this doing?" comments before they happen. It also gives you the raw material for a better PR description — which reviewers appreciate and which speeds up approval. *** ## 6. Request Tests and Implementation Together [#6-request-tests-and-implementation-together] When you ask for implementation first and tests second, you often get tests written to pass the existing code rather than tests that verify the intended behavior. Ask for both at once, or ask for the tests first. "Write a failing test for this behavior, then write the implementation that makes it pass" is a prompt structure that produces output reviewers actually trust. *** ## 7. Specify the Scope of Changes Explicitly [#7-specify-the-scope-of-changes-explicitly] Claude Code will sometimes touch files you didn't intend to change — not a bug, just it trying to be thorough. But a PR that modifies eight files when you expected three creates real review overhead. Add a constraint: "Only modify files in `/src/payments`. Do not touch the config files or the test helpers." Reviewers see a focused diff and don't have to wonder why unrelated files changed. *** ## 8. Use Branch-Per-Task and Review the Diff Before Pushing [#8-use-branch-per-task-and-review-the-diff-before-pushing] Run Claude Code on a fresh branch for each task. Before you push, do a `git diff main` yourself. You will catch things: a debug log left in, a commented-out block, a dependency added to the wrong file. Catching these yourself takes two minutes. Catching them in review takes two hours of back-and-forth. *** ## 9. Ask Claude Code to Self-Review Against Your Criteria [#9-ask-claude-code-to-self-review-against-your-criteria] Once it produces code, ask: "Review this against the acceptance criteria I gave you at the start. What's missing or wrong?" It will often surface its own gaps. This isn't a substitute for human review — it's a filter. Reviewers see cleaner work and can spend their attention on the things that actually require judgment. *** ## 10. Run Long Tasks Without Keeping Your Laptop Open [#10-run-long-tasks-without-keeping-your-laptop-open] One underrated source of review friction is incomplete work. You kick off a long Claude Code task, your laptop sleeps, local execution pauses, and you return to unfinished work. Tasks that must continue while your laptop sleeps should run on remote compute. [Matrix OS](https://matrix-os.com) gives you a dedicated hosted computer where Claude Code can continue across laptop sleep and local disconnects. Git checkpoints and process supervision still matter for host restarts or failed commands. The [post on keeping Claude Code running after your laptop closes](/blog/keep-claude-code-running-after-laptop-closes) covers the setup in detail. *** ## 11. Parallelize Independent Tasks Across Sessions [#11-parallelize-independent-tasks-across-sessions] If you have three independent issues to fix, running them sequentially means three times the wait. Claude Code can work on each in a separate session, and when those sessions run in the cloud, they execute simultaneously without competing for your machine's resources. The result is a batch of PRs ready at the same time instead of a queue. Reviewers can pick them up in parallel too. *** ## 12. Keep a Prompt Log for Recurring Task Types [#12-keep-a-prompt-log-for-recurring-task-types] If you're asking Claude Code to do the same category of thing repeatedly — writing migration scripts, adding API endpoints, fixing a class of linter errors — keep a log of the prompts that worked well. Refine them over time. A prompt that took three iterations to get right the first time should take one the next time. Your review cycle shortens because the output quality compounds with each iteration of the prompt, not just each iteration of the code. *** ## Putting It Together [#putting-it-together] The common thread here is specificity. Claude Code performs best when it knows exactly what you want, what constraints apply, and what passing looks like. Reviewers approve work fastest when the diff is small, focused, and explained. The techniques in the middle of this list are about prompting. The ones toward the end are about infrastructure. Both matter. A well-crafted prompt that dies halfway through because your laptop went to sleep produces the same outcome as a bad prompt: rework. If you're running Claude Code on tasks that take more than a few minutes, it's worth reading about [what a cloud computer for agents](/blog/cloud-computer-for-agents) actually looks like in practice. The goal is the same as everything else on this list: get to a finished, reviewable result the first time. *** ## FAQs [#faqs] ### What is the most important Claude Code tip for reducing PR review comments? [#what-is-the-most-important-claude-code-tip-for-reducing-pr-review-comments] Writing clear acceptance criteria before you prompt is the highest-leverage change. When Claude Code has a specific target, it produces code that matches your intent rather than guessing — which eliminates the most common category of review comments: "this doesn't do what I expected." ### How do I get Claude Code to follow my team's coding conventions? [#how-do-i-get-claude-code-to-follow-my-teams-coding-conventions] Create a `CLAUDE.md` file at the root of your project and document your conventions there. Claude Code reads this file at the start of each session. You can include error handling patterns, naming rules, preferred libraries, and anything else your team enforces in reviews. ### Why does Claude Code sometimes change files I didn't ask it to touch? [#why-does-claude-code-sometimes-change-files-i-didnt-ask-it-to-touch] Claude Code tries to keep changes consistent across the codebase. If you want to limit the scope, say so explicitly: "Only modify files in this directory. Do not touch anything else." Scope constraints produce smaller, more focused diffs. ### Should I ask for tests and implementation at the same time? [#should-i-ask-for-tests-and-implementation-at-the-same-time] Yes, or ask for tests first. Asking for implementation first and tests second often produces tests written to pass the existing code rather than tests that verify the intended behavior. Asking for both together — or using a test-first approach — produces more trustworthy output. ### How do I stop Claude Code tasks from dying when my laptop closes? [#how-do-i-stop-claude-code-tasks-from-dying-when-my-laptop-closes] For tasks that need to continue while your laptop is asleep, run Claude Code on a remote computer. Matrix OS provides a persistent workspace that remains available across local disconnects. A remote host improves uptime, but you should still use Git branches, checkpoints, and process supervision for recoverability. ### What's the best way to review Claude Code output before opening a PR? [#whats-the-best-way-to-review-claude-code-output-before-opening-a-pr] After Claude Code finishes, ask it to review its own work against the acceptance criteria you gave it at the start. Then run `git diff main` yourself before pushing. Those two steps catch most obvious issues before reviewers ever see the code. ### Can I run multiple Claude Code tasks at the same time? [#can-i-run-multiple-claude-code-tasks-at-the-same-time] Yes, as long as the tasks are independent and don't share state. Running them in separate sessions on a cloud machine lets them execute in parallel without competing for local resources — especially useful when you have several small issues to fix and want them all ready for review at once. # OpenAI Codex CLI: how it works and when to use it URL: /blog/openai-codex-cli A practical guide to the OpenAI Codex CLI: what it is, how the agentic loop works, when to use it, and how to run it in persistent cloud sessions. OpenAI Codex CLI OpenAI's Codex CLI brings a capable AI coding agent directly into your terminal. No browser tab, no IDE plugin, no context switching. You describe what you want, and the agent reads your files, writes code, runs commands, and iterates — all from the command line. This guide covers what the Codex CLI actually is, how it works under the hood, when it makes sense to use it, and what to think about when you want it running beyond your local machine. *** ## What Is the OpenAI Codex CLI? [#what-is-the-openai-codex-cli] The Codex CLI is an open-source terminal agent built by OpenAI. It runs locally and connects to OpenAI's models to handle coding tasks through natural language prompts. Tell it something like "add input validation to the registration form" or "write tests for this module," and it reads your codebase, proposes changes, and can execute them directly. Worth clarifying: this is not the older Codex API — the code-completion model OpenAI deprecated in 2023. The CLI is an agentic tool. It takes multi-step actions, not single-shot responses. Codex separates filesystem and network sandboxing from approval policy. You choose what the agent may do inside the workspace and when it must ask before crossing a boundary. The exact configuration evolves, so use the [current OpenAI Codex documentation](https://developers.openai.com/codex/cli/) rather than relying on older mode names. That separation matters. A scoped refactor may permit workspace edits and test commands while still requiring approval for network access, changes outside the repository, or consequential operations. *** ## How the Codex CLI Works [#how-the-codex-cli-works] ### The Core Loop [#the-core-loop] When you run `codex` with a task, the agent follows a reasoning loop: read relevant files, plan the steps, apply changes, run commands to verify, and report back. Each step is visible in the terminal so you can follow along and interrupt if something looks off. The agent has access to your local filesystem and can run shell commands inside a sandboxed environment. By default it uses a network-disabled, read-only root filesystem with only your working directory writable — which limits the blast radius of mistakes. ### Authentication [#authentication] Codex supports OpenAI's current documented authentication methods, which may include signing in with an eligible ChatGPT account or using an API key. Use the method and billing model appropriate for your organization; do not copy browser cookies or unrelated credentials into a remote environment. ### Context Window and File Handling [#context-window-and-file-handling] The agent reads files from your working directory and passes relevant content into the model's context window. For large codebases, it selects files based on what seems relevant to the task rather than loading everything at once. Prompt quality matters here: the more specific your task description, the better the agent's file selection. ### Installation [#installation] Follow OpenAI's current installation instructions. One supported distribution method is the npm package: ```bash npm install -g @openai/codex ``` Once installed, authenticate through a supported method and run `codex` from a project directory. *** ## What the Codex CLI Is Good At [#what-the-codex-cli-is-good-at] The CLI handles a wide range of practical coding tasks well. **Refactoring and cleanup.** Ask it to rename a function across the codebase, extract a class, or simplify a complex conditional. It reads the relevant files, makes the changes, and shows you a diff before applying anything. **Writing tests.** Give it a module and ask for unit tests. It reads the implementation, infers expected behavior, and writes test cases for your review. **Bug fixes from descriptions.** Describe the bug in plain language and the agent traces through the code to find and fix the cause. This works best when the bug is localized to a few files. **Scaffolding new features.** Tell it to add an endpoint, a migration, or a new component following the patterns already in your project. It reads existing code for style and structure before generating anything new. **Documentation.** Ask it to write docstrings, update a README section, or generate an API reference from your source files. *** ## When the Codex CLI Is the Right Tool [#when-the-codex-cli-is-the-right-tool] The Codex CLI fits naturally into a focused work session where you're already in the codebase and want to delegate specific steps without switching tools. It's a good fit when tasks are well-scoped, local, and benefit from tight feedback loops — you see every step in the terminal and can approve or reject changes inline, which gives you more control than a background agent running asynchronously. ### When It Gets Complicated [#when-it-gets-complicated] When the CLI runs locally, it depends on your machine staying awake and on working network access. For short tasks, that is usually fine. For longer-running work, it can become a real constraint. Laptop sleep pauses useful work. A temporary network failure may interrupt an active model call even if the terminal process remains. If you want to start a task and inspect it from another device, run Codex on remote compute or use an appropriate managed Codex workflow. This is where developers start looking at persistent cloud environments. If you've run into the same problem with Claude Code, the post on [keeping Claude Code running after your laptop closes](/blog/keep-claude-code-running-after-laptop-closes) covers the same underlying issue from a different angle. *** ## Running Codex CLI in a Persistent Cloud Environment [#running-codex-cli-in-a-persistent-cloud-environment] If you want Codex CLI to run continuously without depending on your local machine, the practical answer is to run it on a dedicated cloud computer where sessions persist across disconnects. [Matrix OS](https://matrix-os.com) provisions a dedicated VPS for each user where AI coding agents — including Codex — run in persistent sessions. Start a Codex session, close your laptop, and the agent keeps working. Reconnect from any terminal or browser and pick up exactly where things left off. This matters most for longer tasks: a large refactor, batch test generation across multiple modules, or a background bug triage workflow. These are exactly the situations where a local session becomes a liability. Matrix OS also supports running multiple agents simultaneously on the same persistent machine with shared file state. If you use Codex for some tasks and Claude Code or Gemini CLI for others, they share the same codebase and environment without you rebuilding anything. That's the core idea behind what a [cloud computer for agents](/blog/cloud-computer-for-agents) actually means in practice. *** ## Codex CLI vs. Other Agent Options [#codex-cli-vs-other-agent-options] ### Codex CLI vs. Claude Code [#codex-cli-vs-claude-code] Both are terminal-based coding agents with similar agentic loops. The main differences are the underlying model (OpenAI for Codex, Anthropic's Claude for Claude Code), the approval flow UX, and community tooling. Some developers prefer one for certain task types and use both. Neither is inherently better — they have different strengths depending on the codebase and the work. ### Codex CLI vs. Cursor [#codex-cli-vs-cursor] Cursor is an IDE with AI features built in. The Codex CLI is a terminal agent with no IDE dependency. If you prefer working in a terminal or want to use the agent in CI or automation scripts, the CLI fits better. If you want inline suggestions and a visual editor, Cursor fits better. They serve different workflows. ### Codex CLI vs. Devin [#codex-cli-vs-devin] Devin packages the agent, managed environment, and task interface together. Codex CLI is a terminal agent that you can place on infrastructure you control. The tradeoff is managed delegation versus direct control of the runtime and tooling. *** ## Practical Tips for Getting the Most Out of Codex CLI [#practical-tips-for-getting-the-most-out-of-codex-cli] **Be specific about scope.** The agent performs better when you tell it exactly which files or modules to work in. "Refactor the auth module in `src/auth/`" is better than "clean up the auth code." **Use full auto mode carefully.** It's powerful for trusted, well-scoped tasks. For anything touching production configs or sensitive files, stick with auto-edit so you approve shell commands before they run. **Keep tasks atomic.** Break large changes into smaller tasks rather than asking the agent to do everything in one prompt. Smaller tasks produce cleaner diffs and are easier to review. **Review diffs before merging.** The agent writes code that's often good, but it's not infallible. Treat its output the way you'd treat a PR from a capable but new contributor: read it before you ship it. **Set your working directory intentionally.** The agent reads from your current directory. Start it from the right project root so it has the context it needs. *** ## FAQs [#faqs] **What models does the Codex CLI use?** The CLI connects to OpenAI's API and uses the `codex-1` model by default, which is optimized for agentic coding tasks. You can configure the model in the CLI settings if you want to use a different OpenAI model. **Is the Codex CLI free to use?** The CLI itself is free and open-source. You pay for API usage through your OpenAI account at standard rates. Costs depend on how much you run it and the size of the tasks. **Can the Codex CLI access the internet?** By default, the CLI runs in a sandboxed environment with network access disabled — an intentional safety measure. You can configure this if your tasks require network access. **Does the Codex CLI work on Windows?** The CLI is designed for Unix-like environments and works on macOS and Linux. Windows users can run it through WSL (Windows Subsystem for Linux). **What happens if I close my terminal while the agent is running?** A local terminal close may stop the attached process unless a session manager keeps it alive. If you want work to continue independently of the laptop, run the CLI inside `tmux` on a remote server or on a dedicated cloud computer. Preserve progress through Git rather than assuming the process will survive every failure. **Can I run Codex CLI alongside other agents like Claude Code?** Technically yes. The practical challenge is managing shared file state and avoiding conflicts. Running them in isolated sessions on a persistent cloud machine with shared file access is a cleaner approach than trying to manage this locally. **How does the Codex CLI handle large codebases?** It selects files relevant to your task rather than loading the entire codebase into context. For very large repositories, being explicit about which directories or files to focus on helps the agent work more accurately and efficiently. *** ## Conclusion [#conclusion] The Codex CLI is a practical, well-designed terminal agent for developers who want AI help without leaving the command line. It handles refactoring, test writing, bug fixes, and scaffolding well, and its approval modes give you real control over how much autonomy the agent has. The main limitation is that it runs locally. For tasks that need to outlast your laptop session — or workflows where you want Codex running alongside other agents on the same codebase — a persistent cloud environment solves the problem cleanly. If you want to run Codex and other agents in persistent sessions without managing your own infrastructure, take a look at [matrix-os.com](https://matrix-os.com). # E2B alternatives for persistent AI-agent workloads URL: /blog/e2b-alternative Compare E2B with Matrix OS, Daytona, Modal, and OpenHands by sandbox lifecycle, persistence, control, and operational model. E2B alternatives for persistent AI-agent workloads E2B provides isolated cloud sandboxes for agents and code execution. It is a good fit when software needs to create clean environments through an API, run work, preserve state for a defined period, and release the resources afterward. That is not the only shape of agent compute. Some teams want a durable development computer that keeps repositories, shells, services, and tools in place across many tasks. Others want reproducible workspaces, serverless functions, or an open-source agent platform. The right E2B alternative depends on which of those problems you are solving. ## What should you compare? [#what-should-you-compare] Start with the workload rather than a feature checklist: * **Lifecycle:** Is each job disposable, resumable, or expected to live indefinitely? * **State:** Should files survive one task, several tasks, or the lifetime of a project? * **Control:** Do you need an API sandbox, direct shell access, or a complete agent framework? * **Isolation:** Does each task need a fresh boundary, or does each developer need a durable computer? * **Operations:** Who owns images, updates, backups, credentials, and network policy? * **Cost:** Is usage-based billing or a fixed computer easier to predict? Plan limits and prices change. Verify current values with each provider before making a production decision. Primary references: [E2B documentation](https://e2b.dev/docs), [Daytona documentation](https://www.daytona.io/docs/), [Modal documentation](https://modal.com/docs), and [OpenHands documentation](https://docs.openhands.dev/). ## 1. Matrix OS: a persistent computer for agents [#1-matrix-os-a-persistent-computer-for-agents] [Matrix OS](https://matrix-os.com) treats the computer as the durable unit. Repositories, named terminals, dev servers, databases, and artifacts stay on the machine between sessions. Developers can run terminal agents such as Claude Code, Codex CLI, Gemini CLI, and OpenCode without tying their uptime to a laptop. This fits teams that want to return to the same environment every day or coordinate several agents through separate Git worktrees. Matrix Cloud manages the computer; self-hosted Matrix is available when the team wants to operate its own server. It is a less natural fit when an application needs to create thousands of short-lived sandboxes through an SDK. E2B is designed more directly for that programmatic sandbox pattern. ## 2. Daytona: reproducible development infrastructure [#2-daytona-reproducible-development-infrastructure] Daytona focuses on rapidly created development environments and infrastructure for running code safely. It is worth evaluating when reproducibility, API provisioning, and isolated workspaces matter more than keeping one named computer as the long-term home of a project. Compare its current persistence controls, storage model, image support, and pricing with the actual duration and concurrency of your jobs. Do not assume that "workspace" means the same lifecycle across providers. ## 3. Modal: serverless application and AI compute [#3-modal-serverless-application-and-ai-compute] Modal is built around functions, containers, jobs, schedules, and scalable compute. It is a strong candidate for batch work, inference, data processing, and services that fit its programming model. It is not a drop-in replacement for a developer computer. A terminal coding agent can sometimes be wrapped in a job, but the team should decide whether it wants to adapt the workflow to a serverless model or keep the agent inside a conventional long-lived environment. ## 4. OpenHands: an agent platform [#4-openhands-an-agent-platform] OpenHands is an open-source software-development agent platform rather than only a compute provider. It is relevant when the team wants to customize the agent layer, select model providers, or self-host more of the stack. That flexibility changes the operational boundary. Evaluate the hosted and self-hosted options separately, including how they handle runtimes, credentials, isolation, upgrades, and observability. ## How do the options differ? [#how-do-the-options-differ] | Option | Primary abstraction | Best fit | Main tradeoff | | --------- | ------------------------------------ | ---------------------------------------------------- | --------------------------------------------------------- | | E2B | API-created sandbox | Isolated programmatic code execution | Sandbox lifecycle is part of the application design | | Matrix OS | Persistent computer | Durable agent workspaces and direct developer access | Not optimized for high-volume disposable sandbox creation | | Daytona | Development workspace infrastructure | Reproducible isolated environments | Persistence and operations depend on the selected setup | | Modal | Serverless functions and containers | Elastic jobs, services, and AI compute | Stateful terminal workflows require adaptation | | OpenHands | Software-development agent platform | Customizable hosted or self-hosted agent workflows | Broader stack to evaluate and potentially operate | ## Which option should you choose? [#which-option-should-you-choose] Choose E2B when your product needs to create isolated sandboxes on demand and control them through an API. Choose Matrix OS when a project needs a stable computer that people and different terminal agents can share over time. A typical workflow uses one repository, one worktree per agent, persistent terminals, and pull requests as the review boundary. Choose Daytona when reproducible development environments are the central requirement. Choose Modal when the work naturally fits functions, containers, or scheduled jobs. Choose OpenHands when you are selecting an agent platform and value control over the agent stack. The key distinction is between a **sandbox created for a job** and a **computer retained for a project**. Neither is universally better. They optimize for different ownership and lifecycle models. For the Matrix model, see [Agents need a computer, not another chat box](/blog/cloud-computer-for-agents). For a direct infrastructure comparison, see [Matrix OS vs a VPS for AI coding agents](/blog/matrix-os-vs-vps). ## FAQs [#faqs] ### Is E2B limited to short tasks? [#is-e2b-limited-to-short-tasks] E2B sandbox duration and pause/resume behavior depend on its current product and plan configuration. Check the official documentation for current limits. The architectural question is whether your application should manage sandbox lifecycles or your team should keep a durable computer. ### Can these platforms run Claude Code or Codex CLI? [#can-these-platforms-run-claude-code-or-codex-cli] General-purpose Linux environments can often run terminal agents when their system and authentication requirements are met. Support, lifecycle, and the intended operating model vary, so verify each provider's current documentation. ### What does persistent compute mean here? [#what-does-persistent-compute-mean-here] It means the machine or workspace retains useful state between connections and tasks. That can include repositories, dependencies, services, terminals, and artifacts. Persistence does not remove the need for backups, Git branches, access controls, or process supervision. ### Can several agents share one environment? [#can-several-agents-share-one-environment] They can, but they should not edit the same working directory concurrently. Use one Git worktree and branch per agent, isolate ports and databases where needed, and merge through a review queue. # What is a cloud computer for AI agents? URL: /blog/cloud-computer-for-agents A practical guide to remote agent work: terminals, files, task outputs, persistence limits, and how to run your first Matrix workflow. A **cloud computer for AI agents** is a remote computing environment where the agent can work with a repository, terminal, files and installed tools. Your laptop connects to that environment to direct and inspect work. It does not have to execute every command itself. Matrix provides that computer with desktop, browser and CLI access. The useful output is concrete: a changed file, a test result, a draft or a running development service you can inspect. Start with the workflow you need, then decide whether a persistent computer is the right place to run it. ## What belongs on the computer? [#what-belongs-on-the-computer] A repository task usually needs more than a prompt. It needs source files, dependencies, a working directory, tool authentication and somewhere to put the output. Keeping those together can reduce repeated setup across tasks. | Part of the workflow | What to verify | | -------------------- | -------------------------------------------------------------------------------- | | Repository and files | The expected files are on the selected computer and changes are saved. | | Agent process | The agent is running, finished or waiting for input; these are different states. | | Terminal session | You can identify and reconnect to the intended session. | | Tool access | The agent has the authentication and permissions required for this task. | | Output | You can open the changed file, diff, test log or generated artifact. | ## A first workflow: fix one failing test [#a-first-workflow-fix-one-failing-test] Use a sample repository before granting an agent a broad task. Open Matrix, select a ready computer and launch Terminal. Prepare the repository there and run its normal test command so you know the starting state. Ask the agent to fix one failure, preserve the existing tests, rerun them and explain the diff. Stop for human review before committing or publishing. This makes completion observable: the test passes and the change actually addresses the failure. Open the file in Files or Editor, inspect the diff and run the test command again. The [Claude Code walkthrough](/blog/keep-claude-code-running-after-laptop-closes) takes you through setup and reconnect. The [Codex CLI guide](/blog/openai-codex-cli) covers another terminal-agent route. ## Persistence has boundaries [#persistence-has-boundaries] Saved files, a live process and a recoverable agent conversation are separate properties. Files can remain on disk when a process exits. A host reboot stops running processes. A provider limit or expired credential can interrupt an otherwise healthy computer. Disconnecting the viewing client does not itself suspend the remote host. Work can continue in a persistent remote session while the computer remains running. Check the selected plan's lifecycle and test the agent's reconnect behavior; do not assume every surface can resume or steer every agent identically. Keep useful progress in files and Git. When returning to a task, inspect the last output before starting another agent against the same working directory. ## How does this differ from a chat project or a sandbox? [#how-does-this-differ-from-a-chat-project-or-a-sandbox] A chat project can organize instructions and source material. A cloud computer also provides an execution environment you can operate directly. That distinction matters when the task needs a shell, dependencies, repository state or long-lived development services. An API sandbox can be a good fit for isolated jobs with explicit creation and cleanup. A persistent computer can fit work that returns to the same environment between tasks. Both categories have different lifecycle and billing options, so compare the specific service configuration you would use. A raw VPS also gives you remote compute. Choose it when you want to operate the server and access tooling yourself. Matrix packages a computer with desktop/browser access, terminals and file surfaces. See the [VPS comparison](/blog/matrix-os-vs-vps) for the tradeoff. ## Multiple agents need isolation [#multiple-agents-need-isolation] Two writing agents should use separate worktrees and branches. Distinct sessions alone do not isolate their files, development ports or databases. Assign independent tasks and integrate their results through one deliberate review sequence. The [worktree guide](/blog/git-worktrees-for-coding-agents) covers repository isolation. Start with one reliable task before scaling to [Claude Code and Codex in parallel](/blog/run-claude-code-and-codex-in-parallel). ## Getting started with Matrix [#getting-started-with-matrix] Follow the [quickstart](/docs/quickstart) to sign in, select or provision a computer and authenticate your agent. Use the [desktop guide](/docs/desktop) if you want a native window into that computer. Review [current plans](/#pricing) and the terms at checkout for the workload you intend to run. For a business workflow, begin with synthetic input and a reviewable draft. The [company OS series](/blog/company-os-ai-agents-series) describes broader architecture and pilot ideas; it should not be read as a claim that every proposed integration or governance control is already available. # How to keep Claude Code running after you close your laptop URL: /blog/keep-claude-code-running-after-laptop-closes Run Claude Code on a Matrix cloud computer, reconnect to the same terminal, and review its files and tests after your laptop sleeps. To keep a terminal-based Claude Code task working while your laptop sleeps, run it on a remote computer in a persistent terminal session. This guide uses Matrix: sign in, open the cloud Terminal, run a small task, reconnect and inspect the output. If you only need the short answer, read [what happens to Claude Code when a laptop closes](/blog/does-claude-code-keep-running-after-laptop-closes). Sleep pauses local execution; it does not necessarily kill the process or erase its work. ## Before you start [#before-you-start] You need a running Matrix computer, a supported Claude Code account or API access, and a repository you can safely use for a small task. Provisioning Matrix does not automatically authenticate Claude Code or grant it access to GitHub. Check [current Matrix pricing](/#pricing), the selected computer's lifecycle and the terms at checkout. Use a plan suitable for background work. An agent waiting for input, a stopped computer or an expired provider credential cannot keep making progress simply because the terminal is remote. ## Setting up a persistent Claude Code session [#setting-up-a-persistent-claude-code-session] ### 1. Sign in and select your computer [#1-sign-in-and-select-your-computer] Open [Matrix Cloud](https://app.matrix-os.com) or follow the [desktop installation guide](/docs/desktop). Approve the desktop in your browser and choose the computer you intend to use. First-time hosted setup also includes plan selection, checkout and provisioning; the [quickstart](/docs/quickstart) describes those steps. ### 2. Open Terminal on the cloud computer [#2-open-terminal-on-the-cloud-computer] Open **Terminal** from the Matrix desktop and create a separate session for the task. Keep its name so you can find it when you reconnect. Prepare the repository inside that terminal, using the repository's own setup instructions. ```bash pwd git status --short claude --version ``` If Claude Code is missing or needs authentication, follow its [official setup instructions](https://code.claude.com/docs/en/overview). Authenticate on the cloud computer. Do not paste an API key into a screenshot or a shared task brief. ### 3. Give Claude one bounded task [#3-give-claude-one-bounded-task] Start Claude from the repository directory: ```bash claude ``` Try a task whose result you can verify: ```text Fix the one failing test in this sample repository. Keep the change small and preserve the existing tests. Run the test command, explain the diff, and stop for review. Do not commit, push, publish or deploy anything. ``` Watch the initial run long enough to resolve authentication or permission prompts. A task waiting for approval is paused, even when the computer itself is healthy. ### 4. Reconnect before relying on an overnight run [#4-reconnect-before-relying-on-an-overnight-run] Leave the remote session running and disconnect the viewing client. Reopen Matrix, select the same computer and open the same Terminal session. Check whether it is still working, finished or waiting for you. The useful test is observable progress: a later test log, a completed command or changed files. Do not infer success merely because a terminal tab reappeared. Closing the entire cloud computer, stopping the process and disconnecting the client are different operations. ### 5. Inspect what changed [#5-inspect-what-changed] In the repository, review the result: ```bash git status --short git diff --stat git diff ``` Run the repository's test command yourself. Open the affected files in **Files** or **Editor** if you prefer a visual review. Commit or open a pull request only after checking the diff and tests. ## Attach from the CLI [#attach-from-the-cli] The [Matrix CLI quickstart](/docs/quickstart) provides a terminal route to the same computer: ```bash matrix login --profile cloud matrix shell ls matrix shell connect -c blog-demo ``` Use the actual existing session name instead of `blog-demo` when reconnecting. The connect command can create a session when it is missing; opening a new session is not proof of recovering the previous agent conversation. ## What to hand to Claude Code overnight [#what-to-hand-to-claude-code-overnight] Good first candidates have a small scope and a clear stopping point: reproduce one bug, add a missing test, prepare release notes from a fixed commit range, or investigate one failing build. Save results in files and leave consequential decisions for review. Avoid a first task such as “fix every open issue.” It combines uncertain scope, repository access, external actions and potentially conflicting changes. Prove the bounded workflow first, then expand it. ## Running multiple agents in parallel [#running-multiple-agents-in-parallel] Use a separate Git worktree, branch and named terminal for each writing agent. Give each worktree its own development ports and test database where needed. Two branches in the same checkout do not isolate simultaneous edits. Follow [Git worktrees for coding agents](/blog/git-worktrees-for-coding-agents) and [running Claude Code and Codex in parallel](/blog/run-claude-code-and-codex-in-parallel) when one task is working reliably. ## Matrix OS vs a raw VPS [#matrix-os-vs-a-raw-vps] A VPS with tmux can provide the same basic separation between your laptop and remote execution. You operate the server, session tools and access setup. Matrix adds a desktop/browser interface, computer selection, terminals and file access around the hosted environment. Choose based on the workflow you need and the infrastructure you want to manage. ## FAQs [#faqs] ### Will every session survive a restart? [#will-every-session-survive-a-restart] No. Remote execution removes dependence on the laptop being awake; it does not eliminate host restarts, process crashes, provider limits or authentication failures. Keep progress in Git and files, inspect the last output, and use the agent's supported resume behavior when necessary. ### Can I check progress from my phone? [#can-i-check-progress-from-my-phone] Use the supported [mobile access workflow](/blog/use-claude-code-from-phone). Verify the controls you need on your device; do not assume every desktop action or agent recovery path has mobile parity. ### How much does it cost? [#how-much-does-it-cost] Review [current plans](/#pricing) and the terms shown at checkout. Agent-provider access may have separate charges. Select a computer lifecycle that fits the length and background behavior of your task.