Introdução

Read this documentation in English

zombie-crab-project dá a cada usuário o seu próprio agente de IA, real e isolado, atrás de uma única porta de entrada autenticada. Este livro explica como executá-lo, como configurá-lo e como ele é montado.

O problema que ele resolve

Um assistente de IA auto-hospedado costuma ser construído em torno de uma ideia: um agente, um dono. Isso funciona bem no seu próprio laptop. Deixa de funcionar no momento em que uma segunda pessoa entra.

Um agente de IA lê e escreve arquivos, roda ferramentas, executa código e mantém memória de longa duração — tudo isso guiado por linguagem natural que ninguém verificou. Em um único processo compartilhado, uma prompt injection, um bug de path traversal ou uma ferramenta que vaza basta para um usuário ler as conversas, os arquivos e os segredos de outro. Separar usuários por uma chave em um mapa parece isolamento. Não é.

Este projeto responde a isso com uma fronteira que o kernel impõe, e não a aplicação. Cada usuário ganha o seu próprio container e o seu próprio volume, iniciado quando ele fala pela primeira vez e parado quando ele se cala. Se o agente de um usuário for completamente comprometido, ele ainda assim não alcança os dados de outro: outro container, outro volume, sem root, nenhuma superfície compartilhada.

Na frente disso fica uma única entrada autenticada. Um API gateway verifica quem está chamando e injeta um perfil de conta que o chamador não consegue forjar, de modo que a identidade desce de algo confiável em vez de subir do corpo da requisição. Os usuários são identificados por um id de conta estável, e não por um endereço de e-mail — troque o seu e-mail e o seu agente, com tudo que ele lembra, continua sendo seu.

Para quem é este livro

Se você quer executá-lo, o início rápido está a um clone, um .env e um comando compose de distância de um chat funcionando. Você precisa de um terminal e do Docker; não precisa saber Go, nem como nada disso foi construído.

Se você administra um deploy — convidando membros, decidindo qual modelo cada pessoa recebe, publicando skills e documentos compartilhados — os capítulos de administração foram escritos para você, e não supõem mais do que saber usar uma interface web.

Se você vai estendê-lo, os capítulos de componentes descrevem cada peça em separado, e o capítulo de desenvolvimento cobre o build e os gates pelos quais uma mudança tem de passar.

Se você está avaliando o projeto, leia esta página e depois Como a stack se encaixa. A versão curta: a stack tem três camadas, cada uma com exatamente um trabalho, e cada uma substituível sem tocar nas outras duas.

As palavras que este livro usa

Quatro termos aparecem em toda parte e vale a pena fixá-los antes de você encontrá-los em um comando.

Um harness é o programa que de fato é o agente: ele mantém a conversa, chama o modelo, roda as ferramentas. Este projeto escreve o seu próprio, o ganglion, e é ele que esta documentação ensina. Um harness mais antigo, o picoclaw, ainda é suportado e está de saída. Qual dos dois responde é declarado por agente.

Um agente é uma configuração com nome — um harness, um modelo, uma política de ciclo de vida, uma personalidade. alpha e beta são os dois que este repositório traz. Um agente não é um processo: cada membro que usa um agente ganha o seu próprio container executando-o.

Um tenant é uma organização, e uma subscription é uma conta dentro dele à qual os membros pertencem. Juntos, os dois decidem quem pode alcançar qual agente. Um membro alcança um agente quando tem um papel com o nome dele.

Um workspace é o diretório de um membro para um agente: as conversas dele, a memória dele, os arquivos dele. É o que o container recebe e que nada mais consegue ver.

Lendo este livro

Comece pelo início rápido. É o capítulo que todos os outros pressupõem. Ele leva um clone novo até uma conversa com o seu próprio agente em oito passos numerados, e cada um diz como saber que deu certo. Leia mesmo que você não pretenda segui-lo, porque os capítulos seguintes ficam mais fáceis de situar depois que você viu as peças subirem.

Daí em diante o livro está em grupos, e você pode escolher o que combina com o que você está fazendo.

Primeiros passos é o início rápido, depois Instalação para a versão longa — pré-requisitos detalhados, o que a primeira execução escreve em disco e como zerar tudo — e Configuração para cada arquivo e variável que você tocou no caminho.

Conceitos centrais explica o que a stack está fazendo. Como a stack se encaixa é a arquitetura e o raciocínio por trás do formato dela. Harnesses cobre os dois runtimes de agente e como um deles é escolhido. Agentes, workspaces e projetos cobre o layout em disco, skills e memória o que um agente sabe e lembra, e arquivos e entrega como um documento entra e como um resultado volta.

Uso é escrito para um membro, e não para um operador: o cliente de chat, os projetos e as tarefas agendadas.

Administração é o trabalho do dia seguinte: o guia de administração, criar um agente personalizado de ponta a ponta, e modelos e provedores.

Operação cobre os modos de deploy, o banco de dados e o seu único passo manual de migração, observabilidade e solução de problemas — que reúne as falhas que as pessoas realmente encontram, e vale uma passada de olho antes de você precisar dela.

Os componentes são um capítulo para cada um dos quatro programas do repositório: o orquestrador, o harness ganglion, o cliente de chat e o observador.

Desenvolvimento cobre trabalhar na stack e contribuir.

Cada capítulo é dono do seu assunto e aponta para os outros em vez de repeti-los. Se uma página parece parar antes de um tópico, o link naquele ponto é onde o tópico mora.

Uma palavra sobre o que isto não é

Esta stack foi ajustada para ser legível e fácil de rodar localmente, não para vir endurecida de fábrica. O orquestrador detém o socket do Docker e roda como root; é o componente mais privilegiado da stack e o primeiro que você isola antes de expor qualquer coisa. O tráfego entre o gateway e o que está atrás dele não é criptografado, porque se espera que o gateway seja a única coisa voltada para uma rede. Os segredos da configuração de exemplo são apenas marcadores, e dizem isso.

Nada disso está escondido neste livro. Onde um padrão é uma conveniência de desenvolvimento, o capítulo dono dele diz isso e diz o que fazer no lugar.