Referência

    Ambiente e variáveis

    As variáveis PLOY_*, as definições OPENCODE_* que o lançador aplica e o comportamento do Ollama que ele configura.

    Tudo o que está nesta página vem do lançador (bin/ploy) e do código. O lançador é o comando ploy: prepara o Ollama e o modelo, aplica as definições "local primeiro" e só depois corre o Ploy.

    Variáveis do Ploy

    Variável Efeito
    PLOY_WEB 0 desliga a pesquisa na web do Veta, que passa a responder só com o que sabe. Qualquer outro valor deixa-a ligada.
    PLOY_OLLAMA Onde o gateway dos modelos Ploy fala com o Ollama. Por omissão http://127.0.0.1:11434. O lançador continua a verificar e a iniciar o Ollama local.
    PLOY_SHOW_RAW_MODELS 1 mostra no seletor os modelos Ollama em bruto. Por omissão estão escondidos, mas usam-se pelo nome (ollama/qwen3-ploy).
    PLOY_CONFIG_DIR Pasta de configuração. Por omissão ~/.config/ploy.
    PLOY_DATA_HOME Pasta de dados (conversas, registos). Por omissão ~/.local/share/ploy.
    PLOY_CHATS_DIR Onde a memória de cada conversa é espelhada em ficheiros. Por omissão, a pasta chats dentro da pasta de dados.
    PLOY_TRACE 1 escreve no registo do serviço uma linha por pedido ao modelo, para ver onde se vai o tempo.
    PLOY_WHISPER_MODEL Caminho do modelo do whisper.cpp. Por omissão ggml-small.bin na pasta models dentro da pasta de dados.

    Para compilar o terminal existe ainda PLOY_BUN_RANGE, que deixa compilar com uma versão mais antiga do Bun, já verificada. As suítes de testes usam PLOY_VIA, PLOY_SUITE, PLOY_REPEAT e PLOY_TIMEOUT.

    Definições OPENCODE_* que o lançador aplica

    O Ploy é um fork do OpenCode, e estas definições herdadas são o que o torna local.

    Definição O que faz Porquê
    OPENCODE_DISABLE_AUTOUPDATE=1 Sem verificação de atualizações. Local primeiro: nada sai do Mac sem a pessoa querer.
    OPENCODE_DISABLE_MODELS_FETCH=1 Não descarrega a lista de modelos da internet. Idem.
    OPENCODE_DISABLE_FREE_MODELS=1 Retira os modelos gratuitos alojados do OpenCode. Idem.
    OPENCODE_DISABLE_FILEWATCHER=1 Sem vigilância de ficheiros. Ainda não está documentado.
    OPENCODE_DISABLE_CLAUDE_CODE=1 Não lê a pasta .claude (usada só para skills). Ainda não está documentado.
    OPENCODE_CONFIG_DIR Pasta de configuração do Ploy, vinda de PLOY_CONFIG_DIR. Uma pasta própria.
    XDG_DATA_HOME Pasta de dados do Ploy, vinda de PLOY_DATA_HOME. O Ploy não herda conversas dos testes nem de outra instalação do OpenCode.
    OPENCODE_DESKTOP_ISOLATED_SERVER=0 Só em ploy app: a app em modo de desenvolvimento não usa um serviço isolado. Ainda não está documentado.

    A configuração (config/opencode.json) é copiada uma vez para a pasta de configuração. Define o modelo predefinido (ollama/ploy-auto), o contexto de 16 384 tokens e o limite de saída de 6144, e as variantes rapido e profundo. Se a cópia ainda for exatamente uma versão antiga distribuída, é substituída pela atual. Se a editaste, fica como está.

    O que o lançador faz ao Ollama

    Os comandos que nunca falam com o modelo (--version, --help, help, --completions, upgrade, update, uninstall) saltam tudo isto. Para os outros:

    1. Ollama. Se não responde em 127.0.0.1:11434, o lançador inicia-o e espera até 30 segundos. O registo fica em ~/Library/Logs/ploy-ollama.log.
    2. Modelo. Se falta o qwen3-ploy, ou se o seu template ainda não deixa o pedido ligar e desligar o raciocínio, o lançador cria-o a partir do qwen3:8b com o Modelfile do projeto.
    3. Pré-carregamento. Um pedido vazio carrega o modelo para a primeira resposta ser rápida.

    As definições do servidor Ollama só se aplicam quando é o lançador a iniciá-lo. Se o Ollama já estava a correr, ficam as definições dele.

    Definição Valor Notas
    OLLAMA_NUM_PARALLEL 1 O Ploy precisa disto. Os agentes também correm um a seguir ao outro.
    OLLAMA_MAX_LOADED_MODELS 1 Um só modelo em memória. Os 16 GB são partilhados com as tuas apps.
    OLLAMA_KEEP_ALIVE 15m O modelo fica em memória 15 minutos. O pré-carregamento pede o mesmo.
    OLLAMA_FLASH_ATTENTION 1 Opção do Ollama para a atenção do modelo. O motivo exato não está documentado.
    OLLAMA_KV_CACHE_TYPE q8_0 Tipo do cache do contexto. O motivo exato também não está documentado.

    O Modelfile

    O qwen3-ploy parte do qwen3:8b, com um template próprio e estes parâmetros:

    FROM qwen3:8b
# TEMPLATE omitted here: it appends /think or /no_think to the last user message
PARAMETER num_ctx 16384
PARAMETER temperature 0.5
PARAMETER top_p 0.9
PARAMETER top_k 20

    O projeto fixa o num_ctx em 16384, que é a janela de contexto do Ploy. O template acrescenta /think ou /no_think à última mensagem do utilizador, conforme o pedido ligue ou não o raciocínio. Existe também um Modelfile do qwen3-ploy-4b (4 mil milhões de parâmetros), que o lançador não cria.

    Comandos

    bash
    ploy                         # terminal UI
ploy run --auto "<task>"     # one task, approves each permission request once
ploy app                     # window app, development mode
ploy run "<task>" < /dev/null   # in scripts: close stdin, or it waits for it

    Quando o stdin não é um terminal, o ploy run lê-o até fechar, por isso os scripts usam < /dev/null. A pasta de trabalho vem de PWD. Se o binário compilado não existir, o lançador corre a partir do código-fonte e avisa. Ver também Pastas e dados e Resolução de problemas.