Execute o DisPatch e as Minhas Ferramentas de IA no Docker: Um Arquivo, Um Comando

Eu executo meu próprio aplicativo de chat com IA, o DisPatch, para uso doméstico. Até este mês, para instalá-lo era necessário Python, um ambiente virtual e um arquivo de serviço. Agora ele é distribuído como uma imagem Docker; toda a configuração se resume a um único arquivo e um único comando, direto no seu próprio servidor. Esta página guia você desde uma pasta vazia até ter um chat funcionando, utilizando um pequeno modelo de IA que roda no seu processador – assim você pode testá-lo sem precisar se cadastrar em nada.

Todos os comandos desta página foram executados por mim em 19/10/2026. Nesta máquina não tenho o Docker Desktop, então usei o Podman 5.8 com o Docker Compose 5.6 no Linux. Os comandos são os mesmos; onde o Podman exigiu algo extra, indiquei isso na parte técnica no final.

O que você terá no final

Atlas é o personagem inicial do DisPatch. Ele responde perguntas e, com um modelo compatível, pode fazer pesquisas: busca na web, captura de páginas, previsão do tempo, Wikipedia, cotações cambiais, hora atual e calculadora. O mesmo chat também abre no celular:

Para saber o que o DisPatch faz além disso (perfis individuais para cada membro da família, modo infantil, backups), consulte o artigo sobre o DisPatch 3.0. Esta página trata apenas de como colocá-lo em funcionamento.

Passo 1: instalar o Docker

• Windows ou Mac: instale o Docker Desktop e inicie-o uma vez.
• Linux: instale o Docker Engine e o plugin compose, conforme sua distribuição ou as instruções da Docker.

Verifique se está tudo certo abrindo um terminal (PowerShell no Windows) e digitando docker compose version. Qualquer número de versão indica que você está pronto.

Passo 2: criar uma pasta e um arquivo

Crie uma pasta chamada dispatch e salve nela o seguinte conteúdo como docker-compose.yml:

services:
  dispatch:
    image: ghcr.io/laserlloyd/dispatch_chat:main
    ports:
      - "8765:8765"
    volumes:
      - dispatch-data:/data
    restart: unless-stopped
    init: true
    stop_grace_period: 30s

  # Opcional: pequeno modelo de IA que roda no seu processador, sem necessidade de conta.
  # Remova este bloco se for usar Ollama, LM Studio ou um serviço na nuvem.
  model:
    image: ghcr.io/ggml-org/llama.cpp:server-b11723
    command: ["-hf", "unsloth/Qwen3-4B-Instruct-2507-GGUF:Q4_K_M", "--jinja",
              "--host", "0.0.0.0", "--port", "8080", "--ctx-size", "8192"]
    environment:
      LLAMA_CACHE: /models
    volumes:
      - model-files:/models
    restart: unless-stopped

volumes:
  dispatch-data:
  model-files:

Dois serviços. dispatch é o aplicativo de chat. model é o servidor do llama.cpp, que baixa o modelo Qwen3 4B Instruct (2,5 GB) na primeira execução e o mantém. Suas conversas ficam num volume de armazenamento chamado dispatch-data, que sobrevive a atualizações e reinicializações.

"8765:8765" permite que outros dispositivos na sua rede acessem o DisPatch, o que é ideal para um chat familiar. Se por enquanto quiser usá-lo apenas no seu computador, substitua por "127.0.0.1:8765:8765".

Passo 3: iniciar tudo

Num terminal, dentro da pasta dispatch:

docker compose up -d
docker compose ps

A primeira execução baixa as duas imagens e o modelo; aguarde alguns minutos. Na minha máquina, o DisPatch respondeu 5 segundos após a chegada da imagem, e o servidor de modelos levou cerca de 20 segundos para baixar e carregar o modelo na minha conexão. O comando docker compose ps deve mostrar ambos os serviços como Up.

Passo 4: criar sua conta

Abra http://localhost:8765 num navegador. Um novo DisPatch fica bloqueado até ter um proprietário; como roda dentro de um container, pede um token de configuração único. Leia-o nos logs:

docker compose logs dispatch | grep "SETUP TOKEN"

Se grep não estiver disponível (Windows), execute docker compose logs dispatch e procure a linha que começa com SETUP TOKEN:. O token muda toda vez que o DisPatch é iniciado e deixa de funcionar após a criação do proprietário.

A senha precisa ter pelo menos 8 caracteres. O PIN é opcional, para desbloqueio rápido. Se você definir um, o DisPatch grava um código de recuperação nos seus dados; copie-o para algum lugar seguro:

docker compose exec dispatch cat /data/RECOVERY-CODE.txt

Passo 5: conectar a IA

A etapa 2 do assistente procura um servidor de modelos no mesmo computador. Dentro do Docker, ele não encontra sozinho o serviço model, então digite-o manualmente:

Campo	O que digitar
Tipo	OpenAI-compatible
Endereço	http://model:8080/v1
Chave API	deixe vazio
Modelo padrão	unsloth/Qwen3-4B-Instruct-2507-GGUF:Q4_K_M

Quer usar um modelo na nuvem? Selecione-o no mesmo campo e cole sua chave. Testei com um provedor na nuvem compatível com OpenAI: o botão 'Testar e salvar' listou os modelos disponíveis e o Atlas respondeu a partir deles. A chave deve ser inserida nos dados do DisPatch, não no arquivo compose.

Passo 6: finalizar e dizer olá

As etapas restantes são rápidas. O recurso de voz é um complemento separado que você pode pular. 'Família' permite adicionar mais pessoas (isso pode ser feito depois). 'Rede' pergunta quem pode acessar o DisPatch: escolha a mesma opção usada para a porta no passo 2.

Clique em Finalizar. Se a página ainda exibir o formulário de criação da conta após isso, recarregue-a. É um bug de exibição na versão atual (a conta já foi criada; o formulário antigo permanece na tela). Depois, escolha Atlas à esquerda, clique em + para iniciar um novo chat e faça uma pergunta.

Para usar no celular, na mesma rede Wi-Fi, abra http://<your computer's address>:8765. Instalar como atalho na tela inicial, notificações e microfone exigem HTTPS; a parte técnica explica isso.

É isso! A configuração completa. O restante desta página serve para quem quiser saber mais, manter os dados seguros ou adicionar minhas outras ferramentas.

Como as peças se encaixam

A imagem do DisPatch roda como um usuário comum (uid 1000), não como root. Tudo o que ela grava vai para /data, que corresponde ao volume dispatch-data: o banco de dados SQLite, uploads, avatares, configurações e os backups gerados a cada seis horas. Se você remover o contêiner, nada será perdido; porém, ao remover o volume, tudo será apagado.

A tag main da imagem segue o branch principal do repositório do DisPatch. As tags publicadas em 19/10/2026 são main e uma tag sha-<commit> para cada compilação; ainda não existem tags baseadas em números de versão. Se quiser manter a imagem inalterada até decidir atualizá-la, use uma tag sha- disponível na página do pacote. Existem imagens para processadores Intel/AMD de 64 bits e para arquitetura ARM; eu usei a versão para Intel/AMD.

Seus dados: faça backup, restaure e atualize com segurança

Primeiro pare o DisPatch para que seu banco de dados seja completamente gravado; depois copie o conteúdo do volume para um arquivo:

docker compose stop dispatch
docker run --rm -v dispatch_dispatch-data:/data:ro -v "$PWD":/backup alpine \
  tar czf /backup/dispatch-backup.tgz -C /data .
docker compose start dispatch

O Docker Compose nomeia o volume com base no nome da pasta; assim, uma pasta chamada dispatch gera um volume chamado dispatch_dispatch-data. O comando docker volume ls mostra o nome real do volume. Na minha instalação de teste, com alguns poucos chats, o arquivo gerado teve 3,7 MB.

Para restaurar os dados num volume novo (eu restaurei o meu e iniciei outro DisPatch: mesmo proprietário, as mesmas 8 mensagens):

docker volume create dispatch_dispatch-data
docker run --rm -v dispatch_dispatch-data:/data -v "$PWD":/backup:ro alpine \
  sh -c 'tar xzf /backup/dispatch-backup.tgz -C /data && chown -R 1000:1000 /data'
docker compose up -d

Não copie o arquivo chats.db isoladamente de um contêiner em execução: as mensagens mais recentes ficam no arquivo chats.db-wal, ao lado dele, até que o DisPatch seja encerrado.

A atualização exige dois comandos. Eu executei docker compose down, pull e up -d numa instalação já populada; o proprietário e todas as mensagens permaneceram intactos, sem que fosse exibido nenhum token de configuração novo.

docker compose pull
docker compose up -d

Faça um backup antes de atualizar para uma versão mais nova; o DisPatch migra seu banco de dados ao iniciar, e uma imagem antiga pode não conseguir ler esse banco já migrado.

Padrões de segurança e uma configuração a verificar

• Bloqueado até que um proprietário seja criado. Até que o primeiro passo do assistente de configuração seja concluído, a rede exibe apenas uma página de login; para criar o proprietário é necessário usar o token exibido nos logs.
• Visitantes não autenticados veem a visualização Restrita. Isso me surpreendeu nos testes: a partir de um navegador que nunca fez login, consegui abrir o Atlas e receber respostas. Esse é o comportamento padrão do DisPatch 3.0 (um visitante é tratado como um perfil Restrito infantil, com limite de 200 respostas por dia), mas essas respostas utilizam sua conexão com a IA. Se o DisPatch estiver na sua rede e usar uma chave de nuvem paga, altere em Configurações → Todas as configurações → Pessoas e perfis a opção “Um dispositivo que não fez login” para Apenas tela de login.
• Quem pode acessar o serviço depende da definição da porta. A configuração "8765:8765" permite acesso para toda a sua rede; já "127.0.0.1:8765:8765" restringe o acesso apenas ao seu computador. O contêiner, por si só, sempre escuta em todos os endereços da sua própria rede interna.
• O uso de HTTPS fica por sua conta. O docker-compose.yml do repositório prevê um proxy Caddy opcional (--profile proxy) para uso com um domínio real e certificados; nesta rodada eu não testei esse recurso. Caso use o nginx como proxy, mantenha a diretiva proxy_set_header Host $host;, caso contrário o chat carrega mas nunca atualiza (o DisPatch verifica se o origin do navegador corresponde ao cabeçalho Host).
• O servidor do modelo não possui chave de acesso. Sua porta não é exposta na configuração acima; portanto, apenas o DisPatch pode alcançá-lo. Não adicione uma linha ports: ao bloco model, a menos que também forneça ao llama.cpp um parâmetro --api-key.

O guia completo sobre o uso do Docker com o DisPatch, incluindo montagens de volumes, IDs de usuário e detalhes sobre a integração do agente que não funciona bem dentro de um contêiner, encontra-se em docs/deploy-docker.md no repositório.

Adicionando minhas outras ferramentas

Cada uma das minhas outras ferramentas possui um arquivo deploy/compose/compose.yml em seu próprio repositório. Como essas imagens ainda não estão disponíveis em nenhum registry, basta clonar o repositório e adicionar a opção --build. Em minha máquina, cada compilação levou menos de um minuto, pois as imagens base já estavam baixadas. No dia 19/10/2026 eu compilei e iniciei cada uma delas a partir de um clone novo do GitHub:

Ferramenta	O que é	Imagem	Porta	O que verifiquei
DisPatch	o aplicativo de chat	publicada, 599 MB	8765	tudo descrito acima
MailForge	assistente de e-mail que nunca envia mensagens por conta própria	compilada, 420 MB	8090	o painel abriu; nenhuma caixa de correio foi conectada
InfoForge + kiwix	busca offline na Wikipedia para respostas da IA	compilada, 128 MB, mais o kiwix de 66 MB	nenhuma (o kiwix usa a porta 8090)	os comandos doctor e search funcionaram num arquivo de 23 MB da Wikipedia
ThemeForge	página de visualização de temas	compilada, 13,8 MB	8185	a página abriu normalmente
StudioForge	servidor de modelo com GPU	compilado, 568 MB (Vulkan)	1234, 8080, 1235	serviu um modelo numa GPU integrada da AMD; detalhes abaixo
CrucibleForge	ferramenta de benchmark para modelos	compilado, 129 MB	8777	o serviço iniciou e a página abriu; nenhum teste foi executado
TransForge	tradutor de sites	compilado	nenhuma	não testado nesta rodada

Os tamanhos indicados são os reportados pelo Podman em disco. Os arquivos compose dessas ferramentas expõem suas portas apenas para 127.0.0.1, a menos que você altere essa configuração.

MailForge

O MailForge criptografa as senhas da sua caixa de correio usando uma frase-senha que você escolhe; ela não pode ser recuperada, portanto guarde-a em um gerenciador de senhas. Além disso, defina o parâmetro LLM_BASE_URL para apontar ao seu próprio servidor de modelos (192.0.2.10 abaixo representa o endereço desse servidor), pois o padrão é a porta 1234 no host Docker; quaisquer respostas vindas dali serão utilizadas pelo MailForge.

git clone https://github.com/LaserLloyd/MailForge.git
cd MailForge
read -rsp 'Frase-senha do keyring do MailForge: ' MAILFORGE_KEYRING_PASSWORD; export MAILFORGE_KEYRING_PASSWORD
LLM_BASE_URL=http://192.0.2.10:1234/v1 \
  docker compose -f deploy/compose/compose.yml up -d --build
docker compose -f deploy/compose/compose.yml logs app | grep "MailForge UI"

A linha de log exibe um endereço do tipo http://127.0.0.1:8090/?token=…; abra-o num navegador.

InfoForge e Wikipedia offline

Coloque um arquivo .zim da biblioteca Kiwix em deploy/compose/zims/ e indique seu nome no arquivo infoforge.config.yaml (copie-o de infoforge.config.example.yaml). Eu usei o arquivo “Chemistry by Wikipedia”, de 23 MB, para testar.

git clone https://github.com/LaserLloyd/InfoForge.git
cd InfoForge/deploy/compose
docker compose up -d kiwix
docker compose --profile cli build infoforge
docker compose --profile cli run --rm infoforge doctor
docker compose --profile cli run --rm infoforge search "gás nobre"

A busca funciona sem a necessidade de nenhum modelo de IA:

[1] Gás Nobre  (pontuação 19.0, 4222 caracteres)
[2] Gás  (pontuação 16.0, 1586 caracteres)
[3] Composto de gás nobre  (pontuação 10.5, 2045 caracteres)

O comando infoforge ask requer um servidor de modelos em base_url; com o endereço placeholder, o comando doctor passa em todas as verificações, exceto na “llm primary”, o que está correto.

ThemeForge

git clone https://github.com/LaserLloyd/ThemeForge.git
cd ThemeForge
docker compose -f deploy/compose/compose.yml up -d --build

Em seguida, abra http://localhost:8185.

## O servidor de modelos de GPU: StudioForge

StudioForge é o meu próprio servidor de modelos. Ele executa modelos em uma placa de vídeo, lida com vários modelos e múltiplos clientes; desde a versão 2.0, exige uma conta de proprietário e uma chave de API para cada cliente. A imagem do StudioForge ainda não está disponível em nenhum registro, então esta etapa serve para criá-la.

Eu esperava escrever “apenas NVIDIA” aqui. O mini PC que testei não possui placa de vídeo da NVIDIA; tem apenas a GPU Radeon integrada da AMD, no processador Ryzen AI 9 365. Mesmo assim, compilei a imagem Vulkan, passei a GPU como parâmetro e tudo funcionou: o StudioForge baixou automaticamente o motor llama.cpp pré-compilado do GitHub na primeira execução, testou-o e executou o modelo Qwen3 4B com todas as camadas rodando na GPU, atingindo uma velocidade de 23 a 28 tokens por segundo. Para comparação, o serviço de model que usa apenas CPU mencionado acima alcançou 22 tokens por segundo com o mesmo modelo; portanto, nesse chip, a GPU libera mais o processador do que realmente acelera as respostas.

git clone https://github.com/LaserLloyd/StudioForge.git
cd StudioForge/deploy/compose
cp env.example .env
# No arquivo .env: SF_BACKEND=vulkan, SF_MODELS=/caminho/para/seus/arquivos/gguf,
#          SF_OWNER_PASSWORD (uma senha com 10 ou mais caracteres),
#          SF_VIDEO_GID e SF_RENDER_GID = os números obtidos via: getent group video render
docker compose -f compose.yml -f compose.vulkan.yml build
docker compose -f compose.yml -f compose.vulkan.yml up -d
docker compose -f compose.yml -f compose.vulkan.yml exec studioforge \
  studioforge keys create --name dispatch --scope inference

O último comando imprime uma chave uma única vez. O painel de controle está em http://localhost:8080 (usuário owner, sua senha). Para uma placa NVIDIA, o arquivo é compose.cuda.yml e SF_BACKEND=cuda; não testei esse caminho aqui, e a imagem CUDA é bem maior.

DisPatch e StudioForge juntos

O repositório do DisPatch contém o arquivo deploy/compose/stack.yml, que inicia ambos os serviços numa mesma rede e configura automaticamente a conexão do DisPatch com o StudioForge. Por padrão, ele tenta baixar uma imagem do StudioForge que ainda não é pública; portanto, você deve apontar para a imagem que acabou de compilar. Estas são as configurações que adicionei ao arquivo stack.env:

git clone https://github.com/LaserLloyd/DisPatch_Chat.git
cd DisPatch_Chat
cp deploy/compose/stack.env.example deploy/compose/stack.env
# adicione ao deploy/compose/stack.env:
#   DISPATCH_IMAGE=ghcr.io/laserlloyd/dispatch_chat:main
#   STUDIOFORGE_IMAGE=ghcr.io/laserlloyd/studioforge:2.0.1-vulkan
#   STUDIOFORGE_MODELS=/caminho/para/seus/arquivos_gguf
#   STACK_MODEL=<o ID do modelo exibido no StudioForge>
#   SF_OWNER_PASSWORD (a mesma senha de proprietário com 10+ caracteres)

O arquivo de configuração reserva uma GPU NVIDIA. Para sistemas AMD ou Intel usando Vulkan, substituí essa configuração por um segundo arquivo, stack-amd.yml:

services:
  studioforge:
    deploy: !reset {}
    devices: ["/dev/dri:/dev/dri"]
    group_add: ["39", "105"]   # números dos grupos de vídeo e renderização do seu sistema

docker compose -f deploy/compose/stack.yml -f stack-amd.yml \
  --env-file deploy/compose/stack.env up -d
docker compose -f deploy/compose/stack.yml -f stack-amd.yml \
  --env-file deploy/compose/stack.env exec studioforge \
  studioforge keys create --name dispatch --scope inference

Em seguida, conclua o assistente do DisPatch conforme descrito anteriormente; abra “Configurações” → “Conexões”, clique em “Editar” na conexão com o StudioForge, cole a chave gerada e clique em “Testar”.

O ID do modelo pode ser obtido via curl -H "Authorization: Bearer <key>" http://localhost:1234/v1/models ou na aba “Modelos” do painel de controle. Se seus modelos estiverem numa pasta baixada do Hugging Face, o ID será o caminho completo da pasta; embora longo, esse método funciona perfeitamente.

## Pontos de atenção

• Recarregar a página após concluir o assistente. Na versão que testei, o formulário “criar conta de proprietário” permanece na tela após o fechamento do assistente. A conta já existe; basta recarregar a página.
• O assistente não encontra o modelo sozinho. Dentro do Docker, sua busca ocorre apenas no próprio container, não em outros serviços. Digite http://model:8080/v1.
• Modelos pequenos e problemas de chamada de ferramentas. Com o modelo Qwen2.5 1.5B, o Atlas às vezes exibia uma mensagem fictícia do tipo “Pesquisando na web: …” em vez de invocar a ferramenta adequada. Já o modelo 4B listado acima sempre realizou corretamente a busca meteorológica. Modelos maiores tendem a funcionar melhor nesse cenário.
• O código de recuperação só existe se você definir um PIN. Com apenas uma senha, não há arquivo RECOVERY-CODE.txt, embora a lista de verificação do assistente mencione sua existência.
• Duas ferramentas querem usar a porta 8090. O MailForge e o kiwix do InfoForge usam essa porta por padrão neste computador. Ao rodar ambos, defina HOST_PORT para o MailForge ou KIWIX_PORT para o kiwix.
• O primeiro início do StudioForge exige GitHub. Ele baixa o motor llama.cpp por meio da API do GitHub, que permite 60 requisições anônimas por hora por endereço IP. Na minha primeira tentativa, esse limite foi atingido; a imagem Vulkan então tentou compilar o motor a partir do código-fonte – algo impossível, pois não há git nela –, resultando na mensagem can_serve: false. Um reinício após o reset do limite resolveu o problema. Configurar GITHUB_TOKEN no arquivo .env aumenta esse limite, conforme indicado nos logs do StudioForge.
• O comando docker compose down -v apaga suas conversas. O comando simples down não faz isso.
• Usuários do Podman: em Fedora e outros sistemas com SELinux, adicione :z ao montar a pasta de backup ("$PWD":/backup:z). O Podman com Docker Compose também rejeitou os arquivos de composição das ferramentas que não possuíam a linha test: no bloco de healthcheck (“é obrigatório definir um comando de verificação”); adicionei o comando apropriado extraído dos Dockerfiles num pequeno arquivo de sobrescrita. Para o kiwix rodar sem privilégios de root, use KIWIX_USER=0. Usuários do Docker podem ignorar este item.

## O que não testei

• Docker Desktop no Windows ou Mac. Usei apenas o Podman com Docker Compose em Linux, exclusivamente para arquitetura x86-64.
• Ollama ou LM Studio executados fora do Docker no mesmo computador. No Docker Desktop, o endereço seria http://host.docker.internal:11434/v1 para o Ollama; esse servidor precisaria aceitar conexões vindas do container, algo que não pude confirmar.
• Imagens NVIDIA e ROCm do StudioForge, a compilação com o complemento de voz (VOICE=1), o perfil HTTPS do Caddy e o TransForge.
• O uso da ferramenta ask do InfoForge com um modelo, bem como a execução de testes de desempenho no CrucibleForge.

DisPatch no GitHub StudioForge MailForge InfoForge

Relacionado: DisPatch 3.0: perfis familiares e o assistente de configuração, DisPatch, StudioForge e como fazer com que uma IA adapte qualquer projeto ao seu sistema.