Hospede o KiroCrew num VPS com Docker e systemd

Por que hospedar o KiroCrew num VPS em vez de num portátil

Hospedar o KiroCrew por conta própria só compensa numa máquina que nunca entra em suspensão. Por isso, um VPS é o local adequado, mas um portátil 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. Volta a carregar 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 portátil fechado não está em execução.

O KiroCrew é um workspace de agentes de código aberto da equipa Kiro, licenciado sob Apache 2.0. As primeiras releases públicas foram disponibilizadas no início de August 2026. Um único processo, chamado gateway, gere o estado e disponibiliza um dashboard Web na porta 5476. Pode aceder a esse gateway através do dashboard, da CLI kirocrew ou de um canal de chat, como Slack. O gateway é o único componente que vai hospedar por conta própria. Por isso, este guia explica como mantê-lo em execução, mantê-lo fora da Internet pública e 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. Por isso, em August 2026, esta não é uma configuração offline. O projeto também tem apenas algumas semanas. Conte com a possibilidade de ter de fazer rollback e instale-o de forma a permitir essa operação. Se nunca executou um agente num servidor, executar um agente de código num VPS aborda as regras básicas em que este guia se baseia. Se a parte dos agentes for mais recente para si do que a administração de servidores, comece por aprender o que são realmente um ciclo de agente, as respetivas ferramentas e a sua memória. Assim, as opções abaixo serão entendidas como decisões, e não como comandos sem contexto.

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 o dashboard for compilado a partir do código-fonte e de kiro-cli, que a primeira inicialização instala e autentica por si. A instalação num container não precisa de nada disso no host. Precisa de Docker. Essa é a principal razão para preferi-la.

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 do projeto e histórico de chat.
• memory.db e memory_index.db: os índices semântico e de texto completo.
• models/: o modelo de embeddings, transferido 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á transferido 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 é transferido na primeira inicialização. Por isso, meça o consumo no seu próprio sistema com du -sh ~/.kiro/crew depois de algumas semanas, em vez de confiar num valor publicado durante o primeiro mês de um projeto. Compare isso com um runtime que atribui a cada worker o seu próprio container e o seu próprio browser, em que alojar os colegas de trabalho de IA do OpenBot torna o dimensionamento uma questão de RAM antes de ser uma questão de disco.

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

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

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

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 contentor é 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 contentor. Uma instalação nativa coloca pacotes Python, Node e kiro-cli no mesmo host que executa os seus outros serviços. Se uma atualização correr mal, terá de corrigir a situação manualmente. O contentor mantém o runtime numa imagem e o estado num volume. Assim, um rollback consiste em alterar a tag e reiniciar.

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 sempre para a release estável mais recente, pelo que o próximo pull pode alterar a versão em execução sem que a escolha tenha sido sua. A tag também não regista qual era essa versão. As tags de versão são imutáveis, por isso fixe uma delas. A release mais recente em 6 August 2026 é 0.1.3, publicada em 5 August 2026. Existe também uma tag nightly. Num projeto tão recente, isso significa que o código mudou 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 verifique o endpoint de estado que a imagem também usa no seu próprio 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 dentro de cerca de um minuto. /api/health responde sem token, tal como /api/live e /api/ready. É isso que permite usá-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, pelo que uma ligação lenta torna o primeiro arranque demorado.

Mantenha-o em execução com systemd

restart: unless-stopped reinicia o contentor após uma falha e depois 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. Arrancar 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 esperado para esta unidade. Type=oneshot com RemainAfterExit=yes está correto neste caso porque docker compose up -d termina assim que o contentor arranca: o systemd acompanha o estado de execução da stack, não um processo em primeiro plano. Se escrever Type=simple, o systemd vê o comando terminar imediatamente, marca o serviço como inativo e depois desiste ou entra num ciclo de reinícios, dependendo da configuração Restart=. Numa instalação nativa, o projeto fornece o equivalente próprio, 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 num VPS. Uma unidade que não volta a arrancar fica silenciosa se não a configurar para gerar alertas. Adicione um handler OnFailure= que envia um alerta para o seu próprio servidor ntfy e saberá pelo telefone que o gateway está inativo, em vez de descobrir através de uma tarefa agendada que nunca foi executada.

Primeira execução: iniciar sessão e obter um token do dashboard

O contentor inicia o gateway, mas o runtime do agente ainda não tem uma sessão iniciada. Inicie sessão dentro do contentor:

docker exec -it kirocrew kiro-cli login

Isto apresenta um código de dispositivo e um URL que deve abrir no seu próprio navegador. 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. 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 ser acessível através do mapeamento de portas, mas o próprio mapeamento publica a porta apenas na interface de loopback do host. Remova o prefixo 127.0.0.1: e o gateway ficará acessível na Internet pública a qualquer pessoa que faça uma varredura dessa porta. Uma regra de firewall também não o protegerá: o Docker publica portas escrevendo regras DNAT avaliadas antes da filtragem do ufw, pelo que ufw deny 5476 não tem efeito sobre uma 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 comando 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 usada 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, em seguida, aceda a http://localhost:45476/?token=.... Assim que um segundo agente partilhar o servidor, terá de empilhar encaminhamentos deste modo, porque alojar o open-kritt para análise de segurança coloca outro dashboard acessível apenas por loopback no mesmo servidor, na porta 5173.

Há um comportamento documentado a considerar ao usar um túnel: o gateway interpreta os pedidos encaminhados como remotos, pelo que os endpoints de escrita de configuração e revelação de segredos no dashboard os recusam. Se uma alteração de definições não for guardada através de SSH, este é o motivo; 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 acesso por telemóvel, o projeto aponta para o tailscale serve da Tailscale, que mantém o painel dentro da sua própria tailnet em vez de o publicar num hostname público. Prefira essa opção a um reverse proxy público. O token segue no URL, e um URL é registado em todos os logs de acesso no caminho que percorre. Essa regra diz respeito ao que está por trás da porta, não à porta em si: algo como Halcyon, que reconstrói uma biblioteca Jellyfin como uma videolocadora navegável dos anos 90 existe para ser aberto por outras pessoas e é um candidato adequado a um reverse proxy, enquanto um gateway que pode executar comandos no seu servidor não é.

Dê ao agente o menor raio de impacto possível

O contentor verifica se há suporte para sandbox no primeiro arranque, e 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, um gateway que parece saudável enquanto todas as tarefas ficam bloqueadas geralmente está nesta situação. 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. Vale a pena repetir integralmente o aviso do projeto. 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 direitos sobre toda a conta. Execute-o como um utilizador dedicado cujo diretório pessoal não contenha mais nada. É para isso que serve usar utilizadores com privilégios mínimos num VPS. Quando o agente escreve código e depois executa esse código, dê-lhe uma máquina que possa ser danificada: 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. As ferramentas também fazem parte do raio de impacto: dar ao agente acesso à pesquisa na Web transforma cada página obtida em entrada não confiável. Por isso, ligá-lo à sua própria instância do SearXNG é uma decisão sobre injeção de prompts tanto quanto sobre configuração técnica. As tarefas agendadas também gastam dinheiro enquanto dorme, porque a inferência é faturada no seu plano Kiro. Defina os limites descritos em controlar o custo de um agente de IA num VPS antes de adicionar uma tarefa noturna.

Faça uma cópia de segurança do volume de estado antes de cada atualização

Primeiro, encontre o nome real do volume. O Compose acrescenta o nome do projeto aos volumes nomeados. Por padrão, esse nome é 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 bases de dados SQLite. Copiar uma base de dados enquanto está a ser escrita 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. Esta regra de parar primeiro não é específica do KiroCrew. Se um servidor de fotografias partilhar o mesmo host, a comparação entre PhotoPrism e Immich apresenta os comandos de cópia de segurança exatos de que cada um precisa.

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 host. 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

A migração para um novo host é diferente de uma restauração no mesmo host, e o projeto especifica esse procedimento. O histórico de conversas e as notas do projeto em workspace/memory/ são transferidos, assim como os dois ficheiros de base de dados e config.json. Os ficheiros PID, o registo de eventos de segurança e .env estão associados ao host antigo. Não os transfira e introduza novamente os segredos no novo host.

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 baixa a imagem se ela ainda não estiver no servidor. Portanto, editar a tag é toda a atualização. A reversão segue a mesma sequência, usando o número antigo. Assim, obtém exatamente a imagem que tinha antes, porque as tags de versão são imutáveis.

O binário reverte sem problemas. O estado é a parte que pode não reverter. Um gateway mais recente pode reescrever config.json ou migrar as bases de dados em memória para um formato que um gateway mais antigo não consegue ler. Em agosto de 2026, não existe um procedimento de downgrade documentado. Portanto, se a imagem antiga iniciar e depois apresentar um comportamento estranho, não tente depurá-la. Pare-a, restaure o backup feito antes da atualização e inicie novamente. Essa é a razão para fazer o backup primeiro. É também por isso que atualizar agora e fazer o 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 à data de redação, as respetivas notas de versão são ligações automatizadas para changelogs e não notas de migração, e ainda não existe histórico de atualizações. Nada neste guia é 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 a medir no seu próprio servidor, e não como comportamentos garantidos.

Há dois comportamentos que deve testar antes de depender deles. Primeiro, confirme 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, quando isso ainda não tiver impacto, e não durante uma indisponibilidade. Segundo, confirme o que o gateway faz quando o início de sessão no Kiro expira enquanto há um job agendado para ser executado. Ambos são exemplos de limitações que um projeto recente pode corrigir discretamente entre versões. Ambos 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 contentor apenas ao endereço de loopback do host, de forma deliberada. Aceda a ela 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 tornar a porta acessível expõe o gateway à Internet pública. Uma regra de firewall não o consegue conter, porque as regras DNAT de portas publicadas pelo Docker são avaliadas antes de o ufw filtrar o tráfego.

Onde o KiroCrew armazena os dados e do que devo fazer backup?

Tudo fica em ~/.kiro/crew, que corresponde a /home/kirocrew/.kiro/crew dentro da imagem do contentor, e KIROCREW_HOME permite relocalizá-lo. Faça backup do diretório completo ou do volume Docker completo, 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 escreve 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 log 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 é publicada uma release, por isso a versão em execução pode mudar no próximo pull, e a própria tag não indica o que está em execução. Tags de versão como 0.1.3 são imutáveis. É isso que permite fazer rollback: repõe o número antigo e obtém a imagem idêntica. Em 6 August 2026, a release mais recente é 0.1.3.

Por que o meu agente se recusa a executar comandos?

O contentor verifica o suporte de 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 saudável enquanto todas as tarefas ficam bloqueadas. docker logs kirocrew mostra a decisão sobre o sandbox tomada nessa primeira execução. Definir a variável faz do contentor a única barreira entre o agente e o host. Se a definir, não monte nada que não entregaria diretamente ao agente.

Preciso de uma conta Kiro para alojar o KiroCrew?

Sim, em August 2026. O KiroCrew é software livre sob a licença Apache 2.0, mas utiliza kiro-cli, que exige um início de sessão único, e a inferência do agente é faturada num plano Kiro. No contentor, execute docker exec -it kirocrew kiro-cli login e aprove o código do dispositivo no navegador. Até esse início de sessão ser concluído, o gateway arranca e o dashboard é carregado, mas o agente não tem nenhum modelo com o qual comunicar.