Como Instalar o Kiro Crew no Coolify com Telegram

Diagrama de deploy mostrando container Docker, Coolify e Telegram conectados, representando o fluxo de instalação do Kiro Crew

Você quer um agente de IA que trabalhe enquanto você dorme, responda pelo Telegram, e rode na sua própria infra. O Kiro Crew faz isso — mas a documentação oficial foca em instalação manual num host Linux. Como fazer isso funcionar no Coolify, com deploy automatizado e persistência de dados?

Este guia cobre o setup completo: do container rodando no Coolify até você mandando mensagem pro bot no Telegram e recebendo respostas do agente.

Pré-requisitos

Antes de começar, você precisa de:

Coolify instalado numa VPS (Oracle Cloud, Hetzner, DigitalOcean, etc.)
Kiro CLI autenticado — rode kiro login localmente primeiro
Bot do Telegram criado — vamos configurar no tutorial
Acesso SSH ao servidor do Coolify

Sobre a Escolha de Infra

O Kiro Crew precisa de recursos razoáveis:

RAM: mínimo 2GB, recomendado 4GB+ (o modelo de embeddings sozinho usa ~610MB)
CPU: 2 vCPUs funcionam, mais ajuda em execução paralela
Disco: 5GB+ para o modelo de embeddings e dados persistentes

Uma instância Always Free da Oracle Cloud (A1 Flex com 24GB RAM) funciona perfeitamente. Se estiver apertado de recursos, considere rodar direto no host em vez de container — o overhead de Docker consome memória extra.

Passo 1: Criar o Bot do Telegram

Primeiro, crie seu bot no Telegram:

Abra o Telegram e busque por @BotFather
Mande /newbot
Escolha um nome (ex: “Meu Kiro Crew”)
Escolha um username (ex: meu_kirocrew_bot)
Guarde o token que o BotFather vai te dar — formato: 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Pegar seu User ID

O Kiro Crew precisa saber quem pode usar o bot. Para descobrir seu ID:

Busque por @userinfobot no Telegram
Mande qualquer mensagem
Ele responde com seu ID numérico (ex: 123456789)

Guarde esse número — você vai usar como KIROCREW_OWNER_ID.

Passo 2: Preparar o Deploy no Coolify

Arquitetura de deploy do Kiro Crew no Coolify: VPS com container Docker, volumes persistentes, conexão via Telegram e SSH tunnel

No Coolify, você tem duas opções:

Opção A: Usar a Imagem Docker Oficial

A forma mais simples. No Coolify:

Vá em Projects → selecione seu projeto
Clique em + New → Docker Image
Configure:
- Image: ghcr.io/kirodotdev/kirocrew:latest
- Name: kirocrew

Opção B: Build de Imagem Customizada

Se você precisa de ferramentas extras (AWS CLI, gh, etc.), crie um Dockerfile customizado:

FROM ghcr.io/kirodotdev/kirocrew:latest

# Instalar ferramentas adicionais
RUN apt-get update && apt-get install -y \
    awscli \
    gh \
    jq \
    && rm -rf /var/lib/apt/lists/*

# Ou usar uma imagem base mais completa
# FROM ubuntu:24.04
# ... instalação completa do Kiro Crew + suas ferramentas

Pra essa opção, use Git Repository no Coolify apontando pro seu repo com o Dockerfile.

Passo 3: Configurar Variáveis de Ambiente

No Coolify, vá em Environment Variables e adicione:

# Telegram Bot
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

# ID do owner (seu user ID do Telegram)
KIROCREW_OWNER_ID=123456789

# Porta do dashboard (opcional, default 5476)
KIROCREW_PORT=5476

# Bind address (necessário em container)
KIROCREW_BIND=0.0.0.0

Variáveis Opcionais

# Se você quer expor o dashboard via HTTPS (não recomendado sem auth adicional)
# KIROCREW_DASHBOARD_URL=https://kirocrew.seudominio.com

# Para múltiplos owners
# KIROCREW_OWNER_ID=123456789,987654321

Passo 4: Configurar Volumes para Persistência

Diagrama de mapeamento de volumes Docker mostrando diretórios do container conectados a storage persistente no host

Dados do Kiro Crew ficam em ~/.kiro/crew/. No container, você precisa montar volumes para não perder dados no redeploy.

No Coolify, vá em Storages e adicione:

Source (host)	Destination (container)	Descrição
`/data/kirocrew/crew`	`/root/.kiro/crew`	Config, memória, lessons, skills
`/data/kirocrew/kiro`	`/root/.kiro`	Credenciais do Kiro CLI

Crie os diretórios no host antes do primeiro deploy:

ssh seu-servidor
sudo mkdir -p /data/kirocrew/{crew,kiro}
sudo chown -R 1000:1000 /data/kirocrew

Passo 5: Autenticar o Kiro CLI no Container

O Kiro Crew precisa do Kiro CLI autenticado. A forma mais simples é copiar suas credenciais locais para o volume:

# No seu computador local
scp -r ~/.kiro/* seu-servidor:/data/kirocrew/kiro/

Ou faça login diretamente no container após o primeiro deploy:

# No servidor
docker exec -it <container_id> kiro login

Passo 6: Configurar Rede

Comparativo de 3 métodos de acesso ao Kiro Crew: Telegram (recomendado), SSH Tunnel (seguro), HTTPS público (avançado)

Opção Segura: Apenas Telegram (Recomendado)

Se você só vai acessar via Telegram, não precisa expor porta nenhuma. O bot usa long polling — ele que conecta no servidor do Telegram, não o contrário.

No Coolify:

Deixe Ports vazio ou não mapeie a porta 5476 externamente

Opção com Dashboard: SSH Tunnel

Se você quer acessar o dashboard web, use SSH tunnel em vez de expor publicamente:

# Do seu computador
ssh -L 5476:localhost:5476 seu-servidor
# Acesse http://localhost:5476

Opção Avançada: HTTPS com Cloudflare Tunnel

Se você realmente precisa de acesso remoto ao dashboard:

Configure um Cloudflare Tunnel apontando para localhost:5476
Adicione autenticação via Cloudflare Access
Configure KIROCREW_DASHBOARD_URL=https://kirocrew.seudominio.com

⚠️ Atenção: O dashboard tem autenticação por token, mas expor na internet adiciona superfície de ataque. Prefira SSH tunnel ou Telegram.

Passo 7: Deploy e Verificação

Pipeline completo de deploy em 6 etapas: criar bot Telegram, configurar Coolify, env vars, volumes, autenticar CLI, deploy

No Coolify:

Clique em Deploy
Acompanhe os logs de build

Após o deploy, verifique se está funcionando:

# Ver logs do container
docker logs -f <container_id>

# Deve mostrar algo como:
# Starting Kiro Crew gateway...
# Telegram bot connected
# Dashboard running on http://localhost:5476

Testar o Bot

No Telegram, mande uma mensagem pro seu bot:

/start

Ele deve responder com instruções de uso. Teste uma tarefa simples:

Qual a versão do Python instalada?

Passo 8: Configuração Inicial

Na primeira execução, o Kiro Crew vai:

Baixar o modelo de embeddings (~610MB) — isso demora alguns minutos
Criar os bancos de dados de memória
Inicializar a configuração padrão

Você pode rodar o setup interativo:

docker exec -it <container_id> kirocrew setup

Ou editar diretamente o config.json:

docker exec -it <container_id> cat /root/.kiro/crew/config.json

Sincronizar Estado de Outra Máquina

Se você já usava o Kiro Crew localmente e quer migrar pro servidor:

# Script oficial de sync (rode do seu computador local)
cd KiroCrew
scripts/sync-to-remote.sh usuario@seu-servidor

Isso copia:

Memória e lessons
Skills customizadas
Configurações
Histórico de sessões

Comandos Úteis do Telegram

Depois de configurado, você pode usar:

Comando	Descrição
`/kirocrew status`	Status do gateway
`/kirocrew dashboard`	Gera link temporário pro dashboard
`/kirocrew dashboard 6h`	Link válido por 6 horas
`/kirocrew jobs`	Lista cron jobs
`/kirocrew lessons`	Lista lessons aprendidas

Mensagens normais são tratadas como prompts pro agente.

Troubleshooting

Bot não responde

Verifique se o token está correto
Confira os logs: docker logs <container_id>
Verifique se KIROCREW_OWNER_ID está certo

“Embeddings not ready”

O modelo está baixando. Aguarde alguns minutos e verifique os logs:

docker logs -f <container_id> | grep -i embed

Kiro CLI não autenticado

docker exec -it <container_id> kiro login

Memória não persiste após redeploy

Verifique se os volumes estão montados corretamente:

docker inspect <container_id> | grep -A 10 Mounts

Container reiniciando em loop

Provavelmente é falta de memória. Verifique:

docker stats <container_id>

Se RAM estiver no limite, considere:

Aumentar recursos da VPS
Rodar direto no host sem Docker
Usar uma instância com mais RAM

Considerações de Segurança

O que o Kiro Crew Tem Acesso

Código: se você apontar pra um diretório, ele tem acesso total
Comandos: pode executar shell commands (com sandbox)
Rede: pode fazer requests HTTP
Secrets: redação automática, mas cuidado com o que você cola no chat

Recomendações

Não exponha o dashboard publicamente — use SSH tunnel ou Telegram
Restrinja owners — só adicione IDs de pessoas que devem ter acesso
Monitore audit log — todo comando executado é logado
Use secrets via env vars — não cole API keys no chat
Backup regular — rsync do diretório /data/kirocrew/

Setup Alternativo: Direto no Host

Se o overhead de Docker é problema ou você quer mais controle, instale direto no host:

# No servidor
git clone https://github.com/kirodotdev/KiroCrew.git
cd KiroCrew

# Build frontend
cd website && npm install && npm run build && cd ..
cp -R website/dist src/kiro_crew/static/dist

# Install backend
pip install .

# Setup
kirocrew setup
kirocrew doctor

# Rodar como serviço
kirocrew service install

Essa abordagem usa menos recursos e facilita instalar ferramentas CLI (aws, gh, etc.) diretamente no sistema.

Próximos Passos

Com o Kiro Crew rodando, você pode:

Configurar cron jobs para digests matinais
Criar skills específicas pro seu workflow
Adicionar MCP servers para ferramentas extras
Instalar Apps como Issue Radar e Task Runner

Para entender melhor o que o Kiro Crew pode fazer, leia o post conceitual:

O que é o Kiro Crew — O que é o Kiro Crew e quando usar

E para comparar com outras opções de agentes:

Kiro IDE e CLI — Guia do Kiro IDE e CLI
Claude Code — Claude Code como alternativa

Baseado na documentação oficial e experiência prática de deploy. Testado em agosto de 2026 com Coolify v4.x e Kiro Crew latest.