Getting Started
Maestrly is a desktop workspace for AI-assisted work: chats, Maestro orchestration, Git worktrees, terminals, an embedded editor and browser, notes, and memory. It is local-first, but not local-only: conversations and project state stay on your computer, while AI inference goes directly from the app to the provider you choose.
This guide takes you from installation to a reviewed first result.
1. Install Maestrly
Maestrly App is open source under the MIT License and is still in 0.x: a minor version can include breaking changes, which the changelog marks as such. Download the official installers and their SHA-256 checksums (SHA256SUMS.txt) from GitHub Releases.
| Platform | Packages | Signing |
|---|---|---|
| macOS 13 or later, Apple silicon (arm64) | DMG and ZIP | Signed and notarized |
| Linux x64 | AppImage and DEB | Not code-signed |
| Windows x64 | NSIS installer | Not code-signed |
Only arm64 macOS builds are published; there is no official build for Intel Macs. Linux and Windows packages are not code-signed; compare their checksum with SHA256SUMS.txt before installing.
Open the app without a Maestrly account: there is no Maestrly login, license service, telemetry, or automatic diagnostic upload. Local workspace features do not require a provider account.
To build from source instead, follow the prerequisites and commands in the README. A source build runs in a separate development profile and is not a release.
2. Keep Maestrly updated
Packaged releases check GitHub Releases when they start and every six hours. When a new version exists, a card offers Download update; nothing downloads until you accept. Restart to update installs it. Settings → Updates shows your current version, Check now, and the Release notes.
- macOS, Windows, and AppImage builds update themselves.
- DEB packages cannot update themselves: Maestrly notifies you, and you download and install the new package.
- Beta, development, and unpackaged builds do not check for updates, and prereleases are never offered.
If you use a bot server, the app keeps it on the app's version.
3. Connect an AI provider
Open Settings → Maestrly Chat → Accounts and choose Add account. You need your own provider account, subscription, or API key. Maestrly is not affiliated with the providers and does not resell their services.
Subscriptions sign in through the provider's own flow, with no API key:
| Subscription | Sign-in |
|---|---|
| ChatGPT plan, through the built-in Codex runtime | Sign in with ChatGPT |
| Claude Pro, Max, Team, or Enterprise | Sign in with Claude |
| GitHub Copilot | Sign in with GitHub |
| Cursor | Sign in with Cursor |
| Grok or SuperGrok, through xAI | Sign in with Grok |
| Google AI Pro or Ultra, through Google's Antigravity server | Sign in with Google |
When a subscription needs a runtime that is not installed yet, its button reads Install & connect. Google AI downloads the Antigravity server on first sign-in. Claude signs in through the Claude Code installed on this computer, which Maestrly does not bundle: when it is missing or too old, the Claude card shows the official installer for your system, with a copy button and a link to Anthropic's setup guide. Run it in a terminal, then choose Check again; no restart is needed.
Two other ways to connect:
- API keys: Add provider offers presets such as OpenAI, Anthropic, Gemini, OpenRouter, and DeepSeek, or accepts any base URL in an OpenAI-compatible or native Anthropic format.
- ChatGPT Web Companion: converse in ChatGPT itself, connected to a Maestrly project through a secure tunnel. Setup needs an OpenAI Platform API key, used only for the tunnel, and a one-time app created in ChatGPT's Developer mode.
Provider sign-in is separate from Maestrly and does not create a Maestrly account. Credentials stay on this computer.
Before continuing:
- confirm the account shows Connected;
- check which models your plan offers (Filter models hides the ones you do not want in the picker);
- review the provider's pricing and data controls.
Model names and availability can change independently of Maestrly. If a model is missing, verify access in the provider's own console.
4. Start with a standalone chat
You do not need a project. Open Chats → New chat. A standalone chat gets its own working folder in the app profile, its own saved permissions, and the personal memory shared by your chats. It does not inherit any project's instructions or memory. Its folder is a working location, not an operating-system sandbox.
Your first standalone chat starts in Ask mode with Ask for approval permissions, so the agent answers without changing files. Since 0.21.0, later ones start in the mode you last chose in a standalone chat, and always with Ask for approval. Since 0.18.0 they answer in a conversational voice that matches yours; project conversations keep the concise style of coding work. Pick a model in the composer, and switch to Agent when you want it to create files or run commands. Chat, models, and context explains modes, context, and attachments.
5. Add a project
For work on a codebase, open the Workspaces tab and choose + (Add workspace). The Add project dialog can Open existing, Create new, or Clone Git repository. Repositories stay at their existing paths.
Then start a conversation in the project. The New conversation dialog asks for:
- the Conversation experience: Standard (one agent that switches between modes) or Maestro (orchestrates agents and routes each step);
- the branch: a New branch created from a base, or an Existing branch;
- the Work mode: Worktree (an isolated folder outside your repository, on its own branch) or Local (your repository folder, after a preview of any local changes).
Once a Projects folder is set in Settings → Execution, you can also ask a chat to clone or create a project and start working in it. See Projects and Git.
6. Make your first request
Start with a bounded request: state the outcome, the relevant files or constraints, and how the result should be verified. The prompt and selected context are sent directly to the chosen AI provider for inference under that provider's terms.
7. Review before delivery
Watch tool calls, answer approval requests, and inspect the resulting diff. Run the relevant checks before committing, merging, or deploying. AI output can be incomplete or incorrect; you remain responsible for actions and delivered changes.
8. Build the workflow
- Chat, models, and context covers accounts, modes, context, attachments, voice, and memory.
- Concepts defines the building blocks and network boundaries.
- Maestro, agents, and skills turns useful instructions into reusable setups.
- Tools and MCP controls what agents can reach.
- Plugins adds skills, MCP servers, and agents from Git that work with every model.
- Projects and Git covers worktrees, local checkouts, and delivery.
- Bots (Experimental) runs agents on a server you host.
- Remote workspaces (Experimental) runs your chats and workspaces on that server.
- Mobile app follows your bots and server chats from iOS or Android.
- Artifacts publishes web pages from agents to your bot server.
- Usage and costs explains provider billing and limits.
Need help? Visit Support.