# Como Instalar o Kiro Crew no Coolify com Telegram

> Tutorial passo a passo para rodar o Kiro Crew como container no Coolify, com integração Telegram para acessar seu agente de qualquer lugar.

Source: https://agentify.ia.br/blog/kiro-crew-coolify/

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

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=

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

# 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

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

### 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

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 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](/blog/guias/kiro-crew) — O que é o Kiro Crew e quando usar

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

- [Kiro IDE e CLI](/blog/guias/kiro-ide-cli) — Guia do Kiro IDE e CLI

- [Claude Code](/blog/guias/claude-code) — Claude Code como alternativa

---

*Baseado na [documentação oficial](https://github.com/kirodotdev/KiroCrew/blob/main/docs/guides/remote-and-mobile.md) e experiência prática de deploy. Testado em agosto de 2026 com Coolify v4.x e Kiro Crew latest.*

-->