Começar

    Arranque rápido

    Instala o Ollama, descarrega o modelo e abre o Ploy. Passos curtos, cada um com uma forma de confirmar que funcionou.

    1. Instala o Ollama

    O Ollama é o programa que corre o modelo.

    bash
    brew install ollama

    Confirma que o comando existe:

    bash
    ollama --version

    Não precisas de o arrancar à mão. Quando abres o Ploy, o lançador vê se o Ollama responde em http://127.0.0.1:11434 e, se não responder, inicia-o com as definições certas.

    2. Descarrega o modelo

    bash
    ollama pull qwen3:8b

    São cerca de 5 GB, por isso a primeira vez demora conforme a tua ligação. Confirma:

    bash
    ollama list

    A lista deve incluir qwen3:8b.

    3. Instala o ffmpeg

    O ffmpeg (que traz o ffprobe) é usado pela ferramenta de áudio e vídeo e pela voz. Sem ele, o resto do Ploy funciona, mas essas duas partes não.

    bash
    brew install ffmpeg
ffprobe -version

    A voz precisa ainda do whisper.cpp e de um modelo de voz. Estão descritos em Voz e em Requisitos.

    4. Abre o Ploy

    Com a pasta do código, e o comando ploy a apontar para o ficheiro bin/ploy dela, tens duas formas de entrar:

    bash
    # window app, in development mode, started from the code folder
ploy app

# terminal interface
ploy

    Se não existir o binário compilado, o lançador corre o código-fonte com o Bun, e por isso o Bun tem de estar instalado.

    Antes de abrir, o lançador faz três coisas:

    1. inicia o Ollama, se ainda não estiver a correr;
    2. cria o modelo qwen3-ploy a partir do qwen3:8b, se ele ainda não existir ou estiver desatualizado (vês a mensagem «a criar o modelo qwen3-ploy...»);
    3. carrega o modelo para a memória, para a primeira resposta não ficar à espera. Se isto demorar mais de 180 segundos, avisa que o modelo não carregou a tempo.

    A primeira abertura é por isso mais lenta do que as seguintes. Se a janela abrir vazia pela primeira vez, cria o projeto predefinido em ~/Projetos Ploy/Projeto Padrão e abre aí uma conversa nova. Ver Pastas e dados.

    5. Confirma que funciona

    No terminal:

    bash
    ploy --version
ploy run "Explica numa frase o que é o Ollama."

    O primeiro comando mostra uma compilação de desenvolvimento (ploy v0.0.0-ploy- seguido de uma data e hora), não uma versão numerada. O segundo envia uma pergunta ao modelo Automático e imprime a resposta. Quando corres o ploy run num script, redireciona o stdin com < /dev/null, porque o comando espera pelo fim da entrada quando ela não é um terminal.

    Na janela, escreve «Olá». O botão do modelo passa a mostrar «Automático · Saturn», o que quer dizer que o Automático escolheu o Saturn. Depois pede uma tarefa com ferramentas, por exemplo:

    Cria um ficheiro ola.txt com a palavra olá e mostra o conteúdo.

    O Ploy pode pedir-te licença para criar o ficheiro: aprova. Deve depois lê-lo e dizer-te o que verificou. Um modelo de 8 mil milhões de parâmetros falha de vez em quando, e o Ploy foi feito para dizer o que verificou e o que não verificou.

    Se alguma coisa falhar

    O lançador escreve mensagens curtas no terminal. As mais comuns:

    Mensagem O que fazer
    o Ollama não está instalado (brew install ollama). Faz o passo 1.
    falta o modelo base. Corre: ollama pull qwen3:8b Faz o passo 2.
    o Ollama não arrancou (ver ~/Library/Logs/ploy-ollama.log). Abre esse registo para ver porquê.
    aviso: o modelo não carregou a tempo. O modelo pode ter demorado a carregar: tenta de novo. Com pouca memória livre, convém fechar outras aplicações.

    Para mais casos, ver Resolução de problemas. Para saber o que cada modelo faz, ver Os modelos do Ploy.