Como hospedar seu próprio bot Rakazo em um VPS

O que o self-hosting do Rakazo realmente executa

Fazer self-hosting do Rakazo significa executar cinco componentes num único servidor Linux: PostgreSQL, um processo do Graphile Worker, a API, a aplicação Web e um contentor sandbox para cada bot que esteja ativo. O Rakazo é uma alternativa open source ao Grok Bot, publicada por elie222 sob a licença Apache 2.0. Cada bot tem a sua própria thread, o seu próprio computador, a sua própria memória e o seu próprio histórico. Também pode criar pares ou subagentes de curta duração. Se termos como memória, subagente e chamada de ferramenta tiverem um significado pouco claro nessa frase, vale a pena dedicar uma tarde a um percurso faseado pelo funcionamento real dos agentes, porque a maioria das definições abaixo só faz sentido quando consegue visualizar o que um bot faz ao ser ativado.

É por isso que esta configuração deve ficar num VPS (servidor privado virtual), e não num computador de secretária. Um bot que mantém memória e executa tarefas agendadas tem de estar acessível enquanto dorme. Quando um portátil entra em suspensão, a fila deixa de ser processada.

O Rakazo ainda está em beta inicial em agosto de 2026. Encare esta configuração como uma solução funcional, não como um appliance concluído. Toda a stack é desenvolvida em 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 as tarefas 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 a ativação de um bot é uma tarefa suportada 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, a alternativa é criar o seu próprio agente a partir de componentes.

Por que um plano de 1 GB não chega para isto

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 contentor com um ambiente de trabalho Linux gráfico e um browser.

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

Uma definição impede que esta situação piore. .env.example fornece SANDBOX_IDLE_MS=600000 com um comentário que indica que pausa os computadores E2B ou para os contentores Docker depois do número especificado de milissegundos de inatividade. Após dez minutos sem atividade, o computador é removido. O valor mínimo aceite é 30000. Sem essa definiçã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 release. Em 16 August 2026, o repositório tem exatamente uma tag, v0.1.0-beta, publicada em 13 August 2026 e marcada como prerelease.

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

Esse é o commit para o qual v0.1.0-beta aponta. 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 reatribuir. Por isso, nenhum dos dois identifica uma árvore à qual possa voltar. Um identificador de commit não muda. Registre-o junto com os outros dados do servidor, porque, quando uma atualização causa problemas, a correção mais simples é git checkout <old commit> e fazer um rebuild. Isso só funciona se souber qual commit estava funcionando. Fixar o commit com esta precisão é um custo de beta, não uma regra universal. Um projeto que publica releases deliberadas pode ser mantido numa tag publicada. É isso que uma stack self-hosted menor, como openGym faz.

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 mostrar 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 é disponibilizado 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: ser membro de 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 devem 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 substituição fora do desenvolvimento. Assim, uma implementação com configuração incompleta falha explicitamente em vez de funcionar com um segredo publicado no repositório.

openssl rand -base64 48
openssl rand -hex 32

Depois, 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. 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, apenas na interface de 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 pelos scanners em poucas horas. O ficheiro compose de produção lê POSTGRES_PASSWORD em vez disso. Defina esse valor como uma cadeia aleatória quando chegar a essa etapa.

A primeira execução

pnpm dev

Isso 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 está disponível em http://127.0.0.1:5173, onde deverá ver uma página de início de sessão.

Num VPS, não está nessa máquina e não deve publicar a porta 5173 para aceder à aplicação. Em vez disso, encaminhe as portas por 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 executar isto. pnpm dev executa o Vite no host, ligado localmente. O serviço web do ficheiro compose publica 5173:5173 em todas as interfaces. Se iniciar a stack completa do compose de desenvolvimento num VPS público, a aplicação ficará exposta. Por isso, use o ficheiro de produção e o reverse proxy para tudo o que deixar em execução.

Qual provedor de sandbox é seguro num servidor?

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

• docker é o padrão. Cada bot recebe o seu próprio container 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 multiutilizador, porque mantém os computadores dos bots separados do host que executa a sua API e a sua base de dados.
• desktop executa diretamente os comandos do bot 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 é um ambiente de runtime.

Leve literalmente o aviso sobre o modo desktop. Nesse modo, 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 home desse utilizador, as respetivas chaves SSH, as respetivas credenciais cloud e o respetivo .env. O texto de uma página web lida pelo bot transforma-se num comando no seu servidor. Usar o modo desktop num servidor é uma forma de acabar com um bot na posse das suas credenciais. Use-o numa máquina à qual tem acesso físico, ou não o use. Mudar de provedor coloca um container em torno desse percurso até à página web, mas não o elimina. Dar a um bot o seu próprio backend de pesquisa SearXNG cobre a mesma superfície de injeção do lado da pesquisa.

docker é um limite real, mas imperfeito. Um bot não consegue ler os ficheiros de outro bot, porque cada um tem o seu próprio container. No entanto, o supervisor que cria esses containers 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 opcional de um serviço separado. Quando está vazia, o valor padrão é BETTER_AUTH_SECRET. Isto significa que deixar esse segredo no valor de placeholder protege o serviço que cria os containers com uma string que qualquer pessoa pode ler no GitHub. Defina os dois valores. Para obter a separação mais forte disponível aqui, use e2b, ou dê 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 um agente que faça algo errado é a máquina dele não ter 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 configuração.

Mantenha a chave em .env e fora de qualquer ficheiro que faça commit. Ambos os comandos compose no repositório passam --env-file .env, por isso os valores chegam aos contentores sem serem gravados em YAML controlado pelo git. Também pode deixar OPENROUTER_API_KEY vazio e colar uma chave na aplicação durante a configuração inicial. Esta é mais uma razão para ENCRYPTION_KEY ter um valor realmente aleatório, em vez do marcador incluído no pacote.

Defina um limite de gastos para a chave no fornecedor antes de qualquer bot a utilizar. Um bot que entra num ciclo é um bot que gera custos, e um limite por chave é a única forma de o parar que não depende de monitorização manual. Dê um nome exclusivo a esta chave para poder revogá-la isoladamente. Se estiver a configurar isto para uma equipa, e não apenas para si, um gateway do OneCLI à frente do agente de todos é uma resposta diferente ao mesmo problema, porque mantém as chaves dos fornecedores num único local, em vez de manter uma por pessoa.

Deixar o modo de desenvolvimento e passar a um serviço que pode ficar em execução

O repositório inclui um ficheiro Compose de produção que executa o Postgres, a API, o worker, a aplicação web e o Caddy, que obtém automaticamente os certificados TLS (transport layer security). É necessário usar o E2B para os computadores dos bots.

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 por palavra-passe, define regras do UFW (uncomplicated firewall) para SSH, HTTP e HTTPS, ativa o fail2ban e aplica perfis do AppArmor. Leia-o antes de o executar, porque altera a forma como inicia sessão. Mantenha uma segunda sessão SSH aberta enquanto o script estiver em execução.

O .env de produção requer mais definições do que o de desenvolvimento. A documentação de instalação própria 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 num nome público aceita registos de qualquer pessoa que a encontre, e cada conta nova recebe um computador. Defina primeiro uma allowlist. Pode alargá-la mais tarde, se quiser. Se já executar vários serviços no mesmo servidor e preferir manter uma única lista de pessoas em vez de uma allowlist por aplicação, colocar uma instância do Authentik à frente deles transfere essa decisão para o proxy, embora este fique à frente das próprias contas Better Auth do Rakazo, em vez de as substituir.

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

Backups

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

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

backup.sh faz o dump do Postgres e arquiva data/. Numa máquina de que 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. Um backup armazenado no mesmo disco da base de dados não é um backup, por isso copie-o para fora do servidor. Depois, restaure-o uma vez num servidor sobressalente, antes de precisar dele.

Por que falha e o que verá

pnpm db:migrate não consegue aceder à base de dados. A migração informa que não consegue aceder ao servidor de base de dados em 127.0.0.1:5433. O contentor do 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 integridade 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 o volume e elimina também os dados nele contidos.

A porta já está ocupada. Iniciar o Postgres falha com bind: address already in use quando outro processo utiliza a porta 5433, normalmente uma stack Rakazo anterior que se esqueceu de parar. 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, e 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, pelo que um único comando 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 confusas. 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, em vez de apresentar uma mensagem sobre versões.

A autenticação funciona localmente, mas não através do domínio. BETTER_AUTH_URL, WEB_ORIGIN e API_URL têm de conter a mesma origem pública que a barra de endereço, incluindo o esquema. Um http://127.0.0.1:5173 antigo deixado numa delas é normalmente a causa de uma sessão que nunca fica ativa.

Atualizar um checkout fixado

O procedimento de atualização na documentação de instalação autónoma é 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 avisar. Uma variável em falta manifesta-se como um serviço que inicia e depois termina. Se ainda está a decidir se Rakazo é a opção certa, o resumo dos agentes de IA instalados localmente apresenta outras opções desta categoria e o custo de manter cada uma em execução.

FAQ

Posso executar o Rakazo num VPS com 1 GB?

Não. O Postgres, a API, o worker, o supervisor do sandbox e a aplicação Web são executados em simultâneo. Com SANDBOX_PROVIDER=docker, cada bot ativo adiciona um contentor com um ambiente de trabalho 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 ambientes de trabalho dos bots. Considere 4 GB como o mínimo para o plano de controlo. Use mais memória quando os ambientes de trabalho forem executados na sua máquina.

O fornecedor do sandbox de ambiente de trabalho é seguro num servidor?

Não. O desktop executa os comandos do bot diretamente 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 indica que não deve utilizar esta opção num servidor público ou partilhado. Use docker para ter um contentor por bot. Use e2b quando houver mais do que uma pessoa a 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 versão de pré-lançamento. Faça checkout do commit apontado por essa tag, 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb, em vez de acompanhar main. Uma branch pode mudar sem aviso, e uma tag pode ser reatribuída. Por isso, nenhuma das duas identifica uma árvore à qual possa regressar. Registe o commit. Só é possível fazer rollback quando sabe qual funcionou.

Onde devo colocar a minha chave da API do OpenRouter?

Em .env, como OPENROUTER_API_KEY, e nunca num ficheiro compose que vá versionar. Ambos os comandos compose do repositório passam --env-file .env. Assim, o valor chega aos contentores sem ser escrito no YAML acompanhado 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. Um bot preso num ciclo 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 a mesma origem HTTPS pública. Para uma primeira avaliação, pode ignorar o domínio: execute pnpm dev e encaminhe a porta 5173 através de SSH, em vez de a publicar.