Instalação
Esta é a versão longa dos três primeiros passos do início rápido. Leia quando aquela página não couber na sua máquina, quando você quiser saber o que a stack escreve no seu disco, ou quando precisar zerar um ambiente.
Pré-requisitos
Docker Engine com o plugin Compose v2. O comando é docker compose, com espaço. O arquivo compose de desenvolvimento espera por serviços que só fazem build com depends_on: condition: service_completed_successfully, que o script v1 docker-compose não entende. Se você também pretende rodar o overlay de produção, precisa do Compose 2.24 ou mais novo: docker-compose.prod.yaml usa a tag !reset para descartar o build: do arquivo base e a publicação de portas de desenvolvimento, e versões mais antigas não conseguem interpretá-la.
Git. O produto são quatro submódulos — o orquestrador, o harness, o cliente web e o watcher — e o arquivo compose faz o build a partir das árvores de trabalho deles.
Espaço suficiente para o build. Um primeiro up --build compila sete imagens a partir do código-fonte: o picoclaw com patch, o harness ganglion, o proxy, o cliente de chat, o watcher, o gateway Mycelium (construído a partir de um commit git upstream) e a interface de administração do Mycelium. Só o Postgres vem pronto. Espere que a primeira execução demore e que todas as seguintes sejam rápidas.
Portas livres no host. Na configuração padrão a stack publica 8080 para o gateway, 3000 para o cliente de chat, 8081 para a interface de administração do Mycelium e 127.0.0.1:18080 para a porta do proxy usada só em desenvolvimento. Os bancos de dados e os containers dos agentes não publicam nada: só são alcançáveis de dentro da rede da própria stack. Cada porta publicada é uma variável de ambiente (MYCELIUM_PORT, CHAT_WEBAPP_PORT, MYCELIUM_WEBAPP_PORT), então uma colisão é uma edição no .env, não um problema. Se você mudar MYCELIUM_WEBAPP_PORT, mude allowedOrigins na configuração do gateway junto — a interface de administração é uma aplicação que roda no navegador e chama o gateway diretamente, e uma divergência é um muro de CORS.
Uma chave de LLM. Os dois agentes que já vêm prontos estão configurados para o DeepSeek. O provedor é configuração, não código; veja modelos e provedores.
Clonando com submódulos
git clone --recurse-submodules \
https://github.com/LepistaBioinformatics/zombie-crab-project.git
Se você já clonou sem essa flag, os diretórios dos submódulos existem mas estão vazios. Preencha-os no lugar:
git submodule update --init --recursive
--recursive importa: os submódulos estão declarados no .gitmodules deste nível, mas este repositório é ele mesmo o meio de uma cadeia e vale manter o hábito.
O que há no repositório
docker-compose.yaml the whole stack, standalone/development default
docker-compose.prod.yaml production overlay (published images, Postgres)
docker-compose.observability.yaml opt-in metrics backend (collector, Prometheus, Grafana)
deploy/ per-mode configuration
standalone/ .env.example + the gateway config this mode mounts
prod/ the same pair for production
observability/ collector, Prometheus and Grafana configuration
picoclaw-glob/ the Dockerfile and patches for the picoclaw image
crab/ the crab side, one submodule per component
crab-shell-proxy/ the orchestrator (Go) — holds the Docker socket
crab-ganglion-harness/ this project's own agent runtime (Go)
crab-exoskeleton-webapp/ the chat client; its compose service is chat-webapp
harness-sphere/ the watcher; observability only, never a Docker socket
fungi/ the Mycelium side: gateway and admin UI Dockerfiles
docs/ task guides and this book
data/ everything the running stack writes (gitignored)
Dois nomes valem ser fixados na cabeça agora, porque diferem do diretório em que vivem. O repositório do cliente de chat é crab-exoskeleton-webapp, mas o serviço dele no compose — e portanto o nome em todo comando docker compose — é chat-webapp. E deploy/ guarda dois modos de deploy, standalone e prod; observability/ e picoclaw-glob/ são configuração para um overlay e para o build de uma imagem, não modos com os quais você pode subir a stack.
O que a primeira execução cria
Nada dentro de data/ está no git, e o diretório não precisa existir antes de você começar. O proxy cria o que precisa conforme avança, como root, porque é o componente que segura o socket do Docker.
data/templates/<agent>/— a semente por agente, clonada para o diretório de cada novo usuário. Para um agente picoclaw o proxy faz isso sozinho a partir de um template padrão compilado no próprio binário, então um checkout novo funciona sem nenhum passo de seeding. Um agente ganglion não recebe template nenhum: o template é um arquivo de configuração do picoclaw mais o arquivo de segurança dele, e escrever um para o ganglion deixaria dois arquivos que ninguém lê.data/tenants/<tenant>/subscriptions/<subscription>/agents/<agent>/users/<account>/— um workspace isolado por membro por agente. Esta é a árvore que é montada por bind nos containers dos agentes, e o único lugar onde vivem as conversas, a memória e os arquivos de um membro.data/user-secrets/edata/effective-secrets/— o cofre de segredos do próprio membro, e a visão mesclada dele com o que um administrador compartilhou no nível do tenant ou da subscription. A visão mesclada é o que é montado dentro de um container, somente leitura.data/effective-skills/,data/effective-persona/,data/managed-skills/— a mesma ideia para as skills e para os arquivos de identidade do agente. Veja skills e memória.data/restart/— marcadores de restart, deliberadamente fora da árvore do tenant para que um agente não consiga ler nem escrever o seu.data/model-registry.db— o registro de modelos do proxy, um único arquivo de banco de dados embutido ao lado dos diretórios.
Dois volumes nomeados do Docker também são criados, e eles não ficam dentro de data/: mycelium-data guarda o banco SQLite do próprio gateway, que é onde vivem contas, tenants e papéis, e chat-webapp-postgres-data guarda a lista de conversas que o cliente de chat mantém. O cliente de chat cria as próprias tabelas no primeiro uso, então não há passo de migração para ele.
O deploy de produção é diferente em exatamente um ponto doloroso: o backend Postgres do Mycelium não tem migrações embutidas, então o schema dele precisa ser aplicado à mão uma vez, depois da primeira subida. O SQLite aplica as suas sozinho. Veja o capítulo do banco de dados.
Rodando de outro lugar que não a raiz do projeto
O proxy entrega ao daemon do Docker um caminho no host como origem do bind-mount de todo container que ele cria, então esse caminho precisa ser um que o daemon consiga resolver — não um caminho dentro do container do proxy. O arquivo compose usa ${PWD}/data como padrão, o que é correto quando você roda docker compose a partir da raiz do projeto e errado nos outros casos. Se você roda de outro lugar, defina isso explicitamente no .env:
CRAB_HOST_DATA_ROOT=/absolute/path/to/zombie-crab-project/data
Voltando a um estado limpo
Para apagar todo agente por usuário e todos os templates e deixar a stack se reconstruir, pare a stack, remova os containers que o proxy criou fora do compose, apague o estado em disco e suba tudo de novo:
docker compose down
# os agentes não são serviços do compose, então o compose não os remove
docker rm -f $(docker ps -aq --filter 'name=crabshell') 2>/dev/null
# a árvore é escrita por processos que rodam como root, daí o sudo
sudo rm -rf data/templates data/tenants data/user-secrets data/effective-secrets \
data/effective-skills data/effective-persona data/managed-skills \
data/restart data/model-registry.db
docker compose up -d --build
--build não é opcional aqui. O template padrão a partir do qual o proxy refaz o bootstrap está embutido no binário dele, então uma imagem anterior a uma mudança de template restauraria o template antigo.
Depois entre na sua conta e mande uma mensagem: o proxy provisiona seu usuário de novo a partir do nada. Seu login sobrevive, porque contas, tenants e papéis estão no volume mycelium-data e não em data/, e sua lista de conversas também. Adicione -v ao docker compose down só se você quiser essas coisas fora também — aí você teria que reivindicar a conta Staff de novo desde o começo.
Para onde ir agora
Configuração cobre todo arquivo que você acabou de copiar ou editar e o que cada variável faz. Deploy cobre o overlay de produção e como os dois modos diferem. Se alguma coisa não subiu, solução de problemas reúne as falhas que as pessoas realmente encontram.