Como hospedar o Rakazo: bot de IA em VPS

O que o Rakazo self-hosted executa de facto

Fazer self-hosting do Rakazo significa executar cinco componentes num único servidor Linux: PostgreSQL, um processo Graphile Worker, a API, a aplicação web e um contentor sandbox para cada bot ativo. O Rakazo é uma alternativa open source ao Grok Bot, publicada por elie222 ao abrigo da licença Apache 2.0. Cada bot tem o seu próprio thread, o seu próprio computador, a sua própria memória e o seu próprio histórico. Também pode criar peers ou subagentes de curta duração.

Esta última parte é o motivo pelo qual deve ser executado num VPS (virtual private server), e não num desktop. Um bot que mantém memória e executa tarefas agendadas tem de estar acessível enquanto dorme. Um portátil que entra em suspensão interrompe a fila.

Em agosto de 2026, o Rakazo ainda está numa fase beta inicial. Por isso, trate este procedimento como uma configuração funcional, e não como um appliance concluído. Toda a stack usa TypeScript: React 19 e Vite para a aplicação web, Hono para a API, Postgres com Prisma, Better Auth para as contas e Graphile Worker para os trabalhos em segundo plano. O Graphile Worker armazena a fila dentro do Postgres. Por isso, não é necessário executar Redis nem um segundo armazenamento de dados. .env.example define WAKEUP_DRIVER=graphile, o que significa que o despertar de um bot é um trabalho suportado pelo Postgres. Se parar o Postgres, todas as ações agendadas dos bots também param. Se preferir montar um agente a partir de componentes, em vez de executar o produto de outra pessoa, criar o seu próprio agente a partir de componentes é a outra opção.

Por que um plano de 1 GB não será suficiente

Conte os processos. O Postgres é um. A API é um processo Node. O worker é um segundo. A aplicação Web é um terceiro. O supervisor do sandbox é um quarto. Depois, cada bot em execução recebe um container com um desktop Linux gráfico e um browser.

A documentação de instalação do próprio projeto fornece um valor honesto: uma máquina com 2 vCPU e 4 GB é suficiente para a API, o worker e o Postgres quando a E2B gere os desktops dos bots. Esse valor aplica-se apenas ao control plane, com a parte pesada alojada noutro local. Defina SANDBOX_PROVIDER=docker e esses desktops passam para o seu VPS, portanto 4 GB torna-se o mínimo, e não o objetivo. Comece com 8 GB se pretende manter mais de um bot ativo e meça o valor real com docker stats enquanto um bot trabalha. O browser dentro do sandbox é o que aumenta o consumo de memória, por isso uma folha de especificações não lhe dará a resposta. Para conhecer o método geral de dimensionamento de uma máquina para trabalho com agentes, quanto de RAM e CPU um VPS para agentes realmente precisa explica a medição em detalhe.

Uma configuração impede que isto piore. .env.example inclui SANDBOX_IDLE_MS=600000 com o comentário de que pausa os computadores E2B, ou para os computadores Docker, depois desse número de milissegundos de inatividade. Após dez minutos sem atividade, o computador é removido. O valor mínimo aceite é 30000. Sem essa configuração, cada bot que abrisse manteria memória ocupada indefinidamente.

O disco também conta. A imagem do sandbox, os módulos Node e o volume do Postgres partilham o mesmo disco, por isso 40 GB é um ponto de partida razoável.

Fixe uma versão antes de clonar

O Rakazo evolui rapidamente e main não é uma versão. Em 16 August 2026, o repositório tinha exatamente uma tag, v0.1.0-beta, publicada em 13 August 2026 e marcada como pré-lançamento.

git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb
git log -1 --format='%H %ci'

Esse é o commit apontado por v0.1.0-beta. Fixe o commit, não o branch nem a tag. Um branch muda no próximo git pull, e uma tag é um rótulo móvel que um maintainer pode apontar para outro commit. Portanto, nenhum dos dois identifica uma árvore à qual possa regressar. Um identificador de commit não muda. Registe o seu junto dos restantes dados do servidor, porque, quando uma atualização causa problemas, a correção mais simples é git checkout <old commit> e reconstruir o sistema. Isso só funciona se souber qual era o commit funcional.

Requisitos: Node 22, pnpm 9 e Docker

node -v
pnpm -v
docker --version

package.json declara "engines": { "node": ">=22" } e "packageManager": "pnpm@9.15.0", por isso node -v tem de apresentar v22 ou superior. O pacote Node no repositório do Ubuntu é normalmente mais antigo, por isso instale a partir do NodeSource ou do nvm. O pnpm vem com o Node através do corepack:

corepack enable
corepack prepare pnpm@9.15.0 --activate

O Docker Engine e o plugin compose cobrem o restante, e o seu utilizador tem de conseguir aceder ao daemon. Se docker ps responder permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, adicione o seu utilizador ao grupo docker e abra uma nova shell de início de sessão. Saiba primeiro o que isso permite: pertencer ao grupo docker equivale a ter root na máquina, porque qualquer pessoa nesse grupo pode iniciar um contentor que monte o sistema de ficheiros do host.

Configure o .env e inicie o Postgres

cp .env.example .env
chmod 600 .env

Dois valores têm de ser alterados antes de qualquer componente ficar exposto à rede. .env.example inclui BETTER_AUTH_SECRET=replace-with-32-plus-character-secret e ENCRYPTION_KEY=replace-with-64-char-hex-or-passphrase. O Rakazo rejeita esses valores de marcador fora do desenvolvimento. Assim, uma implementação parcialmente configurada falha de forma explícita em vez de funcionar com um segredo publicado no repositório.

openssl rand -base64 48
openssl rand -hex 32

Em seguida, inicie apenas a base de dados e execute as migrações.

docker compose --env-file .env -f infra/compose/docker-compose.yml up postgres -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:build

pnpm sandbox:build cria a imagem do computador do bot, definida em package.json como docker build -t rakazo/computer:local infra/sandboxes/computer. É uma imagem gráfica, por isso a primeira compilação transfere muitos dados e demora algum tempo. Confirme que foi criada com docker image ls rakazo/computer. O comando deve apresentar uma linha.

O ficheiro Compose publica o Postgres como 127.0.0.1:5433:5432, acessível apenas através do loopback. Mantenha essa configuração. As credenciais de desenvolvimento são rakazo:rakazo e estão no repositório. Uma porta do Postgres acessível pela Internet com uma palavra-passe publicada é encontrada por scanners em poucas horas. O ficheiro Compose de produção lê POSTGRES_PASSWORD. Defina esse valor como uma cadeia aleatória quando chegar a essa etapa.

A primeira execução

pnpm dev

Isto inicia quatro componentes: a API na porta 3100, o Graphile Worker, a aplicação web Vite na porta 5173 e o supervisor do sandbox na porta 7091. A aplicação fica disponível em http://127.0.0.1:5173 e deverá apresentar uma página de início de sessão.

Num VPS, não está junto dessa máquina e não deve publicar a porta 5173 para aceder à aplicação. Em vez disso, reencaminhe as portas através de SSH (secure shell) a partir da sua própria máquina.

ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-server

Tenha atenção à diferença entre as duas formas de execução. pnpm dev executa o Vite no host, associado apenas localmente. O serviço web do ficheiro Compose publica 5173:5173 em todas as interfaces. Se iniciar a stack completa de desenvolvimento num VPS público, a aplicação ficará exposta. Por isso, use o ficheiro de produção e o respetivo reverse proxy para tudo o que deixar em execução.

Qual provedor de sandbox é seguro num servidor?

Esta é a única configuração que precisa de ficar correta. SANDBOX_PROVIDER em .env aceita quatro valores.

• docker é o valor predefinido. Cada bot recebe o seu próprio contentor na sua máquina, criado a partir da imagem produzida por pnpm sandbox:build. É a configuração self-hosted mais rápida.
• e2b executa os computadores dos bots no E2B e requer E2B_API_KEY. O projeto recomenda esta opção para implementações públicas ou com vários utilizadores, porque mantém os computadores dos bots separados do host que executa a sua API e a sua base de dados.
• desktop executa os comandos do bot diretamente no host da API e do worker. A instrução do repositório é clara: não use esta opção num servidor público ou partilhado.
• fake é um emulador no processo para testes. Não é uma opção de runtime.

Leve esse aviso sobre o modo desktop à letra. No modo desktop não existe qualquer limite de isolamento. O bot executa comandos shell como o utilizador que executa o processo da API, com o diretório pessoal desse utilizador, as respetivas chaves SSH, as respetivas credenciais cloud e o respetivo .env. O texto de uma página Web que o bot lê transforma-se num comando no seu servidor. Usar o modo desktop num servidor é permitir que um bot fique com as suas credenciais. Use-o numa máquina à qual tenha acesso físico, ou não o use.

docker é um limite real, mas não perfeito. Um bot não consegue ler os ficheiros de outro bot, porque cada um tem o seu próprio contentor. No entanto, o supervisor que cria esses contentores monta /var/run/docker.sock, e controlar o socket Docker do host equivale a controlar o host. Por isso, mantenha o supervisor privado. .env.example documenta SANDBOX_SUPERVISOR_TOKEN como uma credencial de serviço opcional e separada, que usa BETTER_AUTH_SECRET quando fica vazia. Isto significa que deixar esse segredo com o valor de substituição protege o serviço que cria os contentores com uma string que qualquer pessoa pode ler no GitHub. Defina ambos os valores. Para obter a separação mais forte disponível aqui, use e2b ou atribua ao Rakazo uma máquina que não contenha mais nada. É o mesmo princípio de executar agentes de programação numa VM descartável: a forma mais barata de sobreviver a uma ação incorreta de um agente é garantir que a máquina dele não tem qualquer valor.

Onde ficam as chaves de API dos modelos?

O Rakazo não gere a faturação dos modelos. Tem de fornecer a chave. .env.example define PI_DEFAULT_PROVIDER=openrouter, por isso OPENROUTER_API_KEY é o local habitual, e as chaves dos fornecedores funcionam através da mesma definição.

Mantenha a chave em .env e fora de qualquer ficheiro que seja incluído num commit. Ambos os comandos compose no repositório passam --env-file .env, para que os valores cheguem aos contentores sem nunca serem escritos em YAML rastreado pelo git. Também pode deixar OPENROUTER_API_KEY vazio e colar uma chave na aplicação durante a configuração inicial. Este é mais um motivo para ENCRYPTION_KEY receber um valor aleatório real, em vez do marcador de posição fornecido.

Defina um limite de gastos para a chave no fornecedor antes de qualquer bot a utilizar. Um bot que entra num ciclo continua a gerar custos, e um limite por chave é a única paragem que não depende de monitorização. Dê um nome próprio a esta chave para poder revogá-la isoladamente.

Passar do modo de desenvolvimento para uma configuração que pode ficar em execução

O repositório inclui um ficheiro Compose de produção que executa Postgres, a API, o worker, a aplicação web e o Caddy para obter automaticamente certificados TLS (segurança da camada de transporte). Ele espera que o E2B forneça os computadores do bot.

sudo DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml up -d --build

harden-host.sh desativa o início de sessão SSH com palavra-passe, configura regras do UFW (firewall descomplicado) para SSH, HTTP e HTTPS, ativa o fail2ban e aplica perfis AppArmor. Leia-o antes de o executar, porque ele altera a forma como inicia sessão. Mantenha uma segunda sessão SSH aberta enquanto ele é executado.

O .env de produção precisa de mais definições do que o de desenvolvimento. A documentação de instalação autónoma lista este mínimo.

NODE_ENV=production
RAKAZO_HOST=app.example.com
BETTER_AUTH_URL=https://app.example.com
WEB_ORIGIN=https://app.example.com
API_URL=https://app.example.com
POSTGRES_PASSWORD=<random>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
DATA_DIR=/data

Aponte um registo A para o servidor antes desse primeiro up. O Caddy solicita um certificado para o nome em RAKAZO_HOST, e o pedido falha se o nome não resolver para este servidor ou se a porta 80 estiver fechada para o exterior.

Defina também SIGNUP_ALLOWLIST=you@example.com. SIGNUPS_ENABLED=true é o valor predefinido. Assim, uma instância com um nome público aceita registos de qualquer pessoa que a encontre, e cada conta nova recebe um computador. Configure primeiro uma allowlist. Pode alargar o acesso mais tarde, se quiser.

Considere docs/self-host.md no repositório como a fonte de autoridade para as definições de produção, porque ele muda com o código e este guia não é atualizado com essas alterações. Como o Compose executa o trabalho, aplicam-se as regras habituais, e os conceitos básicos do Docker Compose para um VPS explicam por que --env-file e os volumes nomeados se tornam mais importantes quando uma stack fica sem intervenção durante meses.

Cópias de segurança

O Postgres e o diretório data/ constituem a instância completa.

./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMP

backup.sh despeja o Postgres e arquiva data/. Numa máquina da qual depende, instale infra/compose/backup-prod.sh como /usr/local/sbin/rakazo-backup com o temporizador fornecido pelo repositório, para que a rotação ocorra automaticamente. Uma cópia de segurança armazenada no mesmo disco que a base de dados não é uma cópia de segurança, por isso copie-a para fora da máquina. Depois, restaure-a uma vez num servidor sobressalente, antes de precisar dela.

Por que falha e o que será apresentado

pnpm db:migrate não consegue aceder à base de dados. A migração indica que não consegue aceder ao servidor de base de dados em 127.0.0.1:5433. O contentor Postgres pode não estar em execução ou pode ainda não estar pronto. Execute docker compose --env-file .env -f infra/compose/docker-compose.yml ps e procure o serviço postgres com o estado healthy, porque o ficheiro Compose define uma verificação de estado que é executada a cada três segundos. Um contentor que reinicia continuamente normalmente indica que o volume pgdata foi criado com credenciais diferentes. docker compose ... down -v limpa esse volume e elimina também os dados.

A porta já está ocupada. Iniciar o Postgres falha com bind: address already in use quando outro processo ocupa a porta 5433. Isto acontece frequentemente devido a uma stack Rakazo anterior que não foi parada. sudo ss -lntp | grep 5433 identifica o processo.

Um bot nunca recebe um computador. Com SANDBOX_PROVIDER=docker e sem uma imagem rakazo/computer:local, não há nada para iniciar. docker image ls rakazo/computer responde a essa questão numa linha, e pnpm sandbox:build corrige o problema. Se o supervisor não conseguir aceder ao socket do Docker, também não conseguirá criar contentores. A mensagem indica o caminho: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.

Um comando longo termina a meio. .env.example define SANDBOX_COMMAND_TIMEOUT_MS=300000, por isso um único comando executado dentro do computador de um bot é interrompido após cinco minutos. Aumente esse valor para builds lentos, em vez de presumir que o sandbox falhou.

pnpm install falha de formas difíceis de interpretar. Verifique node -v antes de qualquer outra coisa. O workspace declara >=22, e uma versão antiga do Node falha no código das dependências, sem apresentar uma mensagem sobre versões.

O início de sessão funciona localmente, mas não através do domínio. BETTER_AUTH_URL, WEB_ORIGIN e API_URL têm de usar a mesma origem pública indicada na barra de endereço, incluindo o esquema. Um http://127.0.0.1:5173 antigo deixado num deles é normalmente a causa de uma sessão que nunca permanece ativa.

Atualizar um checkout fixado

O procedimento de atualização na documentação de self-hosting é curto: obtenha o novo código-fonte, execute a migração da base de dados e reinicie a API e o worker.

./scripts/backup.sh
git fetch --all
git checkout NEW_COMMIT_SHA
pnpm install
pnpm --filter @rakazo/db migrate
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml up -d --build

Faça primeiro uma cópia de segurança. As migrações avançam, e uma versão beta não oferece um caminho de reversão fiável. Leia os commits entre o SHA fixado e o novo SHA antes de os aplicar, porque um projeto tão recente pode renomear variáveis de ambiente sem aviso. Uma variável ausente manifesta-se como um serviço que inicia e termina logo a seguir. Se ainda estiver a decidir se Rakazo é mesmo a solução certa para executar, o resumo dos agentes de IA self-hosted apresenta outras opções desta categoria e o custo de manter cada uma em funcionamento.

FAQ

Posso executar o Rakazo numa VPS com 1 GB?

Não. O Postgres, a API, o worker, o supervisor do sandbox e a aplicação web são executados ao mesmo tempo. Com SANDBOX_PROVIDER=docker, cada bot ativo adiciona um container com um desktop gráfico e um browser. A documentação do projeto indica que 2 vCPU e 4 GB são suficientes para a API, o worker e o Postgres apenas quando o E2B aloja os desktops dos bots. Considere 4 GB como o mínimo para o plano de controlo e use mais memória quando os desktops forem executados na sua máquina.

O fornecedor do sandbox de desktop é seguro num servidor?

Não. O desktop executa diretamente os comandos do bot no host da API e do worker, com a conta que executa esse processo. Os ficheiros e as credenciais dessa conta ficam acessíveis. O repositório recomenda não o utilizar num servidor público ou partilhado. Use docker para um container por bot ou e2b quando mais de uma pessoa iniciar sessão.

Que versão do Rakazo devo instalar?

Em 16 August 2026 existe uma tag, v0.1.0-beta, publicada em 13 August 2026 e marcada como uma pré-lançamento. Faça checkout do commit para o qual ela aponta, 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb, em vez de acompanhar main. Uma branch pode mudar enquanto a utiliza e uma tag pode ser reposicionada. Por isso, nenhuma das duas identifica uma árvore à qual possa regressar. Registe o commit, porque só é possível fazer rollback quando sabe qual funcionou.

Onde devo colocar a minha chave de API do OpenRouter?

Em .env, como OPENROUTER_API_KEY, e nunca num ficheiro compose que faça commit. Ambos os comandos compose do repositório passam --env-file .env. Assim, o valor chega aos containers sem ser escrito num YAML monitorizado pelo controlo de versões. Também pode deixá-lo vazio e colar a chave na aplicação durante a configuração inicial. Defina um limite de gastos para a chave no fornecedor, porque um bot preso num loop continuará a chamar o modelo até algo o interromper.

Preciso de um nome de domínio e de TLS?

Para qualquer utilização além de um primeiro teste, sim. O ficheiro compose de produção executa o Caddy e obtém os certificados automaticamente. RAKAZO_HOST, BETTER_AUTH_URL, WEB_ORIGIN e API_URL têm de utilizar todos a mesma origem HTTPS pública. Para uma primeira verificação, pode ignorar o domínio: execute pnpm dev e encaminhe a porta 5173 através de SSH, em vez de a publicar.