Como hospedar o KiroCrew num VPS com Docker

Por que hospedar o KiroCrew num VPS em vez de num laptop

Hospedar o KiroCrew só compensa numa máquina que nunca entra em suspensão. Por isso, um VPS é o local adequado e um laptop não é. O KiroCrew mantém no disco o histórico das sessões, a memória semântica, as tarefas agendadas e a fila de aprovações. Recarrega tudo quando o processo reinicia. Nada disso ajuda se o processo não estiver em execução às 03:00, quando uma tarefa agendada deve ser executada. Um laptop fechado não está a executar o processo.

O KiroCrew é um workspace de agentes open source da equipa Kiro, licenciado ao abrigo da Apache 2.0. As primeiras versões públicas foram lançadas no início de agosto de 2026. Um processo, chamado gateway, gere o estado e disponibiliza um dashboard web na porta 5476. Pode aceder ao gateway a partir do dashboard, da CLI kirocrew ou de um canal de chat, como o Slack. O gateway é o único componente que vai hospedar por conta própria. Por isso, este guia explica como mantê-lo em execução, como impedir o acesso a partir da Internet pública e como restaurá-lo depois de uma atualização problemática.

Há duas coisas que deve saber antes de começar. O KiroCrew utiliza kiro-cli, que requer um início de sessão único com uma conta Kiro. A inferência dos agentes é faturada num plano Kiro. Assim, em agosto de 2026, esta não é uma configuração offline. O projeto também só tem algumas semanas. Parta do princípio de que terá de reverter uma atualização em algum momento e instale-o de modo a permitir essa reversão. Se nunca executou um agente num servidor, executar um agente de programação num VPS explica os princípios em que este guia se baseia.

O que o KiroCrew precisa e onde o estado fica

Uma instalação nativa precisa de Python 3.10 ou mais recente (o projeto recomenda 3.12), de Node.js 18 ou mais recente se compilar o dashboard a partir do código-fonte e de kiro-cli, que a primeira inicialização instala e configura para iniciar sessão. A instalação num contentor não precisa de nada disso no host. Precisa de Docker. Essa é a principal razão para a preferir.

O estado fica em ~/.kiro/crew, e a variável de ambiente KIROCREW_HOME permite movê-lo para outro local. Conteúdo desse diretório:

• config.json: definições do gateway e credenciais dos canais de chat.
• .env: segredos.
• workspace/memory/: preferências, notas de projeto e histórico de chat.
• memory.db e memory_index.db: os índices semântico e de texto integral.
• models/: o modelo de embeddings, descarregado na primeira execução.
• gateway.log e security_events.jsonl: o log de execução e o log de eventos de segurança.

Esse diretório é a instalação. Copie-o para um novo VPS e terá movido o seu agente. Por isso, a secção de backup abaixo é mais importante do que a secção de instalação.

Planeie o espaço em disco, não a RAM. O gateway é um processo Python. O que realmente carrega o sistema é aquilo que o agente executa, como uma compilação ou uma suite de testes. O diretório de estado cresce com o histórico de chat, e o modelo de embeddings é descarregado na primeira inicialização. Por isso, meça o espaço no seu próprio sistema com du -sh ~/.kiro/crew depois de algumas semanas, em vez de confiar em qualquer valor publicado no primeiro mês de um projeto.

Qual dos três métodos de instalação deve usar

O projeto disponibiliza três métodos. O instalador de uma linha transfere um wheel e coloca kirocrew no seu PATH:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh

O instalador aceita uma flag de canal e uma flag de versão:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --channel insider
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --version 0.1.3

A imagem de container é publicada em ghcr.io/kirodotdev/kirocrew, para linux/amd64 e linux/arm64 em todas as tags. A compilação a partir do código-fonte requer git clone e make build e destina-se a quem altera o código, não a quem o executa.

Use o container. Uma instalação nativa coloca pacotes Python, Node e kiro-cli no mesmo host que executa os seus outros serviços. Assim, se uma atualização correr mal, terá de desfazer essas alterações manualmente. O container mantém o runtime numa única imagem e o estado num único volume. Isso transforma um rollback numa alteração de tag seguida de um reinício.

Fixe a imagem numa tag de release, não em stable

O exemplo do próprio projeto usa a tag stable:

docker run -d --name kirocrew \
  -p 127.0.0.1:5476:5476 \
  -v kirocrew-home:/home/kirocrew \
  ghcr.io/kirodotdev/kirocrew:stable

stable é uma tag móvel. Aponta para a release estável mais recente disponível, por isso o próximo pull pode alterar a versão em execução sem que essa decisão seja sua. Além disso, a tag não regista qual era essa versão. As tags de versão são imutáveis, por isso fixe uma. A release mais recente em 6 August 2026 é 0.1.3, publicada em 5 August 2026. Também existe a tag nightly. Num projeto tão recente, isso significa que o código foi alterado esta manhã.

Escreva /opt/kirocrew/compose.yaml:

services:
  kirocrew:
    image: ghcr.io/kirodotdev/kirocrew:0.1.3
    container_name: kirocrew
    restart: unless-stopped
    ports:
      - "127.0.0.1:5476:5476"
    volumes:
      - kirocrew-home:/home/kirocrew

volumes:
  kirocrew-home:

Inicie o contentor e, em seguida, verifique o endpoint de estado que a própria imagem também utiliza para o seu HEALTHCHECK:

cd /opt/kirocrew
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:5476/api/health

docker compose ps deve indicar que o contentor está saudável ao fim de cerca de um minuto. /api/health responde sem token, tal como /api/live e /api/ready, o que permite utilizá-los como sondas. Se o estado permanecer em starting, leia docker logs kirocrew antes de alterar qualquer coisa. A primeira execução descarrega o modelo de embeddings, por isso uma ligação lenta torna o primeiro arranque demorado.

Mantenha-o em execução com systemd

restart: unless-stopped reinicia o container depois de uma falha e de um reboot, desde que o próprio Docker arranque no boot. Um ficheiro de unidade torna essa dependência explícita e fornece um único comando para parar toda a stack antes de uma cópia de segurança. Iniciar uma stack Docker Compose no boot explica o padrão geral. Esta é a estrutura usada pelo KiroCrew, em /etc/systemd/system/kirocrew.service:

[Unit]
Description=KiroCrew gateway
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/kirocrew
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now kirocrew
systemctl status kirocrew

systemctl status kirocrew deve apresentar active (exited), que é o resultado normal para esta unidade. Type=oneshot com RemainAfterExit=yes está correto neste caso porque docker compose up -d termina assim que o container é iniciado: o systemd acompanha o estado de execução da stack, e não um processo em primeiro plano. Se escrever Type=simple, o systemd vê o comando terminar imediatamente, marca o serviço como parado e depois desiste ou entra num ciclo de reinícios, dependendo da sua configuração Restart=. Numa instalação nativa, o projeto fornece o equivalente, kirocrew service install, que escreve /etc/systemd/system/kirocrew.service e executa o gateway com o seu utilizador. Não execute as duas unidades. A versão mais abrangente deste tema está em serviços e temporizadores systemd numa VPS.

Primeira execução: autentique-se e obtenha um token do dashboard

O container inicia o gateway, mas o runtime do agente ainda não está autenticado. Autentique-se dentro do container:

docker exec -it kirocrew kiro-cli login

O comando mostra um código do dispositivo e um URL que deve abrir no seu próprio browser. Em seguida, gere um token do dashboard:

docker exec kirocrew kirocrew token --ttl 2h

O URL do dashboard é http://localhost:5476/?token=<the token>. Os tokens expiram: as sessões têm uma duração predefinida de uma hora e o máximo documentado é de vinte horas. Se o dashboard carregar em branco ou o redirecionar imediatamente para fora, normalmente o token expirou. Gere outro token. Nunca cole um token num ticket ou numa mensagem de chat, porque quem o tiver controla o seu agente.

Aceda ao dashboard por SSH e nunca publique a porta 5476

Consulte novamente o endereço de bind no exemplo do projeto: -p 127.0.0.1:5476:5476. Dentro do contentor, o gateway escuta em 0.0.0.0, porque tem de estar acessível através do mapeamento de portas, mas o próprio mapeamento publica apenas na interface de loopback do host. Remova o prefixo 127.0.0.1: e o gateway ficará acessível na Internet pública para qualquer pessoa que faça uma varredura dessa porta. Uma regra de firewall também não o protegerá: o Docker publica portas através de regras DNAT avaliadas antes da filtragem do ufw, por isso ufw deny 5476 não tem efeito numa porta publicada. Portas do Docker que ignoram o ufw explica esse mecanismo.

Encaminhe a porta por SSH a partir do seu portátil:

ssh -N -L 5476:127.0.0.1:5476 you@your-server.example.com

Deixe esse processo em execução e abra http://localhost:5476/?token=<the token> localmente. Para tornar o encaminhamento automático em todas as ligações, coloque-o em ~/.ssh/config:

Host your-server.example.com
    LocalForward 5476 127.0.0.1:5476

Se a porta 5476 já estiver a ser utilizada no seu portátil, altere apenas o número do lado esquerdo: ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com e aceda depois a http://localhost:45476/?token=....

Há um comportamento documentado a considerar num túnel: o gateway interpreta os pedidos encaminhados como remotos, por isso os endpoints de escrita da configuração e revelação de segredos no dashboard recusam esses pedidos. Uma alteração de definições que não seja guardada através de SSH apresenta este comportamento por conceção, não é um erro. Edite a configuração diretamente no host:

docker cp kirocrew:/home/kirocrew/.kiro/crew/config.json .
# edit config.json here
docker cp config.json kirocrew:/home/kirocrew/.kiro/crew/config.json
docker exec -u 0 kirocrew chown kirocrew:kirocrew /home/kirocrew/.kiro/crew/config.json
docker restart kirocrew

Para aceder pelo telemóvel, o projeto indica tailscale serve da Tailscale, que mantém o dashboard dentro da sua própria tailnet, em vez de o expor num hostname público. Prefira esta opção a um reverse proxy público. O token é transmitido no URL, e um URL é escrito em todos os logs de acesso existentes no caminho do pedido.

Reduza tanto quanto possível o raio de impacto do agente

O contentor verifica se existe suporte para sandbox no primeiro arranque. O resultado determina se os agentes podem executar alguma coisa. Se o isolamento de namespaces estiver disponível, os subprocessos do agente são executados de forma isolada. Se não estiver disponível e KIROCREW_ALLOW_UNSANDBOXED=1 não estiver definido, a execução é recusada em vez de ser feita sem isolamento. Por isso, quando o gateway parece saudável, mas todas as tarefas ficam bloqueadas, esta é normalmente a causa. A decisão fica registada em docker logs kirocrew nessa primeira execução. O projeto também publica um perfil seccomp (secure computing mode) que pode aplicar:

curl -fsSL https://raw.githubusercontent.com/kirodotdev/KiroCrew/main/docker/seccomp/kirocrew-seccomp.json \
  -o /opt/kirocrew/kirocrew-seccomp.json

    security_opt:
      - seccomp:./kirocrew-seccomp.json

Se definir KIROCREW_ALLOW_UNSANDBOXED=1, deixe claro o que mudou: o contentor passa a ser a única barreira entre o agente e o servidor. O aviso do projeto merece ser repetido na íntegra. Não monte caminhos do host que não entregaria diretamente ao agente. Na prática, isso exclui o socket do Docker, qualquer bind mount de / e qualquer diretório que contenha dados de outro serviço.

O restante é a estrutura aplicável a todos os agentes autorizados a executar comandos. Limite as credenciais ao único repositório ou bucket de que o agente precisa. Nunca use um token pessoal com permissões para toda a conta. Execute-o como um utilizador dedicado cujo diretório pessoal não contenha mais nada. É esse o objetivo de utilizadores com privilégio mínimo num VPS. Quando o agente escreve código e depois executa esse código, forneça-lhe uma máquina que possa avariar: uma VM descartável para agentes de programação é uma barreira mais forte do que qualquer flag neste ficheiro compose, porque pode eliminá-la em vez de a limpar. O mesmo princípio orienta executar o OpenClaw com segurança num VPS e alojar o agente Hermes num VPS. O trabalho agendado também gera custos enquanto dorme, porque a inferência é faturada no seu plano Kiro. Por isso, defina os limites descritos em controlar o custo de um agente de IA num VPS antes de adicionar uma tarefa noturna.

Faça backup do volume de estado antes de cada atualização

Primeiro, descubra o nome real do volume. O Compose prefixa os volumes nomeados com o nome do projeto, que por padrão é o nome do diretório. Por isso, o volume declarado como kirocrew-home em /opt/kirocrew/compose.yaml é criado como kirocrew_kirocrew-home:

docker volume ls

Pare o gateway antes de copiar qualquer coisa. memory.db e memory_index.db são bancos de dados SQLite, e copiar um banco de dados enquanto ele está a ser gravado pode capturar uma transação incompleta, que será restaurada como um ficheiro corrompido. As próprias instruções de migração do projeto dizem o mesmo: mova a memória apenas quando os gateways estiverem parados.

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data:ro -v "$PWD":/backup \
  alpine tar czf /backup/kirocrew-2026-08-06.tgz -C /data .
sudo systemctl start kirocrew

Copie o arquivo para fora do servidor. A restauração usa o mesmo comando, com o contentor parado e tar xzf no lugar de tar czf:

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data -v "$PWD":/backup \
  alpine tar xzf /backup/kirocrew-2026-08-06.tgz -C /data
sudo systemctl start kirocrew

Migrar para um novo host é diferente de restaurar no mesmo host, e o projeto especifica como proceder. O histórico de conversas e as notas do projeto em workspace/memory/ são transferidos, assim como os dois ficheiros de banco de dados e config.json. Os ficheiros PID, o log de eventos de segurança e .env estão associados ao host antigo. Não os transfira e introduza novamente os segredos no novo servidor.

Como reverter uma atualização problemática

A atualização é rápida e só é segura porque fixou uma versão. Faça primeiro o backup e, em seguida, altere a tag:

sudo systemctl stop kirocrew
# take the backup here, as above
sudo nano /opt/kirocrew/compose.yaml   # set the new image tag
sudo systemctl start kirocrew
docker compose -f /opt/kirocrew/compose.yaml ps
curl -s http://127.0.0.1:5476/api/health

docker compose up -d faz o pull da imagem se ela ainda não estiver no servidor, portanto editar a tag conclui toda a atualização. A reversão segue a mesma sequência, usando o número antigo, e fornece exatamente a imagem usada antes, porque as tags de versão são imutáveis.

O binário é revertido sem problemas. O estado é a parte que pode não ser. Um gateway mais recente pode reescrever config.json ou migrar os bancos de dados em memória para um formato que um gateway mais antigo não consegue ler, e não existe um procedimento de downgrade documentado em agosto de 2026. Portanto, se a imagem antiga iniciar e depois apresentar um comportamento estranho, não faça a depuração. Pare o serviço, restaure o backup feito antes da atualização e inicie novamente. Essa é a razão para fazer o backup primeiro e também explica por que o hábito de atualizar agora e fazer backup depois falha num projeto tão recente.

O que não está comprovado aqui

Seja realista quanto à idade deste software. A versão 0.1.3 tem poucos dias na data de redação deste texto, as notas de versão são links automatizados para changelogs, e ainda não existe um histórico de atualizações. Nada neste guia representa um resultado de longo prazo. Por isso, trate o crescimento da memória, o tamanho da base de dados e a fiabilidade do agendador como aspetos que deve medir no seu próprio servidor, não como comportamentos garantidos.

Há dois comportamentos que deve testar antes de depender deles. Primeiro, verifique se uma versão anterior consegue ler o estado gravado por uma versão mais recente. Faça o teste numa cópia do volume, enquanto isso ainda não tiver impacto, e não durante uma indisponibilidade. Segundo, verifique o que o gateway faz quando a sessão de início de sessão do Kiro expira no momento em que uma tarefa agendada deve ser executada. Ambos são o tipo de limitação que um projeto recente pode corrigir silenciosamente entre versões. Também são fáceis de verificar agora.

FAQ

Por que o dashboard do KiroCrew não abre no IP público do meu servidor?

Porque o exemplo publicado associa a porta ao loopback. -p 127.0.0.1:5476:5476 associa a porta do container apenas ao endereço de loopback do host, de forma deliberada. Aceda-lhe através do encaminhamento da porta por SSH com ssh -N -L 5476:127.0.0.1:5476 you@your-server e abra http://localhost:5476/?token=<token> no seu portátil. Remover o prefixo 127.0.0.1: para o tornar acessível coloca o gateway na Internet pública, e uma regra de firewall não o irá conter, porque as regras DNAT de portas publicadas pelo Docker são avaliadas antes de o ufw filtrar o tráfego.

Onde é que o KiroCrew armazena os dados e o que devo salvaguardar?

Tudo fica em ~/.kiro/crew, que corresponde a /home/kirocrew/.kiro/crew dentro da imagem do container, e KIROCREW_HOME permite relocalizá-lo. Faça uma cópia de segurança de todo o diretório ou de todo o volume Docker, com o gateway parado. memory.db e memory_index.db são bases de dados SQLite, por isso uma cópia feita enquanto o gateway está a escrever pode ficar inconsistente. Ao migrar para um novo host, workspace/memory/, os dois ficheiros de base de dados e config.json são transferidos, enquanto os ficheiros PID, o registo de eventos de segurança e .env pertencem ao host antigo.

Devo usar a tag stable ou uma tag de versão?

Use uma tag de versão. stable muda sempre que é lançada uma versão, por isso a versão em execução pode mudar na próxima extração, e a própria tag não informa sobre o que está em execução. As tags de versão, como 0.1.3, são imutáveis. É isso que permite fazer um rollback: repõe o número antigo e obtém a mesma imagem. Em 6 de agosto de 2026, a versão mais recente é 0.1.3.

Por que o meu agente se recusa a executar comandos?

O container verifica se existe suporte para sandbox no primeiro arranque. Se não conseguir isolar os subprocessos do agente e KIROCREW_ALLOW_UNSANDBOXED=1 não estiver definido, recusa-se a executá-los em vez de os executar sem isolamento. Assim, o gateway parece estar saudável enquanto todas as tarefas ficam bloqueadas. docker logs kirocrew mostra a decisão relativa à sandbox tomada nessa primeira execução. Definir a variável faz do container a única barreira entre o agente e o host. Por isso, se a definir, não monte nada que não entregasse diretamente ao agente.

Preciso de uma conta Kiro para alojar o KiroCrew?

Sim, em agosto de 2026. O KiroCrew é software livre ao abrigo da Apache 2.0, mas utiliza kiro-cli, que requer uma autenticação única, e a inferência do agente é faturada num plano Kiro. No container, execute docker exec -it kirocrew kiro-cli login e aprove o código do dispositivo no navegador. Até essa autenticação ser concluída, o gateway arranca e o dashboard carrega, mas o agente não tem nenhum modelo com o qual comunicar.