Getting started

This page takes you from free account to your first run: sign up, download and install Motriz, answer the first-run question, connect a provider, add a product, and start work. If you want the vocabulary first, read Core concepts.

Requirements

• An Apple Silicon Mac running macOS 13 or newer. Motriz is macOS-only and ships arm64 builds only.
• At least one AI provider for local desktop agent work: an existing Claude Code, Codex, or ChatGPT login, or an API key for one of the API providers. The managed First Decision in Motriz Cloud does not require your own provider. See Providers and models.
• A free Motriz account for the standard onboarding path and managed/cloud capabilities. Create it in Motriz Cloud; no payment method is required. Signed-out Local mode remains available during the account transition.
• A repository is optional. An idea product starts with nothing but a conversation.

Install Motriz

1. Create your free account.

   Sign up in Motriz Cloud with Google, GitHub, or email and password. The free account includes one product journey and a managed First Decision — you can take one product question to a cited Build, Reshape, Test, Pause, or Stop call right in Motriz Cloud, before the desktop app is installed, with no provider configured.

2. Download the DMG.

   Once you are signed in, choose Download desktop in the Motriz Cloud header.

3. Drag Motriz into Applications.

   Open the disk image, drag the app across, then launch it. Releases are signed and notarized with Apple, so Gatekeeper accepts them without any bypass steps. If macOS asks you to confirm opening an app downloaded from the internet, choose Open.

First launch: what are you starting with?

With no products yet, Motriz opens on a welcome screen headed "Add a product." — "Start from wherever the product actually is." On the very first run it asks what you are starting with, as three answer cards plus a Skip link:

• "Start from an idea or product question" — Start the product journey with your co-founder.
• "Design a product change" — Continue from a repository with Product Design. This preselects the Product design mode on your first Start work view.
• "Continue from a repository" — Continue its product journey from the real code.

Your answer is stored once and never overwritten, and the question never reappears. Answering also sends Motriz's single anonymous first-entry signal (app version plus the chosen mode — nothing else); skipping stores and sends nothing. See Privacy and safety for the full telemetry contract.

The welcome screen also reminds you: "First time here? Connect a provider in Settings → Providers." Do that next.

Connect a provider

Open Settings → Providers ("Connect the AI CLIs and API keys Motriz runs your agents with."). Every provider stays visible whether or not it is configured; a badge shows ready or not set up. There are two setup styles:

One connected provider is enough to start; you can pick models per run later. Keys and paths are stored encrypted in the local database and secret fields never echo a saved value. Details, model catalogs, and defaults are in Providers and models; the rest of the panel is covered in Settings.

Add your first product

Everything in Motriz opens as a product with up to four fixed destinations — Dashboard, Journey, Co-founder, Build (see Products and the Dashboard). The add-product dialog offers two paths. Reach it from the welcome screen or, later, from the product switcher's "Add a product…" entry.

Start from an idea

1. Choose "Start from an idea or product question".

   Think through what to build, change, or validate with your co-founder.

2. Name it, or don't.

   The name field is optional. Left blank, the product is created as "Untitled product" and renames itself automatically from your idea brief later.

3. Set up your co-founder.

   Pick a model, a reasoning effort, and — for supporting models — the Fast tier. "Becomes this product’s default. Changeable anytime from the co-founder conversation."

4. Click "Create product".

   Motriz creates the product with one empty, durable co-founder conversation and drops you straight into it. No message is sent and no model runs: "Your co-founder starts only when you begin the conversation." A "Suggested" chip offers a first message; nothing runs until you send.

From here, the conversation is the front door to the product journey. Read The co-founder for how that relationship works.

Continue from a repository

1. Choose "Continue from a repository".

   Motriz scans your home directory for Git repositories. Use the search box, Rescan, or "Choose another folder…" below the list if yours lives somewhere unusual (when nothing was found at all, the button reads "Choose a folder…").

2. Check the repository's status.

   Each candidate is labeled "Not in Motriz", "Journey not started", or "Journey active". A "Journey active" repository is already a product — the button becomes "Open product" and "Nothing will be created or changed."

3. Answer "What needs direction?".

   Four options: "Understand why it stalled", "Decide the next product move", "Reshape the product", "Build a known change". Optionally describe "The current constraint". This tells the co-founder where to point first.

4. Set up your co-founder and confirm.

   The button reads "Create product" or "Start product journey" depending on status. "Motriz analyzes the repository in the background — normal work stays available."

"The repository stays where it is. Existing history and work are preserved." — Motriz connects the repository in place and never moves files. You land on the product's Dashboard, where a quiet chip tracks the background context build and all four destinations are live, Build included.

Run your first work

Press ⌘N or click Start work at the top of the sidebar's Work section. The view asks "What are we doing in {product name}?" with mode cards — Chat, Build (the default), and Product design; products that are building also get a fourth Co-founder card. Nothing persists until you send the first message.

For a Build run, describe one bounded task with a verifiable outcome, then send. Live activity streams into the conversation, the Send button becomes Stop, and the sidebar's Build row shows a running count. When the run lands changes, review them before anything ships — see Work and runs and Build, tasks, and review.

If your product is an idea still on the journey, Start work skips the mode cards and reads "Talk it through with your co-founder" — every start routes into the same durable conversation. That is deliberate: product guidance stays in one place, and building opens up when there is something real to build.

How updates arrive

Motriz updates itself. It checks motriz.ai/downloads/latest.json at most once per hour; when a newer build exists, a pill appears at the top of the sidebar footer: "Update ready (v{version}) — restart". Click it and Motriz downloads the archive, verifies its checksum and its Apple code signature against the Motriz Developer ID, swaps the app in place, and relaunches. While it works the pill reads "Updating…"; a problem shows "Update failed: {message}".

Updates never interrupt work: while runs are active the pill is disabled and reads "Update ready (v{version}) — stop active runs first". There is a single release channel and no update setting to manage. If an update misbehaves, see Troubleshooting; version and local paths live under Settings → About, documented in the Reference.