Antes de começar
Você precisa de pouco. Veja o que cada caminho pede:
Instalação local
- Node.js 24.11 ou superior
- Windows, macOS ou Linux. No Windows, direto no PowerShell: o WSL2 é opcional
- pnpm 9 ou superior (o Corepack, que vem com o Node, ativa)
- Git
Docker
- Docker Desktop (Windows e macOS) ou Docker Engine com Compose (Linux)
- Git
- Memória: a compilação do servidor usa até 4 GB. Se faltar, aumente o limite do Docker Desktop.
Chaves de IA (podem esperar)
O Hive sobe sem elas. Para os agentes trabalharem, configure ao menos uma: Anthropic (Claude), OpenAI (Codex) ou Google (Gemini). O assistente de primeiros passos pede a chave na etapa de conectar um modelo.
Instalação local
RecomendadoÉ o caminho que recomendamos. O Hive roda no seu computador, com um banco de dados embutido: não é preciso instalar o PostgreSQL.
Prepare o Node.js
Baixe o instalador do Node.js 24.11 ou superior em nodejs.org (abre em uma nova aba) e execute. Depois, abra um novo PowerShell e confira:
PowerShell node --versionInstale o Node.js 24.11 ou superior, pelo Homebrew ou pelo instalador de nodejs.org (abre em uma nova aba):
Terminal brew install nodenode --versionInstale o Node.js 24.11 ou superior pelo gerenciador que preferir (nvm, fnm) ou em nodejs.org (abre em uma nova aba). Exemplo com o nvm:
Terminal curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash# feche e abra o terminal, depois:nvm install 24node --versionO
node --versiondeve mostrarv24.11ou mais recente.Habilite o pnpm
O Node traz o Corepack, que instala a versão certa do pnpm para o projeto.
Terminal corepack enablepnpm --versionSe o
corepack enableacusar falta de permissão (comum no Windows), instale o pnpm pelo npm:npm.cmd install -g pnpmno PowerShell, ounpm install -g pnpmnos outros sistemas.Baixe o código e instale as dependências
Terminal git clone https://github.com/gugow06/hive.gitcd hivepnpm installNa primeira vez, a instalação leva alguns minutos.
Inicie o Hive
Terminal pnpm devQuando o endereço aparecer no terminal, abra
http://localhost:3100no navegador. No modo local o Hive não pede login.
Docker
Em validaçãoO Hive isolado num contêiner, com o banco de dados dentro dele e os dados guardados num volume.
Baixe o código
PowerShell git clone --config core.autocrlf=false https://github.com/gugow06/hive.gitcd hive\dockerA opção
core.autocrlf=falseimporta: o Git do Windows troca as quebras de linha dos arquivos e isso quebra a compilação (veja Dúvidas frequentes).Terminal git clone https://github.com/gugow06/hive.gitcd hive/dockerTerminal git clone https://github.com/gugow06/hive.gitcd hive/dockerCrie o arquivo de configuração
PowerShell Copy-Item .env.hive.example .env# gera o segredo de sessão:$b = New-Object byte[] 32; [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b); ($b | ForEach-Object { $_.ToString('x2') }) -join ''Terminal cp .env.hive.example .env# gera o segredo de sessão:openssl rand -hex 32Terminal cp .env.hive.example .env# gera o segredo de sessão:openssl rand -hex 32Abra o arquivo
.enve cole o valor gerado emBETTER_AUTH_SECRET: é o segredo que protege as sessões de login. Se quiser, preencha também as chaves de IA.Suba o Hive
Terminal docker compose -f docker-compose.hive.yml up -d --buildA primeira vez compila a imagem e leva vários minutos; as próximas usam o cache. Para acompanhar:
Terminal docker compose -f docker-compose.hive.yml logs -fAbra o Hive
Acesse
http://localhost:3100. No Docker o Hive roda no modo autenticado (o login é obrigatório) e a porta só abre na sua máquina.
Primeiros passos
Com o Hive aberto, o assistente conduz a configuração inicial em quatro etapas. A interface do produto ainda está em inglês; os nomes abaixo seguem a tela.
Name your organization
Dê um nome à organização: é a empresa ou o projeto que o Hive vai organizar.
Create your first agent
Crie o primeiro agente e escolha quem executa o trabalho dele: Claude Code, Codex, Cursor ou outro executor. Ele será o coordenador da equipe.
Connect a model
Informe a chave do provedor de IA (Anthropic, OpenAI ou Google) para o agente poder trabalhar.
Review
Confira o resumo e confirme. A organização está pronta.
Depois disso
- Crie a primeira tarefa e atribua ao coordenador: ele divide o trabalho em subtarefas para a equipe.
- Abra a Memória para ver os documentos que o time consulta e o grafo que liga todos eles.
- Acompanhe tudo na Auditoria: quem fez o quê, e quando.
Quer entender como as peças se encaixam? Veja como o Hive trabalha.
Atualizar, parar e remover
Instalação local
Para atualizar, dentro da pasta do projeto:
git pullpnpm installPara parar, pressione Ctrl+C no terminal. Seus dados ficam na pasta .paperclip, dentro da sua pasta de usuário, e continuam lá até você apagá-la.
Docker
Para atualizar, dentro da pasta docker:
git pulldocker compose -f docker-compose.hive.yml up -d --buildPara parar, ou para remover o contêiner mantendo os dados:
docker compose -f docker-compose.hive.yml stopdocker compose -f docker-compose.hive.yml downDúvidas frequentes
Preciso instalar o WSL no Windows? Quais as vantagens?
Não. O Hive roda direto no Windows, pelo PowerShell, e foi assim que o testamos. O WSL2 é um Linux dentro do Windows e é opcional.
Ele vale a pena se você já trabalha num ambiente Linux:
- Os agentes executam comandos no mesmo ambiente do Hive. No WSL2 eles usam bash e as ferramentas de Linux, como na maioria dos tutoriais e servidores.
- Projetos guardados dentro do sistema de arquivos do Linux abrem e compilam mais rápido do que os que ficam nas pastas do Windows.
- O ambiente fica igual ao do macOS e do Linux, o que reduz diferenças de caminho e de scripts.
O custo é manter tudo em dois lugares: Node.js, o Hive e as CLIs dos agentes precisam ser instalados dentro do Ubuntu, com os próprios logins. Se não precisa disso, fique no PowerShell.
A imagem Docker não compila (“Generated contract drift”)
É um problema conhecido da versão atual: a imagem ainda não compila de ponta a ponta. Use a instalação local por enquanto. Acompanhamos a correção no repositório (abre em uma nova aba).
No Windows, a compilação diz “The generated PRP contract manifest is stale”
Só acontece ao compilar pelo código-fonte. O Git do Windows converte as quebras de linha dos arquivos, e o Hive confere arquivos por assinatura. Clone de novo sem a conversão:
git clone --config core.autocrlf=false https://github.com/gugow06/hive.gitSe já clonou, apague a pasta e clone de novo com o comando acima. Evite “consertar” com git reset --hard sem antes salvar o que você alterou.
O Docker diz que BETTER_AUTH_SECRET não está definida
O arquivo .env não existe ou está sem o valor. Volte ao passo 2 da instalação com Docker: copie o .env.hive.example para .env e cole o segredo gerado.
O Docker não responde (“Cannot connect to the Docker daemon”)
O Docker está fechado. Abra o Docker Desktop e espere o aviso “Engine running”; no Linux, inicie o serviço do Docker. Depois repita o comando.
A porta 3100 já está em uso
No Docker, acrescente HIVE_PORT=3200 ao arquivo .env e suba de novo. Na instalação local, defina a variável antes do comando:
PORT=3200 pnpm devOs agentes não trabalham
Falta uma chave de IA, ou o executor escolhido (Claude Code, Codex…) não está instalado. O Hive mostra na tela o que falta na verificação do ambiente do agente: comece por ela.
Como adicionar o Claude Code, o Codex e o Gemini ao PATH?
O Hive chama claude, codex e gemini como qualquer comando do terminal. Se o terminal em que você roda o Hive não encontra o comando, o agente não executa. Escolha o agente que você usa:
Ele funciona com a sua assinatura do Claude (Pro, Max, Team ou Enterprise) ou com uma conta do Console. No primeiro uso, o claude abre o login no navegador.
Primeiro, confira se o terminal já encontra o comando:
claude --versionSe responder “command not found” (ou “não é reconhecido”, no Windows), a pasta dele não está no PATH. Escolha o seu sistema:
Se ainda não instalou (PowerShell):
irm https://claude.ai/install.ps1 | iexO instalador do Claude Code deixa o comando em %USERPROFILE%\.local\bin. Para pôr essa pasta no PATH do seu usuário, sem precisar de administrador:
$dir = "$env:USERPROFILE\.local\bin"$path = [Environment]::GetEnvironmentVariable("Path", "User")if (($path -split ";") -notcontains $dir) { [Environment]::SetEnvironmentVariable("Path", "$path;$dir", "User")}Se ainda não instalou:
curl -fsSL https://claude.ai/install.sh | bashO instalador do Claude Code deixa o comando em ~/.local/bin. Para pôr essa pasta no PATH: No macOS o shell padrão é o zsh:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrcsource ~/.zshrcSe ainda não instalou:
curl -fsSL https://claude.ai/install.sh | bashO instalador do Claude Code deixa o comando em ~/.local/bin. Para pôr essa pasta no PATH: No bash, o padrão da maioria das distribuições:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrcsource ~/.bashrcUsa zsh? Troque ~/.bashrc por ~/.zshrc.
Guia oficial: Claude Code (abre em uma nova aba).
Ele entra com a sua conta ou com uma chave da OpenAI, conforme o seu plano. No primeiro uso, o codex pede o login.
Primeiro, confira se o terminal já encontra o comando:
codex --versionSe responder “command not found” (ou “não é reconhecido”, no Windows), a pasta dele não está no PATH. Escolha o seu sistema:
Se ainda não instalou (PowerShell):
npm.cmd install -g @openai/codexO npm instala os pacotes globais na pasta npm.cmd prefix -g. Para pôr essa pasta no PATH do seu usuário, sem precisar de administrador:
$dir = (npm.cmd prefix -g)$path = [Environment]::GetEnvironmentVariable("Path", "User")if (($path -split ";") -notcontains $dir) { [Environment]::SetEnvironmentVariable("Path", "$path;$dir", "User")}Usamos npm.cmd porque, na configuração padrão do Windows, o PowerShell bloqueia o npm com o erro “a execução de scripts está desabilitada”.
Se ainda não instalou:
npm install -g @openai/codexO npm instala os pacotes globais na pasta $(npm prefix -g)/bin. Para pôr essa pasta no PATH: No macOS o shell padrão é o zsh:
printf 'export PATH="%s/bin:$PATH"\n' "$(npm prefix -g)" >> ~/.zshrcsource ~/.zshrcSe ainda não instalou:
npm install -g @openai/codexO npm instala os pacotes globais na pasta $(npm prefix -g)/bin. Para pôr essa pasta no PATH: No bash, o padrão da maioria das distribuições:
printf 'export PATH="%s/bin:$PATH"\n' "$(npm prefix -g)" >> ~/.bashrcsource ~/.bashrcUsa zsh? Troque ~/.bashrc por ~/.zshrc. Com nvm ou fnm, a pasta dos pacotes globais já entra no PATH sozinha quando a versão do Node está ativa.
Guia oficial: Codex (abre em uma nova aba).
Ele entra com a sua conta Google ou com uma chave do Gemini. No primeiro uso, o gemini pede o login.
Primeiro, confira se o terminal já encontra o comando:
gemini --versionSe responder “command not found” (ou “não é reconhecido”, no Windows), a pasta dele não está no PATH. Escolha o seu sistema:
Se ainda não instalou (PowerShell):
npm.cmd install -g @google/gemini-cliO npm instala os pacotes globais na pasta npm.cmd prefix -g. Para pôr essa pasta no PATH do seu usuário, sem precisar de administrador:
$dir = (npm.cmd prefix -g)$path = [Environment]::GetEnvironmentVariable("Path", "User")if (($path -split ";") -notcontains $dir) { [Environment]::SetEnvironmentVariable("Path", "$path;$dir", "User")}Usamos npm.cmd porque, na configuração padrão do Windows, o PowerShell bloqueia o npm com o erro “a execução de scripts está desabilitada”.
Se ainda não instalou:
npm install -g @google/gemini-cliO npm instala os pacotes globais na pasta $(npm prefix -g)/bin. Para pôr essa pasta no PATH: No macOS o shell padrão é o zsh:
printf 'export PATH="%s/bin:$PATH"\n' "$(npm prefix -g)" >> ~/.zshrcsource ~/.zshrcSe ainda não instalou:
npm install -g @google/gemini-cliO npm instala os pacotes globais na pasta $(npm prefix -g)/bin. Para pôr essa pasta no PATH: No bash, o padrão da maioria das distribuições:
printf 'export PATH="%s/bin:$PATH"\n' "$(npm prefix -g)" >> ~/.bashrcsource ~/.bashrcUsa zsh? Troque ~/.bashrc por ~/.zshrc. Com nvm ou fnm, a pasta dos pacotes globais já entra no PATH sozinha quando a versão do Node está ativa.
Guia oficial: Gemini CLI (abre em uma nova aba).
Os demais agentes, como Cursor, OpenCode e Kimi, seguem o mesmo padrão: instale a CLI, deixe o comando no PATH e entre com a sua assinatura (ou com uma chave de API, quando o agente aceitar). Cada um tem o seu guia oficial.
Depois de ajustar o PATH, feche e abra o terminal, rode o --version de novo e inicie o Hive outra vez com pnpm dev. Ele só enxerga o PATH do terminal que o iniciou.
Preferiu não mexer no PATH? No agente, preencha o campo command com o caminho completo, por exemplo /home/voce/.local/bin/claude.
O Hive envia dados para fora da minha máquina?
As suas tarefas, os documentos e as chaves ficam com você. Nesta versão beta, porém, o Hive vem com a telemetria de uso ligada por padrão e envia eventos técnicos ao projeto original, o Paperclip. Pelas regras do projeto, esses eventos não incluem o conteúdo das tarefas, dos documentos nem as suas chaves.
Para desligar, defina a variável antes de iniciar o Hive:
export PAPERCLIP_TELEMETRY_DISABLED=1pnpm devPara deixar fixo, acrescente a primeira linha ao ~/.bashrc ou ao ~/.zshrc. A variável DO_NOT_TRACK=1 também funciona. No Docker, o nosso arquivo de configuração já vem com a telemetria desligada. A política de privacidade explica o que cada parte trata.
Onde ficam os meus dados?
Na instalação local, na pasta .paperclip da sua pasta de usuário (a pasta pode ser trocada com a variável PAPERCLIP_HOME). No Docker, no volume hive-data.
Não achou o seu caso? Abra uma issue (abre em uma nova aba) ou escreva para contato@hiveagents.com.br.