zervis

Zérvis

O assistente de voz e a oficina de IA de quem toca automações, para os próprios projetos e os dos clientes.

Você dá o norte, por voz ou pelo painel. O Zé conduz os agentes Claude e Codex, liga os sistemas dos clientes por MCP
e fica de olho no que está rodando, no seu Linux ou na sua VPS.

Instalar no PC · Instalar numa VPS · Arquitetura · Hermes e OpenClaw · Roteiro · Contribuir

<a href="https://github.com/gestordescomplicaa-web/zervis/actions/workflows/check.yml"><img alt="Verificação" src="https://img.shields.io/github/actions/workflow/status/gestordescomplicaa-web/zervis/check.yml?branch=master&label=verifica%C3%A7%C3%A3o&style=flat-square"></a>
<img alt="Linux" src="https://img.shields.io/badge/plataforma-Linux-45c6d8?style=flat-square">
<img alt="Python 3.12 a 3.14" src="https://img.shields.io/badge/python-3.12%E2%80%933.14-45c6d8?style=flat-square">

Em desenvolvimento ativo. Há instaladores para o PC e para a VPS; o da VPS foi provado do zero (guia), o do PC num Omarchy (prova e limites). O que está pronto e o que está em teste vem marcado em cada função.

Para quem é

Para gestores e consultores de automação e IA: quem monta integrações, fluxos e agentes para empresas e quer um assistente que faça o trabalho pesado sem misturar um cliente com outro. Serve também a quem só quer um assistente de voz de trabalho no próprio Linux.

O que o Zé faz

Benefícios

• O modelo pensa uma vez; o resto roda sem tokens. Os agentes constroem e corrigem; o que se repete roda no lugar certo (um fluxo no n8n, uma automação, o vigia), sem chamar o modelo a cada execução.
• Clientes separados de verdade. Conectores ligados ao projeto pelo caminho da pasta, sessões independentes e nomes por cliente: o n8n do cliente A nunca entra na sessão do cliente B.
• Segredo nunca passa pela conversa. Tokens e chaves ficam em arquivos 0600 fora do repositório; a LLM recebe só o nome da variável.
• Tudo registrado. A Atividade guarda o que o Zé executou, inclusive o que foi negado e as chamadas aos sistemas de fora.
• Suas contas, seus dados. Claude pela assinatura (Agent SDK), Codex pela conta, ou chaves da Anthropic, OpenAI, OpenRouter e proxies no formato OpenAI. Os dados ficam nas suas pastas.
• Falha fechada. Na dúvida, não envia, não aprova, não apaga, e diz por quê.

Como se compara

Hermes Agent (Nous Research, MIT) e OpenClaw (MIT) são assistentes generalistas excelentes, com foco nos mensageiros. O Zérvis escolheu outro foco: voz, oficina de código e integração de sistemas de clientes, no Linux e na VPS. Comparação pela documentação oficial de cada um, em outubro de 2026; detalhes na matriz comparativa.

Legenda: ● tem · ◐ parcial · — não tem.

Quando escolher cada um. OpenClaw, se o principal é falar com o assistente por muitos mensageiros e apps de celular. Hermes, se você quer um generalista com centenas de modelos e integração com IDE. Zérvis, se o seu trabalho é conduzir agentes de código e ligar sistemas de clientes, falando com ele, com cada cliente no seu lugar.

Arquitetura

flowchart LR
    voce(["Você<br>voz · painel · celular"])

    subgraph ze["Zérvis (um serviço do usuário, systemd)"]
        nucleo["Núcleo<br>estados e serviços"]
        voz["Voz<br>ativação · escuta · Piper"]
        cerebro["Cérebro<br>Claude ou Codex"]
        mcpze["Ferramentas do Zé (MCP)<br>memória · skills · sessões ·<br>automações · sistema · conectores"]
        oficina["Oficina<br>sessões de código por projeto"]
        avisos["Central de avisos<br>e Atividade"]
        vigia["Vigia do n8n"]
        dados[("SQLite e Markdown<br>pastas XDG")]
    end

    central["Central de Atendimento<br>processo próprio · WhatsApp"]
    agentes["Claude Code e Codex<br>com os conectores do projeto"]
    externos["Sistemas dos clientes<br>n8n · CRM · ERP (MCP)"]

    voce <--> voz <--> nucleo
    nucleo <--> cerebro <--> mcpze
    cerebro -- conectores gerais --> externos
    mcpze --> oficina --> agentes -- conectores do projeto --> externos
    vigia -- healthz --> externos
    vigia --> avisos
    oficina --> avisos
    avisos --> voce
    nucleo <-->|eventos| central
    nucleo --- dados

• Uma linguagem por papel. Python no núcleo, no cérebro e na voz; Go no WhatsApp (WaCalls); JavaScript com tipos no painel, sem etapa de build. Só se reescreve noutra linguagem o que uma medição apontar como gargalo (ADR 0032).
• Fronteiras por processo. O que precisa ficar de pé sozinho roda à parte, com API local e token: a Central de Atendimento, o WaCalls, a memória longa. Reiniciar o Zé não derruba o atendimento.
• Cérebro trocável. Claude ou Codex atrás de uma interface única; a via rápida responde o que é curto e passa o resto ao cérebro (ADR 0015).
• Os agentes fazem; o Zé conduz. As sessões são o Claude Code e o Codex de verdade, com as skills e os conectores do projeto (ADR 0037).
• O n8n executa; o Zé constrói e vigia. Os fluxos dos clientes rodam no n8n, conhecido e auditável; o Zé não vira um motor de fluxos (ADR 0038).
• Dados em SQLite, um banco por área, com migrações automáticas e busca de texto; segredos fora do banco, em arquivos 0600.
• Uma essência que não muda. O que o Zé é e não deixa de ser está em docs/essencia.md: nenhuma mudança, nem a feita por ele mesmo, pode contrariá-la.

Instalar no PC

No terminal da sessão gráfica, como usuário comum, com Git, Make e curl instalados:

git clone https://github.com/gestordescomplicaa-web/zervis.git
cd zervis && deploy/instalar-pc.sh

O instalador prepara Python e dependências, os modelos de voz, os agentes de código e o Go verificado para o WhatsApp. Instala o serviço do usuário, o atalho Zérvis no menu e o comando zervis, e abre o painel na configuração inicial (http://127.0.0.1:8795/, só no próprio PC; acesso por outros aparelhos se liga depois, no painel).

No Ubuntu 24.04, os pré-requisitos são sudo apt install git make curl xdg-utils pulseaudio-utils. Sem as ferramentas de áudio, o instalador avisa; o painel e a conversa por texto continuam funcionando. O controle completo da máquina é no Omarchy; outros Linux têm o controle reduzido.

Instalar numa VPS

Num Ubuntu 24.04 ou parecido, com um usuário comum (não root) e Git, Make e curl instalados:

git clone https://github.com/gestordescomplicaa-web/zervis.git
cd zervis && deploy/instalar-servidor.sh

O instalador prepara tudo, deixa o Zé rodando como serviço e termina com um endereço HTTPS e um código de primeiro acesso: abra o endereço, crie a senha e ligue o código do autenticador, sem túnel SSH. O passo a passo e o login do Claude e do Codex estão em docs/vps.md.

O comando zervis

Sem terminal, o mesmo update fica em Ajustes → Atualizações, no painel: o Zé procura uma vez por dia, avisa quando há versão nova, mostra o que muda e atualiza num clique.

Desenvolver

Linux, Python 3.12 a 3.14, Node.js 22+ e uv:

uv sync
npm ci
make check                 # formatação, lint, tipos e testes
uv run python -m zervis    # sobe o Zé; o painel abre em http://127.0.0.1:8795/

Na primeira subida, o Zé baixa os modelos de som e a voz (Cadu, 63 MB), confere o SHA-256 de cada um e abre a configuração inicial: perfil, acesso ao Claude (assinatura ou chave de API) e a chave do Deepgram para a voz. Sem a palavra de ativação treinada, ele atende pelo painel e pelo teclado. make instalar instala o serviço do systemd do usuário e o atalho "Zérvis" no menu de aplicativos (PORTA=8796 make instalar para outra porta).

Numa VPS, sem tela e sem som, o Zé não oferece o que a máquina não tem.

Onde ficam os seus dados

Nada é enviado ao repositório nem a terceiros sem pedido explícito. Nenhum nome, fuso ou caminho de alguém fica fixo no código: o que é seu vem da configuração. ZERVIS_PERFIL=<nome> usa outro conjunto de pastas (zervis-<nome>); ZERVIS_RAIZ=<pasta> põe as três dentro de uma pasta só.

Documentação

Licença

AGPL-3.0-or-later. A voz usa o Piper (GPL-3.0) e a voz Cadu (CC0); os demais componentes de terceiros e as licenças estão em THIRD_PARTY.md.