Kokon

A tela de configuração escolhe uma predefinição com base na sua VRAM. Em um Mac, as predefinições são nomeadas pela memória unificada (Mac de 16–24 GB, Mac de 32–36 GB, Mac de 48 GB, Mac de 64 GB+), porque a parte gráfica pode usar apenas cerca de dois terços dela e o codificador de texto compartilha a mesma memória. Você pode alterar a predefinição depois em Configurações → Modelos → Configurar modelos…

Cada predefinição também inclui stable-diffusion.cpp (a compilação CUDA 12 em NVIDIA, a compilação Vulkan em AMD e Intel, a compilação Metal em um Mac), o VAE do Qwen-Image 2.1 e o projetor de visão Qwen3-VL e, em um PC, o upscaler Superscale-SP (67 MB). O modelo de imagem é o Qwen-Image 2.1 Turbo oficial de 8 etapas da Qwen, por meio de DogukanUrker/Qwen-Image-2.1-Turbo-GGUF; as outras fontes são Qwen/Qwen3-VL-8B-Instruct-GGUF e Comfy-Org/Qwen-Image-2.1.

Os arquivos vão para %LOCALAPPDATA%\KokonData\sdcpp (Mac: ~/Library/Application Support/KokonData/sdcpp) por padrão. Você pode apontar a tela de configuração para uma pasta existente de stable-diffusion.cpp; os arquivos que já estão lá são mantidos. Outros pesos, como fine-tunes, podem ser selecionados em Configurações → Modelos.

.mcp.json com escopo de projeto, ou qualquer host que aceite o formato padrão (em um Mac, o comando é /Applications/Kokon.app/Contents/MacOS/kokon-mcp):

{
  "mcpServers": {
    "kokon": {
      "type": "stdio",
      "command": "C:\\Users\\<you>\\AppData\\Local\\Kokon\\kokon-mcp.exe",
      "args": []
    }
  }
}

A mesma coisa pela linha de comando:

claude mcp add-json --scope user kokon '{"type":"stdio","command":"C:\\Users\\<you>\\AppData\\Local\\Kokon\\kokon-mcp.exe","args":[]}'

• Cada resultado retorna o caminho absoluto do arquivo salvo, seu tamanho, semente e metadados de geração.
• Os caminhos podem ser absolutos ou relativos ao projeto (CLAUDE_PROJECT_DIR). Leituras e gravações são limitadas à pasta do projeto, à pasta de saída do Kokon e às pastas listadas em QLS_MCP_ALLOWED_DIRS (separadas por ponto e vírgula). Arquivos existentes nunca são sobrescritos.
• As imagens não são enviadas de volta ao modelo por padrão; elas permanecem no disco. Passe include_preview: true para incluir uma prévia JPEG pequena.
• upscale_image usa scale (padrão 2) ou width/height (até 8192 px).
• O progresso é relatado por meio de notificações de progresso do MCP. O tempo limite padrão da ferramenta do Claude Code é 30 minutos (MCP_TOOL_TIMEOUT).
• Sem a janela da área de trabalho aberta, o modelo é descarregado após 15 minutos ociosos (Configurações → Geral).

URL base http://127.0.0.1:39151/api/v1. Toda chamada, exceto /ping, precisa de Authorization: Bearer <token>, com o token de %LOCALAPPDATA%\KokonData\service.json (Mac: ~/Library/Application Support/KokonData/service.json). Requisições que carregam um cabeçalho de navegador Origin são recusadas.

$i = Get-Content "$env:LOCALAPPDATA\KokonData\service.json" | ConvertFrom-Json
$h = @{ Authorization = "Bearer $($i.token)" }
Invoke-RestMethod -Method Post "http://127.0.0.1:$($i.port)/api/v1/generate" -Headers $h `
  -ContentType 'application/json' -Body '{"prompt":"a lighthouse at dusk, 16:9","quality":"fast"}'

Campos de operações simples: prompt, image / images[], mask, action (edit|remove|replace|add, inpainting), width, height, aspect_ratio, quality (fast|balanced|quality), seed, output_path, preserve_dimensions, private, left/right/top/bottom + units (pixels|percent) para outpainting, scale para upscaling. Requisições completas (/jobs) também aceitam "mode": "upscale" com "upscale": {"scale" | "width"/"height"}.

O SmartScreen mostra isso para aplicativos novos que ainda não têm histórico de download. Clique em Mais informações → Executar mesmo assim. Você pode verificar o instalador em relação ao hash SHA-256 listado nas notas da versão, ou compilá-lo você mesmo.

O Kokon não é notarizado pela Apple (isso exige uma conta de desenvolvedor Apple paga), então o macOS o bloqueia na primeira vez. Você só faz isso uma vez; atualizações no aplicativo não disparam isso novamente.

1. Abra o Kokon. O macOS diz “Kokon” Não Aberto: clique em Concluído (não Mover para a Lixeira).

   

2. Abra Ajustes do Sistema → Privacidade e Segurança e role para baixo até Segurança. Ao lado de “Kokon” foi bloqueado para proteger seu Mac, clique em Abrir Mesmo Assim e confirme com sua senha ou Touch ID.

   

3. Abra o Kokon novamente e clique em Abrir no último prompt.

Você também pode compilá-lo você mesmo.

Somente para baixar os modelos. Depois disso, o Kokon funciona totalmente offline. Se você estiver online, ele verifica uma vez por dia se há uma nova versão, o que você pode desativar na tela de boas-vindas ou em Configurações → Geral.

AMD e Intel: em beta. A tela de configuração instala a versão Vulkan do stable-diffusion.cpp para eles, que usa o driver gráfico que você já tem. Funciona em placas NVIDIA, mas não foi verificado em uma placa AMD ou Intel real ainda; gráficos integrados não são suportados. Por favor, abra uma issue com sua placa e como foi.

Mac: sim, em beta, em Apple Silicon (M1 ou mais novo) com macOS 26. Ele roda em um Mac de 16 GB em um modo mais leve, mas lentamente (cerca de 4 minutos por imagem de 1 megapixel em um M2 Pro); 32 GB ou mais e um chip Pro, Max ou Ultra são recomendados. Veja os requisitos e docs/platforms.md.

Não com bons resultados hoje. O Qwen-Image 2.1 é um modelo grande, e 12 GB é o menor tamanho para o qual o Kokon foi projetado. Placas menores podem vir com modelos mais leves no futuro.

Não com o modelo padrão. O código do Kokon é open source (veja Licença), mas o modelo de imagem tem sua própria licença: Qwen-Image 2.1 e seu modelo Turbo são lançados sob a Qwen Research License, que permite somente pesquisa e avaliação, sem uso comercial. Isso inclui vender ou usar comercialmente as imagens que você cria com ele. Para uso comercial, peça uma licença à equipe Qwen (model-business@notice.qwencloud.com).

O codificador de texto Qwen3-VL é Apache-2.0. O upscaler padrão, Superscale-SP da Nmkd, é WTFPL, e o MoSR experimental de Philip Hofmann é CC BY 4.0: ambos permitem uso comercial. O upscaler opcional UltraSharp é CC BY-NC-SA 4.0, somente não comercial.

Fotos HEIC/HEIF abrem como qualquer outra imagem. Em um Mac, elas são decodificadas pelo próprio macOS. No Windows, as Extensões de Imagem HEIF e as Extensões de Vídeo HEVC da Microsoft devem estar instaladas.

Fotos do iPhone com mapa de ganho HDR (iOS 18+) mostram um interruptor Manter HDR em Avançado, que está ativado por padrão. Edições dessas fotos são salvas como JPEG Ultra HDR: Chrome, Edge, Android e sistemas Apple recentes as mostram em HDR, e todos os outros visualizadores mostram um JPEG normal. Isso precisa de ffmpeg 7.1+ no PATH; sem isso, o resultado é salvo em SDR e as notas do trabalho explicam o motivo.

Por padrão, Superscale-SP da Nmkd (ESRGAN), baixado pela tela de configuração; em um Mac, Lanczos, porque upscalers de IA levam minutos lá (Superscale-SP: 5 min 45 s para ampliar uma imagem 1024×1024 para 2048×2048 em um M2 Pro, contra cerca de um segundo). Escolha outro no menu Avançado ao lado do prompt, ou em Configurações → Modelos; Comparar upscalers lá mostra cada um nos mesmos recortes (um rosto, uma foto JPEG, uma rua à noite, texto, uma paisagem, um upscale 4×):

• Superscale-SP (padrão): nítido e natural na maioria das imagens; em fotos JPEG e áreas escuras, pode desenhar uma grade tênue.
• MoSR (experimental, 17 MB, vem com o aplicativo): o mais rápido, bom para upscales 4×, mas em imagens limpas ampliadas menos de cerca de 3×, desenha uma grade fina. Ele precisa da versão do Kokon do stable-diffusion.cpp (pull request para o projeto original).
• UltraSharp (download opcional): muito limpo, mas suaviza a pele em um visual artificial e pode inventar linhas. Licença não comercial.
• Lanczos: um redimensionamento simples, nunca inventa nada.

Força do upscaler (0–100 %) mistura o resultado do upscaler com um redimensionamento simples, para suavizar texturas que ele inventa. Configurações → Modelos também tem Reduzir a imagem antes do upscaling, que dá ao upscaler uma imagem menor, como as que ele foi treinado.

Windows: Configurações → Aplicativos → Aplicativos instalados → Kokon → Desinstalar. O desinstalador pergunta se você deseja excluir também os modelos baixados e os dados do aplicativo (%LOCALAPPDATA%\KokonData).

Mac: arraste o Kokon da pasta Aplicativos para a Lixeira. Para liberar também o espaço dos modelos, exclua ~/Library/Application Support/KokonData.

Suas imagens permanecem na sua pasta Imagens.

Se um download falhar, a tela de configuração mostra a página de download do arquivo e a pasta de destino para que você possa baixá-lo manualmente. Para qualquer outra coisa, por favor abra um problema com sua GPU (ou modelo do Mac), versão do driver ou do macOS e o log de KokonData/logs (veja a tabela acima).

Windows: Rust (estável, MSVC), Node 22+, Visual Studio Build Tools e WebView2.

npm install
cargo test -p qls-core            # core unit tests
npx vitest run                    # UI logic tests
cd mcp; npx vitest run; cd ..     # MCP tests (includes a stdio protocol test)
npx tauri dev                     # run the desktop app in development
powershell -ExecutionPolicy Bypass -File scripts\build-release.ps1   # installer

Mac (Apple Silicon, macOS 26+): Xcode Command Line Tools, Rust e Node 22+.

bash scripts/dev/mac-dev.sh --check   # check the prerequisites
bash scripts/dev/mac-dev.sh           # build and run the app in development
bash scripts/build-release-mac.sh     # Kokon.app + .dmg in dist-release/

A publicação de uma versão (atualizações assinadas no aplicativo para ambas as plataformas) está descrita em docs/releasing.md.

flowchart TB
    UI["<b>Kokon</b><br>Tauri 2 + React"]
    MCP["<b>kokon-mcp</b><br>MCP over stdio"]
    S["Scripts and other apps"]
    SVC["<b>kokon-service</b><br>planner · preprocessing · job queue · gallery<br><code>127.0.0.1:39151/api/v1</code>"]
    SD["<b>sd-server</b><br>stable-diffusion.cpp (CUDA · Vulkan · Metal)<br><code>127.0.0.1:39150</code>"]
    UI -- "HTTP + SSE, token" --> SVC
    MCP -- "HTTP, token" --> SVC
    S -- "HTTP, token" --> SVC
    SVC -- "native async API" --> SD

O núcleo em Rust (crates/qls-core) contém toda a lógica: geometria, processamento de imagens, planejamento, o adaptador de inferência, a fila de trabalhos e a galeria. O serviço, o aplicativo de desktop e o servidor MCP são camadas finas por cima. Veja as notas de engenharia para um mapa de módulos e os fatos de backend em que cada padrão se baseia.