Primeiros passos

O Maestrly é um ambiente desktop para trabalho assistido por IA: chats, orquestração com o Maestro, worktrees Git, terminais, editor e navegador integrados, notas e memória. Ele é local-first, mas não local-only: conversas e estado dos projetos ficam no seu computador, enquanto a inferência de IA vai direto do app ao provedor escolhido.

Este guia leva você da instalação até o primeiro resultado revisado.

1. Instalar o Maestrly

O Maestrly App é open source sob a licença MIT e ainda está na série 0.x: uma versão minor pode trazer mudanças incompatíveis, que o changelog identifica como tal. Baixe os instaladores oficiais e os checksums SHA-256 (SHA256SUMS.txt) em GitHub Releases.

Plataforma	Pacotes	Assinatura
macOS 13 ou mais recente, Apple silicon (arm64)	DMG e ZIP	Assinados e notarizados
Linux x64	AppImage e DEB	Sem assinatura de código
Windows x64	Instalador NSIS	Sem assinatura de código

Só há builds arm64 para macOS; não existe build oficial para Macs Intel. Os pacotes de Linux e Windows não têm assinatura de código; compare o checksum com o SHA256SUMS.txt antes de instalar.

Abra o app sem conta Maestrly: não há login Maestrly, serviço de licença, telemetria nem envio automático de diagnósticos. Os recursos locais do workspace não exigem conta de provedor.

Para compilar a partir do código, siga os requisitos e comandos do README. Uma build do código roda em um perfil de desenvolvimento separado e não é uma versão oficial.

2. Manter o Maestrly atualizado

As versões empacotadas consultam as GitHub Releases ao abrir e a cada seis horas. Quando há versão nova, um cartão oferece Baixar atualização; nada é baixado até você aceitar. Reiniciar para atualizar faz a instalação. Em Configurações → Atualizações você vê a versão atual, Verificar agora e as Notas da versão.

• As builds de macOS, Windows e AppImage se atualizam sozinhas.
• Pacotes DEB não se atualizam sozinhos: o Maestrly avisa, e você baixa e instala o pacote novo.
• Builds beta, de desenvolvimento ou não empacotadas não verificam atualizações, e pré-lançamentos nunca são oferecidos.

Se você usa um servidor de bots, o app o mantém na mesma versão do app.

3. Conectar um provedor de IA

Abra Configurações → Maestrly Chat → Contas e escolha Adicionar conta. Você precisa da sua própria conta, assinatura ou chave de API no provedor. O Maestrly não é afiliado aos provedores e não revende os serviços deles.

As assinaturas entram pelo fluxo do próprio provedor, sem chave de API:

Assinatura	Login
Plano do ChatGPT, pelo runtime Codex integrado	Entrar com ChatGPT
Claude Pro, Max, Team ou Enterprise	Entrar com Claude
GitHub Copilot	Entrar com GitHub
Cursor	Entrar com Cursor
Grok ou SuperGrok, pela xAI	Entrar com Grok
Google AI Pro ou Ultra, pelo servidor Antigravity do Google	Entrar com Google

Quando uma assinatura precisa de um runtime que ainda não está instalado, o botão mostra Instalar e conectar. A Google AI baixa o servidor Antigravity no primeiro login. O Claude entra pelo Claude Code instalado neste computador, que não vem com o Maestrly: quando ele falta ou está desatualizado, o cartão do Claude mostra o instalador oficial para o seu sistema, com um botão de copiar e um link para o guia de instalação da Anthropic. Rode o comando num terminal e escolha Verificar de novo; não precisa reiniciar.

Há mais duas formas de conectar:

• Chaves de API: Adicionar provedor oferece atalhos como OpenAI, Anthropic, Gemini, OpenRouter e DeepSeek, ou aceita qualquer URL base nos formatos compatível com OpenAI ou Anthropic nativo.
• ChatGPT Web Companion: converse no próprio ChatGPT, conectado a um projeto do Maestrly por um túnel seguro. A configuração pede uma chave de API da OpenAI Platform, usada só para o túnel, e um app criado uma única vez no Developer mode do ChatGPT.

O login no provedor é independente do Maestrly e não cria uma conta Maestrly. As credenciais ficam neste computador.

Antes de continuar:

• confirme que a conta aparece como Conectado;
• confira quais modelos seu plano oferece (Filtrar modelos esconde do seletor os que você não quer);
• revise preços e controles de dados do provedor.

Nomes e disponibilidade de modelos podem mudar independentemente do Maestrly. Se um modelo não aparecer, confira o acesso no console do próprio provedor.

4. Começar com um chat avulso

Você não precisa de projeto. Abra Chats → Novo chat. Um chat avulso tem uma pasta de trabalho própria no perfil do app, permissões salvas só dele e a memória pessoal compartilhada pelos seus chats. Ele não herda instruções nem memória de nenhum projeto. A pasta é um local de trabalho, não um sandbox do sistema operacional.

O seu primeiro chat avulso começa no modo Pergunta com a permissão Solicitar aprovação, então o agente responde sem alterar arquivos. Desde a 0.21.0, os seguintes começam no último modo que você escolheu num chat avulso, sempre com Solicitar aprovação. Desde a 0.18.0 eles respondem num tom de conversa que acompanha o seu; as conversas de projeto mantêm o estilo direto do trabalho com código. Escolha um modelo na caixa de mensagem e mude para Agente quando quiser que ele crie arquivos ou rode comandos. Chat, modelos e contexto explica modos, contexto e anexos.

5. Adicionar um projeto

Para trabalhar em um código, abra a aba Workspaces e escolha + (Adicionar workspace). A janela Adicionar projeto permite Abrir existente, Criar novo ou Clonar repositório Git. Os repositórios continuam em seus caminhos atuais.

Depois, inicie uma conversa no projeto. A janela Nova conversa pede:

1. a Experiência da conversa: Standard (um agente que alterna entre modos) ou Maestro (orquestra agentes e roteia cada etapa);
2. a branch: uma Nova branch criada a partir de uma base, ou uma Branch existente;
3. o Modo de trabalho: Worktree (uma pasta isolada fora do repositório, com branch própria) ou Local (a pasta do repositório, depois de uma prévia das alterações locais).

Com uma Pasta de projetos definida em Configurações → Execução, você também pode pedir a um chat que clone ou crie um projeto e comece a trabalhar nele. Veja Projetos e Git.

6. Fazer a primeira solicitação

Comece com uma solicitação limitada: descreva o resultado, os arquivos ou restrições relevantes e como verificar a entrega. O prompt e o contexto selecionado são enviados diretamente ao provedor de IA escolhido para inferência, sob os termos desse provedor.

7. Revisar antes de entregar

Acompanhe chamadas de ferramentas, responda aos pedidos de aprovação e inspecione o diff resultante. Rode as verificações relevantes antes de fazer commit, merge ou deploy. Saídas de IA podem ser incompletas ou incorretas; você continua responsável pelas ações e mudanças entregues.

8. Montar o fluxo

• Chat, modelos e contexto cobre contas, modos, contexto, anexos, voz e memória.
• Conceitos define os blocos do Maestrly e os limites de rede.
• Maestro, agentes e skills transforma boas instruções em configurações reutilizáveis.
• Ferramentas e MCP controla o que os agentes podem alcançar.
• Plugins acrescenta skills, servidores MCP e agentes vindos do Git que funcionam com qualquer modelo.
• Projetos e Git cobre worktrees, checkout local e entrega.
• Bots (Experimental) roda agentes em um servidor hospedado por você.
• Workspaces remotos (Experimental) roda seus chats e workspaces nesse servidor.
• App para celular acompanha seus bots e os chats do servidor no iOS ou no Android.
• Artefatos publica páginas web dos agentes no seu servidor de bots.
• Uso e custos explica cobrança e limites dos provedores.

Precisa de ajuda? Acesse o Suporte.