Start here
Getting started
Install Motriz, connect an AI provider, add a codebase or venture, and run your first task.
Requirements
- An Apple Silicon Mac running macOS 13 or newer.
- At least one supported AI provider. The fastest setup is usually an existing Claude Code, Codex, or ChatGPT login.
- A local folder or Git repository for code work. Ventures can begin without either.
Install Motriz
- Download the DMG.
Get the current build from motriz.ai.
- Open the disk image.
Drag Motriz into Applications, then launch it. Releases are signed and notarized for macOS.
- Allow the first launch.
If macOS asks for confirmation, verify the app name and publisher context, then choose Open.
Installed releases check for newer builds in the background. When an update is available, Motriz shows an update action in the sidebar; you must stop active runs before installation.
Connect your first provider
Open Settings → Providers. Each provider remains visible even when it is not configured, and the status badge explains whether it is ready.
| Provider | First setup |
|---|---|
| Claude Code | Install the claude CLI, run claude auth login, and let Motriz auto-detect it. Set a custom CLI path only if detection fails. |
| Codex | Install the codex CLI, run codex login, and let Motriz auto-detect it. Motriz uses an isolated runtime home while preserving your login. |
| ChatGPT | Choose Sign in with ChatGPT and complete authorization in your browser. |
| API providers | Paste the relevant API key. Azure OpenAI also needs its endpoint; Anthropic can optionally use a custom base URL. |
| Ollama Cloud | Save an Ollama Cloud API key. Motriz supplies local repository and shell tools to the model. |
Provider keys, paths, and connection details are encrypted in the local Motriz database. Secret fields never echo the saved value back into the UI.
Answer the first-run question
On an empty installation, Motriz asks what you are starting with. This is a routing shortcut, not a permanent workspace type.
- An idea opens the venture path.
- A feature asks for a repository and preselects Product Design.
- An existing repository asks for a repository and preselects Build.
- Skip dismisses the question without sending a first-entry signal.
Add a code project
- Choose Add project.
Motriz scans configured repository roots and groups GitHub repositories separately from other Git repositories.
- Select a discovered repository or paste a path.
A pasted path only needs to be an existing directory. Git is recommended for change review and GitHub workflows, but it is not required.
- Open a new thread.
Select Chat, Build, or Product Design. The thread is not created until you send the first message.
- Choose the run configuration.
For Build, keep the default single-agent mode, choose a configured model and effort, and describe a bounded first task.
Start a venture
- Choose Start venture.
Give it a name, or leave the field empty so Motriz can name it from the first conversation.
- Choose the co-founder model.
You can change the model, reasoning effort, and Fast tier later from the conversation composer.
- Talk naturally.
The co-founder opens the conversation and asks one focused question at a time. Rough input is expected.
Run your first Build task
A useful first task has a clear outcome and enough context to verify it. For example:
Inspect this repository's test setup, identify the smallest missing check for the authentication callback, add that regression test, fix the root cause, and run the focused validation.During the run, Motriz streams activity, elapsed time, messages, tool work, token usage, estimated provider cost when available, and file changes. You can stop the run from the composer.
Before you scale up
- Confirm the provider and model are available before assigning them to tasks or flows.
- Commit or stash unrelated work before giving a Build agent broad instructions.
- Use a flow only when separate roles improve the result; a single agent is the first-class default.
- Connect integrations only when you want agents to read or modify those remote workspaces.