Início rápido

Este capítulo leva você de um clone novo até uma conversa com o seu próprio container de agente. Siga-o de cima para baixo. Todo comando aqui é executado a partir da raiz do checkout, e nada nele supõe que você já usou esta stack antes.

O caminho descrito é o mais curto que funciona: o arquivo compose de desenvolvimento, o agente alpha e um usuário — você. Tudo o mais que a stack sabe fazer é assunto de um capítulo posterior.

Antes de começar

Você precisa de quatro coisas:

• Docker, com o plugin Compose v2 (docker compose, não docker-compose). O arquivo compose de desenvolvimento usa depends_on: condition: service_completed_successfully, que é um recurso do Compose v2.
• Git, porque o produto é montado a partir de quatro submódulos e um clone sem eles não constrói nada.
• Uma chave de API de LLM. Os dois agentes que este repositório traz estão configurados para a DeepSeek (provider: "deepseek", name: "deepseek-chat" em crab/crab-shell-proxy/config.yaml), então uma chave da DeepSeek dá menos trabalho. Trocar o provedor é configuração, não mudança de código.
• Acesso à internet durante o build, e paciência na primeira vez. Este arquivo compose constrói seis imagens a partir do código-fonte, incluindo o gateway do Mycelium a partir de um commit git upstream.

Os builds de imagem rodam com network: host porque um container do BuildKit recebe um único resolvedor DNS utilizável e nenhum fallback, e builds em paralelo perdem consultas. Isso já está escrito no arquivo compose; você não passa nenhuma flag para isso.

1. Clone o repositório com os submódulos dele

git clone --recurse-submodules \
  https://github.com/LepistaBioinformatics/zombie-crab-project.git
cd zombie-crab-project

Como saber que deu certo: ls crab/crab-shell-proxy lista código-fonte Go. Se o diretório estiver vazio, você clonou sem os submódulos; rode git submodule update --init --recursive para corrigir sem clonar de novo.

2. Crie o seu .env

O repositório traz um exemplo comentado por modo de deploy. Copie o standalone, que é o padrão local:

cp deploy/standalone/.env.example .env

Agora abra o .env e substitua os valores de exemplo. Cinco deles importam para este passo a passo:

Gere os segredos em vez de inventá-los; o arquivo de exemplo sugere openssl rand -hex 32 para cada um, e qualquer string longa e aleatória serve.

Os nomes com cara de picoclaw no alpha não são erro de copiar e colar. O alpha já rodou picoclaw e foi movido para o ganglion sobre os mesmos diretórios por usuário; o serviceName e o token dele foram deixados de propósito como estavam, porque o gateway roteia pelo primeiro e injeta o segundo, então renomear qualquer um dos dois teria sido um agente novo para cada membro, em vez do mesmo agente em um runtime novo.

Os dois tokens de agente precisam estar definidos, mesmo que você use só um agente. O agente beta roda o harness picoclaw, e para um agente picoclaw um token que resolve para nada é fatal: o proxy se recusa a subir em vez de tirar em silêncio o acesso de um membro. O alpha roda o harness ganglion, onde a mesma omissão desativa apenas aquele agente. Veja harnesses para entender de onde vem essa diferença.

PICOCLAW_BETA_API_KEY pode ficar com o sk-your-beta-key do exemplo. A chave de um agente picoclaw é escrita na configuração do próprio usuário no momento do provisionamento, e uma chave errada aparece como erro de autenticação na primeira mensagem — ela não impede nada de subir. PICOCLAW_ALPHA_API_KEY é diferente: como o alpha é um agente ganglion, um valor vazio faz o proxy desativar o alpha na subida, e as rotas dele passam a responder 404.

3. Suba a stack

docker compose up -d --build

Como saber que deu certo: docker compose ps lista os serviços. Dois deles têm mesmo de ter sumido:

picoclaw-image    Exited (0)
ganglion-image    Exited (0)

Esses dois são serviços só de build. Eles existem para que docker compose up produza as duas imagens de harness em vez de deixar isso como um passo manual que alguém esquece; cada um roda /bin/true e sai. Todo o resto deve estar running, e crab-shell-proxy e mycelium-gateway devem chegar a healthy.

Neste modo o proxy publica uma porta apenas de loopback, então você pode conferi-lo diretamente:

curl http://127.0.0.1:18080/healthz

Depois confirme que nenhum agente se desativou:

docker compose logs crab-shell-proxy | grep disabled

O silêncio é o bom resultado. Uma linha na forma agent "alpha" disabled: … — its routes will answer 404 nomeia a variável de ambiente que você ainda tem de definir, e você deve corrigir isso antes de seguir.

O build da própria imagem do ganglion roda go vet e go test antes de linkar o binário. Isso é de propósito — os testes são o teste de aceitação da imagem — então um teste falhando impede a stack de subir, em vez de entregar um harness quebrado.

4. Reivindique a conta Staff (uma vez por deploy)

O gateway começa sem conta nenhuma. A primeira é reivindicada por um fluxo web de uso único, liberado pelo segredo de bootstrap que você definiu no passo 2.

Abra http://localhost:8080/_adm/instance/bootstrap, envie o segredo de bootstrap e o seu endereço de e-mail. O deploy standalone não manda e-mail: o transporte de e-mail dele escreve no log. Leia de lá o código de seis dígitos:

docker compose logs mycelium-gateway | grep -i bootstrap

Conclua a reivindicação com esse código.

Como saber que deu certo: o fluxo devolve um token de Staff, e a URL de bootstrap para de responder — é um endpoint de uso único e vira 404 depois de reivindicado.

Use um endereço real que você reconheça depois. É a conta com a qual você vai entrar, e esse mesmo endereço tem de ser o que você convida no passo 6.

5. Crie um tenant e uma subscription

Um agente é alcançado dentro de um tenant (uma organização) por meio de uma subscription (uma conta sob esse tenant à qual os membros pertencem). A sua conta Staff pode criar as duas coisas, na própria interface de administração do Mycelium em http://localhost:8081: entre lá com a conta que você acabou de reivindicar e siga a cadeia Staff → tenant → subscription.

Essas telas pertencem ao Mycelium e são construídas a partir de fontes upstream, então este livro não as descreve clique a clique. O que importa aqui é o resultado: existe um tenant, e existe uma conta de subscription sob ele.

Como saber que deu certo: a subscription aparece na lista do tenant nessa mesma interface, e você consegue selecioná-la no passo 6.

6. Dê a si mesmo o papel alpha

Alcançar um agente é uma permissão, não um padrão. O gateway declara as rotas dele como protectedByRoles, com um papel nomeado a partir de cada agente, então uma conta precisa ter o papel de convidado alpha — em write, que é o que enviar uma mensagem exige — antes que qualquer outra coisa funcione. Enquanto não tiver, toda requisição é recusada com um erro de permissão.

Os papéis em si já existem: declará-los na configuração do gateway basta para o Mycelium criá-los na subida. Manual mesmo é a concessão. Faça isso pelo mesmo fluxo Staff → tenant → subscription → convite de convidado em http://localhost:8081, convidando o seu próprio endereço de e-mail para o papel alpha com acesso de escrita.

Como saber que deu certo: o convite aparece vinculado à sua conta naquela subscription. Quando uma subscription já tem membros, as mesmas concessões podem ser feitas pela própria área de administração do chat-webapp — veja o guia de administração.

7. Entre no cliente de chat

Abra http://localhost:3000. Este é o chat-webapp, o cliente voltado ao membro. Entre com o mesmo endereço de e-mail: não há senha, só um magic link, e neste modo o código dele vai para o log em vez de ser enviado por e-mail:

docker compose logs mycelium-gateway | tail -50

No primeiro acesso o aplicativo oferece criar a sua conta antes de deixar você entrar no chat; aceite, e ele a cria para você no gateway.

Como saber que deu certo: você cai na tela de chat em vez do formulário de entrada.

8. Envie a sua primeira mensagem

Sem nenhum workspace selecionado, a área de chat é um seletor: uma linha por tenant, uma caixa por subscription e um bloco para cada agente que você pode alcançar. Escolha alpha e envie uma mensagem.

Como saber que deu certo: o agente responde — e um container que não existia um instante atrás está rodando agora:

docker ps --filter name=crabshell

Você vai ver algo como crabshell-alpha-1a2b3c4d5e6f7890, rodando como um usuário sem root. O sufixo é um hash do seu tenant, da sua subscription e da sua conta: um nome de container é limitado a 63 caracteres, então a identidade mora nos labels do container, e não no nome dele.

Aquele container é seu. O agente de mais ninguém consegue ler os arquivos, a memória ou as conversas dele, porque é um container diferente com um volume diferente — que é justamente o ponto desta stack.

O alpha está configurado para escalar até zero. Cerca de meio minuto depois da sua última mensagem o container dele para, liberando a memória; a sua próxima mensagem o inicia de novo com tudo intacto. Um agente parado é normal, não uma falha.

Para onde ir agora

Se algum passo não coube na sua máquina — uma versão do Docker, um caminho, uma porta já em uso — Instalação é a versão longa dos passos 1 a 3, e explica o que a primeira execução escreve em disco e como apagar tudo. Para trocar o modelo, adicionar um agente ou entender o que você acabou de editar no .env, leia Configuração. Para entender o que de fato aconteceu quando você apertou enviar, leia Como a stack se encaixa.