SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Como hospedar seu próprio bot Rakazo em um VPS

Veja como rodar o Rakazo em um VPS com Node 22, pnpm, Postgres, Graphile Worker e Docker Compose, incluindo sandbox, chaves e dimensionamento real.

O que a execução self-hosted do Rakazo realmente envolve

Executar o Rakazo em self-hosting significa executar cinco componentes num único servidor Linux: PostgreSQL, um processo Graphile Worker, a API, a aplicação web e um contentor sandbox que funciona como o computador dos bots. O Rakazo é uma alternativa open source ao Grok Bot, publicada por elie222 sob a licença Apache 2.0. Cada bot tem as suas próprias conversas, memória, rotinas e histórico. Partilha um Team Computer com os outros bots do workspace, a menos que lhe seja atribuído um Private Computer. Também pode criar bots pares ou subagentes de curta duração. Se termos como memória, subagente e chamada de ferramenta não forem claros nessa frase, um percurso faseado pelo funcionamento efetivo dos agentes merece uma tarde antes de começar, porque a maioria das definições abaixo só faz sentido quando consegue imaginar o que um bot está a fazer ao ser iniciado.

É precisamente por isso que isto deve ser executado num VPS (servidor privado virtual), e não num computador pessoal. 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.

O Rakazo continua a descrever-se como beta em outubro de 2026, embora já publique releases com numeração estável. Por isso, trate esta configuração como uma instalação funcional, e não como um appliance concluído. Toda a stack é 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. Portanto, não é necessário executar Redis nem um segundo armazenamento de dados. .env.example define WAKEUP_DRIVER=graphile, o que significa que o arranque de um bot corresponde a um trabalho suportado pelo Postgres. Se parar o Postgres, todas as ações agendadas dos bots param com ele. 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 suporta 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 vem o computador dos bots: por padrão, um contêiner Team Computer compartilhado que contém um desktop Linux gráfico, com um display X e um processo Chrome separado para cada bot ativo.

A documentação de self-host do projeto não informa mais o tamanho do host. A documentação em v0.3.5, verificada em 27 October 2026, lista apenas os requisitos de software. O que ela informa é um limite por computador: com sandboxes Docker, RAKAZO_COMPUTER_MEMORY tem como padrão 2g e RAKAZO_COMPUTER_CPUS tem como padrão 2. Esse limite se aplica a cada computador, não a cada bot. Cada workspace recebe um Team Computer por padrão, e cada Team bot ativo executa seu desktop e navegador dentro dele. Portanto, todos compartilham esses 2 GB e dois cores. Apenas um bot transferido para um Private Computer recebe um contêiner e um limite próprios. Defina SANDBOX_PROVIDER=docker e esses desktops passarão a usar seu VPS, além do control plane. Assim, 4 GB é um piso, não uma meta. Comece com 8 GB se pretende manter mais de um bot ativo, aumente RAKAZO_COMPUTER_MEMORY para que o computador compartilhado possa realmente usar essa memória e meça o número real com docker stats enquanto os bots trabalham. O navegador dentro do sandbox é o que altera o consumo de memória, portanto uma ficha técnica não informará esse valor. Para impedir que uma máquina pequena execute muitos navegadores ao mesmo tempo, defina um SANDBOX_TEAM_SCREEN_LIMIT positivo. Ele limita os desktops ativos em um Docker Team Computer. O valor fornecido em 0 deixa esse limite desativado. Se a memória estiver muito limitada, RAKAZO_COMPUTER_MEMORY também aceita um valor menor, como 1536m. Para conhecer o método geral de dimensionamento de uma máquina para executar agentes, quanto de RAM e CPU um VPS para agentes realmente precisa explica a medição em detalhes.

Uma configuração impede que isso piore. .env.example fornece SANDBOX_IDLE_MS=600000, e o comentário informa que os computadores são pausados ou interrompidos depois desse número de milissegundos ociosos. Após dez minutos de ociosidade, o computador é encerrado. O valor mínimo aceito é 30000, e 0 desativa o modo de suspensão por ociosidade. O mesmo comentário sugere 0 para instalações Docker self-host, nas quais um computador ocioso não custa nada. Assim, aplicações e sessões de longa duração permanecem ativas. Isso vale para o custo, não para a memória. Em um VPS pequeno, mantenha o temporizador ativado, porque, sem ele, todos os computadores que você iniciar e todos os navegadores dentro deles continuarão em execução.

O disco também entra na conta. A imagem do sandbox, os módulos Node e o volume do Postgres compartilham o mesmo disco, portanto 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 9 de novembro de 2026, v0.8.0, publicada em 4 de novembro de 2026, é a release marcada como Latest. Este guia continua fixado em v0.3.5, publicada em 25 de outubro de 2026.

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

Esse commit é o apontado por v0.3.5. Fixe o commit, não a branch nem a tag. Uma branch muda no próximo git pull, e uma tag é um rótulo móvel que um maintainer pode redirecionar. Portanto, nenhuma das duas identifica uma árvore à qual possa regressar. O identificador de um commit não muda. Anote-o junto dos restantes dados do servidor. Quando uma atualização causa problemas, a correção mais simples é git checkout <old commit> e reconstruir o ambiente. Isso só funciona se souber qual commit estava funcional. O README fixado classifica o Rakazo como beta, por isso vale a pena fixar esta versão com precisão. Um projeto com um longo histórico de releases deliberadas pode ser mantido numa tag publicada, como faz uma stack self-hosted menor, como o openGym.

Requisitos: Node 22, pnpm 9 e Docker

node -v
pnpm -v
docker --version

package.json declara "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" } e "packageManager": "pnpm@9.15.0". Portanto, node -v tem de apresentar v22.22.2 ou uma versão 22.x posterior, qualquer v24 ou v26 e posterior. Uma versão v22 anterior a 22.22.2 fica fora desse intervalo, e o README afirma explicitamente que Node.js 23.x e 25.x não são suportados. Instale uma versão suportada do Node a partir do NodeSource ou do nvm. O Corepack é incluído no Node 22 e 24; no Node 26 e posteriores, instale-o primeiro com npm install -g corepack. Em seguida, ative o pnpm:

corepack enable
corepack prepare pnpm@9.15.0 --activate

O Docker Engine e o plugin compose cobrem o restante. A documentação de instalação autónoma exige o Docker Engine 26 ou posterior e a API 1.45 ou posterior para subcaminhos de volumes do bot, além de curl e OpenSSL. O seu utilizador também 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 login. Saiba primeiro o que isso concede: 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

É necessário alterar vários valores antes de iniciar qualquer componente. .env.example inclui BETTER_AUTH_SECRET=replace-with-32-plus-character-secret, ENCRYPTION_KEY=replace-with-64-random-hex-characters, SCREEN_PROXY_SECRET=replace-with-32-plus-character-screen-proxy-secret e SANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token, e deixa POSTGRES_PASSWORD e POSTGRES_APP_PASSWORD vazios. Todos esses placeholders estão publicados no repositório. Por isso, um deploy que mantenha algum deles está a usar um segredo que qualquer pessoa pode ler. Atribua um valor aleatório próprio a cada um. ENCRYPTION_KEY tem de conter 64 caracteres hexadecimais aleatórios. É exatamente isso que openssl rand -hex 32 imprime. Os outros segredos precisam de 32 ou mais caracteres. Execute a linha base64 uma vez para cada um. Para as duas palavras-passe do Postgres, a documentação do serviço pede valores seguros para URLs. A última linha gera esses valores. Execute-a também uma vez para cada palavra-passe. A base de dados tem dois logins. DATABASE_MIGRATION_URL é incluído como postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo, a conta proprietária que executa as migrações. DATABASE_URL é incluído como postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo, o login usado pela aplicação. Essa conta não tem privilégios de superutilizador e está sujeita à segurança ao nível das linhas. Coloque cada palavra-passe no seu próprio URL. pnpm db:migrate cria o login rakazo_app com a palavra-passe que definiu.

openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24

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

docker compose --env-file .env -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.postgres-host.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 imprimir uma linha.

O ficheiro compose base não publica nenhuma porta do Postgres. O overlay docker-compose.postgres-host.yml usado nesse comando publica-a como 127.0.0.1:5433, acessível apenas através do loopback. Assim, ferramentas no host, como pnpm db:migrate e pnpm dev, conseguem aceder à base de dados. Mantenha essa configuração. O Compose recusa iniciar o Postgres sem um POSTGRES_PASSWORD em .env. No entanto, uma porta do Postgres acessível pela Internet permite ataques às palavras-passe. O ficheiro compose de produção lê a mesma variável e não publica nenhuma porta da base de dados.

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 por predefinição. Se essas portas estiverem ocupadas, pnpm dev seleciona outro bloco livre e apresenta os URLs. Com as portas predefinidas, a aplicação fica 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á diante dessa 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 formas de executar isto. pnpm dev executa o Vite no host, ligado apenas localmente. O ficheiro Compose de desenvolvimento publica 127.0.0.1:5173:5173 através do serviço web e 127.0.0.1:3100:3100 através do serviço api, ambos apenas na interface loopback, pelo que o mesmo túnel funciona com ele. No ficheiro de produção, a aplicação web não publica nenhuma porta do host e apenas expõe a porta 5173 aos contentores nas suas próprias redes. O Caddy é o único componente que publica as portas 80 e 443. Por isso, use o ficheiro de produção e o respetivo reverse proxy para qualquer serviço que mantenha em execução.

Qual provedor de sandbox é seguro num servidor?

Esta é a única configuração que precisa de estar correta. SANDBOX_PROVIDER em .env é docker por padrão, e o checkout fixado também oferece suporte ao Railway, além dos provedores listados no documento de self-host.

  • docker é o padrão. Os computadores dos bots são executados como containers na sua máquina, criados a partir da imagem produzida pelo comando pnpm sandbox:build e executados sob um supervisor. Por padrão, os bots de um workspace compartilham um Team Computer, e um bot recebe um container próprio somente em um Private Computer. Não é necessária uma conta E2B.
  • e2b executa os computadores dos bots no E2B e precisa de E2B_API_KEY. Em v0.3.5, a factory aceita esse provedor em produção quando a chave é fornecida, sem a restrição NODE_ENV. O documento de self-host o considera adequado para produção pública ou multiusuário, porque mantém os computadores dos bots afastados do host que executa a sua API e o seu banco de dados.
  • daytona, createos e boat são outros provedores remotos, cada um exigindo a sua própria chave: DAYTONA_API_KEY, CREATEOS_SANDBOX_API_KEY ou BOAT_API_KEY.
  • railway executa computadores no Railway e precisa de RAILWAY_API_TOKEN e de um RAILWAY_ENVIRONMENT_ID selecionado explicitamente na API e no worker. Use um projeto ou ambiente dedicado do Railway para os sandboxes.
  • desktop executa os comandos do bot diretamente no host da API e do worker, como diz a documentação. Em v0.3.5, a API e o worker recusam esse provedor, a menos que NODE_ENV seja development ou test, mas .env.example inclui NODE_ENV=development, portanto um servidor que executa pnpm dev ainda o aceita. Não o habilite em um serviço público ou compartilhado.
  • fake é um emulador usado apenas para verificação. Não é um runtime.
  • none inicia o produto sem nenhum host de computador.

Interprete isso literalmente. No modo desktop, não existe nenhum limite de isolamento, portanto o bot executa comandos shell como o usuário que executa o processo da API, com o diretório home desse usuário, as chaves SSH desse usuário, as credenciais de cloud desse usuário e o .env desse usuário. O texto de uma página web lida pelo bot se torna um comando no seu servidor. O modo desktop em um servidor é como um bot acaba tendo as suas credenciais. Use-o em uma máquina na qual você trabalha diretamente, ou não o use. Trocar de provedor coloca um container ao redor desse caminho da página web, em vez de fechá-lo, e dar a um bot o seu próprio backend de pesquisa SearXNG cobre a mesma superfície de injeção pelo lado da pesquisa.

docker é um limite real entre os bots e o seu host, mas um limite fraco entre os próprios bots. Por padrão, eles compartilham um único Team Computer, e o documento do runtime do computador diz que os bots de um Team compartilham o usuário do sistema operacional, o workspace, os perfis do navegador e o acesso ao shell e ao X11, e que as pastas por bot organizam o trabalho, mas não são limites de segurança. Portanto, qualquer bot de um Team pode ler os arquivos de outro bot do mesmo Team. Um bot que precisa dos seus próprios limites deve usar um Private Computer, que o provedor docker executa como um container irmão separado na sua própria rede. No entanto, o supervisor que cria esses containers monta /var/run/docker.sock, e o documento de self-host afirma claramente: o acesso a esse socket equivale ao controle do host Docker. Portanto, mantenha o supervisor privado. .env.example trata SANDBOX_SUPERVISOR_TOKEN como uma credencial dedicada, distinta de BETTER_AUTH_SECRET, exigida pelos sandboxes Docker fora do desenvolvimento local, e vem com um valor de placeholder que qualquer pessoa pode ler no GitHub. Defina um valor aleatório próprio para ele. 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. Esse é o mesmo raciocínio por trás de executar agentes de código em uma VM descartável: a forma mais barata de sobreviver a um agente fazendo algo errado é fazer com que a máquina dele não tenha valor.

Onde devem ficar as chaves de API dos modelos?

A faturação opcional de créditos de modelos do Rakazo permanece desativada, exceto quando os dois segredos do Stripe estão definidos. A chave é fornecida por si. .env.example define PI_DEFAULT_PROVIDER=openrouter, portanto OPENROUTER_API_KEY é normalmente o local correto, e as chaves dos fornecedores funcionam através da mesma definição.

Mantenha a chave em .env e fora de qualquer ficheiro que seja submetido ao repositório. Ambos os comandos compose do repositório passam --env-file .env, por isso os valores chegam aos contentores sem nunca serem escritos em YAML controlado pelo git. Também pode deixar OPENROUTER_API_KEY vazio e ligar um modelo na aplicação depois do registo. Esta é mais uma razão para ENCRYPTION_KEY ter um valor aleatório real, em vez do marcador fornecido por defeito.

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 gastos. O Rakazo também fornece MAX_TOOL_CALLS_PER_TURN: defina um inteiro positivo para interromper de forma controlada um turno que exceda o orçamento de chamadas de ferramentas, mantendo ainda a produção de uma mensagem final do assistente. Se 0 não estiver definido ou estiver vazio, o limite é ilimitado. Isto contabiliza chamadas de ferramentas, não dinheiro, por isso não substitui o limite de gastos do fornecedor. Dê a esta chave um nome próprio para poder revogá-la isoladamente. Se estiver a configurar isto para uma equipa, e não apenas para si, o gateway único do OneCLI à frente dos agentes de toda a equipa é 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 para uma configuraçã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 para obter automaticamente certificados TLS (transport layer security). O Caddy é o único serviço que publica portas. Por predefinição, utiliza o E2B para os computadores dos bots. Uma sobreposição opcional, infra/compose/docker-compose.prod.docker.yml, executa computadores Docker locais na mesma stack. A documentação avisa que o supervisor adicionado por essa sobreposição tem privilégios equivalentes aos de root no host.

sudo --preserve-env=SSH_CONNECTION DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  build --build-arg GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  up -d --wait --pull never
curl --fail https://app.example.com/health

Crie uma conta deploy que aceite apenas autenticação por chave e confirme que consegue iniciar sessão com ela antes de executar o script. harden-host.sh desativa a autenticação SSH por palavra-passe e o login de root, limita a taxa de ligações SSH, adiciona permissões para SSH, HTTP e HTTPS através do UFW (uncomplicated firewall), preservando as regras existentes para redes privadas, e ativa o fail2ban, as atualizações de segurança automáticas, o AppArmor e as regras de auditoria. O script recusa-se a executar sem SSH_CONNECTION. Por isso, o comando transmite esse valor através de sudo. O script reverte a alteração da firewall, a menos que a confirme a partir de uma sessão SSH nova dentro de três minutos. Leia o script antes de o executar, porque ele altera a forma como inicia sessão e recarrega o SSH. Mantenha a consola do seu fornecedor aberta até conseguir iniciar uma nova sessão SSH.

A .env de produção requer mais do que a configuração de desenvolvimento. A documentação de instalação autónoma apresenta estes requisitos mínimos, além dos segredos.

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
SIGNUPS_ENABLED=true
SIGNUP_ALLOWLIST=you@example.com
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
WAKEUP_DRIVER=graphile
DATA_DIR=/data
RAKAZO_DEPLOY_DIR=/srv/rakazo
RAKAZO_IMAGE_TAG=local
POSTGRES_PASSWORD=<random, URL-safe>
POSTGRES_APP_PASSWORD=<random, URL-safe>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<64 random hex characters>
SCREEN_PROXY_SECRET=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>

Aponte um registo A para o servidor antes do primeiro up. O Caddy pede um certificado para o nome definido em RAKAZO_HOST. Esse nome tem de resolver para este servidor, e a porta 80, para a validação HTTP, ou a porta 443, para a validação TLS-ALPN, tem de estar acessível externamente. Ambos os desafios estão ativados por predefinição. Por isso, fechar apenas a porta 80 não impede a emissão do certificado através da porta 443.

Mantenha SIGNUP_ALLOWLIST definido desde o início para o seu próprio endereço. .env.example inclui SIGNUPS_ENABLED=true por predefinição, e ambas as definições são lidas do ambiente em cada arranque da API. Assim, uma instância com um nome público, com os registos abertos e sem uma lista de permissões aceita registos de qualquer pessoa que a encontre. Uma lista de permissões não vazia é aplicada em cada arranque e substitui a lista armazenada. Os registos com lista de permissões requerem verificação da caixa de correio, incluindo a primeira conta. Por isso, configure o envio de correio antes de criar a sua conta. Sem correio eletrónico, a documentação recomenda iniciar com SIGNUPS_ENABLED=false e criar a sua conta com o comando de bootstrap no servidor indicado. Esse comando cria uma conta normal verificada, sem privilégios no servidor. Configure primeiro a lista de permissões. Pode flexibilizá-la mais tarde, se necessário. Se já executar vários serviços no mesmo servidor e preferir manter uma única lista de utilizadores em vez de uma lista de permissões por aplicação, colocar uma instância do Authentik à frente deles transfere essa decisão para o proxy. No entanto, essa configuração fica à frente das próprias contas Better Auth do Rakazo, em vez de as substituir.

Considere docs/self-host.md no repositório como a fonte de autoridade para as definições de produção, porque esse ficheiro muda com o código e este guia não muda. Como o Compose executa o trabalho, aplicam-se as regras habituais. Os conceitos básicos do Docker Compose para um VPS explicam por que razão --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/ contêm os dados da instância neste ambiente. A recuperação também precisa de ENCRYPTION_KEY e de quaisquer chaves mestras de conteúdo configuradas. Por isso, mantenha cópias fora do servidor.

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

backup.sh faz um dump do Postgres e arquiva data/. restore.sh funciona na stack Compose de desenvolvimento, numa base de dados vazia e com os serviços da aplicação parados. Não lê os ficheiros de backup de produção. Numa máquina de que dependa, instale infra/compose/backup-prod.sh como /usr/local/sbin/rakazo-backup, com o timer fornecido pelo repositório. A ferramenta grava um dump verificado e um arquivo dos dados da aplicação em /var/backups/rakazo. Por predefinição, mantém até três snapshots verificados, definido por RAKAZO_BACKUP_KEEP, dentro de um limite de 50 GiB definido por RAKAZO_BACKUP_MAX_GB. Também remove snapshots incompletos e histórico excedente antes de cada execução, pelo que a rotação é automática. Pode ainda cifrar cada backup com age para os destinatários públicos que indicar em /etc/rakazo/backup.env. Assim, o servidor grava backups que não consegue ler. Gere esse par de chaves numa máquina que controle e mantenha a chave privada fora do servidor. Sem destinatários, o backup permanece em texto simples e é registado um aviso. Depois do primeiro backup cifrado, uma execução sem destinatários falha, exceto se permitir explicitamente texto simples com RAKAZO_BACKUP_ALLOW_PLAINTEXT=1. Um backup no mesmo disco da base de dados não é um backup. Copie-o para fora da máquina. Depois, restaure-o uma vez num servidor sobresselente, 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 Postgres pode não estar em execução, pode estar em execução mas ainda não estar pronto, ou pode ter sido iniciado sem a sobreposição docker-compose.postgres-host.yml, que publica a porta 5433 no host. 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. Se o contentor reiniciar continuamente, consulte os respetivos logs: a stack Compose fixada recusa iniciar com um volume Postgres 16 antigo até este ser migrado para Postgres 18. docker compose ... down -v limpa o 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 já utiliza a porta 5433, normalmente uma stack Rakazo anterior que não foi parada. sudo ss -lntp | grep 5433 identifica o processo. A sobreposição lê a porta do host a partir de POSTGRES_HOST_PORT, por isso pode alterá-la, desde que também altere DATABASE_URL e DATABASE_MIGRATION_URL.

Um bot nunca obtém um computador. Com SANDBOX_PROVIDER=docker e sem a imagem rakazo/computer:local, não há nada para iniciar. docker image ls rakazo/computer confirma isso 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, por isso um único comando dentro do computador de um bot é terminado após cinco minutos. Aumente este valor para builds lentos, em vez de assumir que a sandbox falhou.

pnpm install falha de formas difíceis de interpretar. Verifique node -v antes de qualquer outra coisa. O workspace declara ^22.22.2 || ^24.0.0 || >=26.0.0, por isso 23.x, 25.x e qualquer versão 22.x anterior a 22.22.2 estão fora desse intervalo. O .npmrc fixado define engine-strict=true, por isso pnpm install rejeita uma versão do Node não suportada com um erro de engine/versão antes de o código das dependências da aplicação ser executado.

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 apresentada na barra de endereço, incluindo o esquema. Um http://127.0.0.1:5173 desatualizado deixado num deles é normalmente a causa de uma sessão que nunca fica ativa.

Atualizar um checkout fixado

O procedimento de atualização descrito na documentação de self-hosting para uma stack de produção do Compose criada a partir do seu checkout é curto: obtenha o novo código-fonte e, em seguida, reconstrua e reinicie a API, o worker e a aplicação web. As migrações são executadas quando a API inicia, porque o comando de arranque as aplica antes de disponibilizar o serviço.

sudo /usr/local/sbin/rakazo-backup
git fetch --all --tags
git checkout NEW_COMMIT_SHA
export GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  up -d --wait --pull never --build api worker web

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. Se o seu checkout for anterior a 30 August 2026, o que inclui o commit v0.1.0-beta, leia a nota da documentação sobre a migração 20260830200000_space_scope_names_and_user_credentials antes de atualizar. Trata-se de uma mudança coordenada. Por isso, pare primeiro a API e o worker antigos e execute a verificação do limite de privacidade do Space indicada na documentação. Ao atualizar a partir de um checkout anterior à separação do login da aplicação, defina POSTGRES_APP_PASSWORD em .env antes de reconstruir. O ficheiro Compose de produção recusa iniciar sem essa definição. Os ficheiros Compose do checkout do código-fonte e de produção também executam o Postgres 18. Uma instalação existente do Postgres 16 precisa do procedimento infra/compose/upgrade-postgres.sh da documentação antes de poder iniciar no novo layout. Leia os commits entre o SHA fixado e o novo SHA antes de os aplicar. Um projeto tão recente pode renomear variáveis de ambiente sem aviso, e uma variável em falta manifesta-se como um serviço que inicia e termina logo depois. Se ainda estiver a decidir se o Rakazo é a solução certa para executar, a síntese de 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 num VPS com 1 GB?

Não. O Postgres, a API, o worker, o supervisor do sandbox e a aplicação web executam ao mesmo tempo. Com SANDBOX_PROVIDER=docker, o computador dos bots adiciona um contentor com um ambiente de trabalho gráfico, um display X separado e um processo Chrome para cada bot ativo. Tudo fica dentro do limite predefinido de 2 GB de memória e dois CPUs. A documentação de self-host em v0.3.5 não indica o tamanho do host. Considere 4 GB como o mínimo para o plano de controlo. Use mais memória quando os ambientes de trabalho gráficos forem executados na sua máquina.

O provider de desktop sandbox é seguro num servidor?

Não. A documentação de self-host diz que desktop executa comandos diretamente no host da API e do worker. O bot atua, portanto, como o utilizador que executa esse processo, com acesso aos ficheiros e às credenciais desse utilizador. Em v0.3.5, a API e o worker recusam-no fora dos modos de desenvolvimento e teste. No entanto, um servidor que execute pnpm dev está no modo de desenvolvimento e aceita-o. Mantenha-o desligado de qualquer servidor público ou partilhado. Use docker para dar a um bot um Private Computer quando ele não deve partilhar ficheiros com os outros bots da workspace. Use e2b quando mais de uma pessoa iniciar sessão.

Que versão do Rakazo devo instalar?

Em 9 de novembro de 2026, a release mais recente é v0.8.0, publicada em 4 de novembro de 2026 e marcada como Latest. Para seguir este guia, faça checkout do commit v0.3.5 fixado, f31e3c0699f086d663637c4107858c238a086fb3, em vez de acompanhar main ou a prerelease de agosto v0.1.0-beta. Uma branch muda e uma tag pode ser redirecionada. Portanto, nenhuma das duas identifica uma árvore à qual possa regressar. Registe o commit, porque só é possível reverter 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 será incluído num commit. Ambos os comandos Compose do repositório passam --env-file .env. Assim, o valor chega aos contentores sem ser gravado num YAML versionado. Também pode deixá-lo vazio e ligar um modelo na aplicação depois de criar a conta. Defina um limite de gastos para a chave no provider, porque um bot preso num ciclo continua 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. Defina RAKAZO_HOST como o hostname público e BETTER_AUTH_URL, WEB_ORIGIN e API_URL com a mesma origem HTTPS pública. Para uma primeira verificação, pode ignorar o domínio: execute pnpm dev e encaminhe a porta 5173 por SSH, em vez de a publicar.

Este artigo foi útil?