Cómo instalar Rakazo en tu propio VPS

Qué ejecuta realmente el self-hosting de Rakazo

El self-hosting de Rakazo consiste en ejecutar cinco componentes en un servidor Linux: PostgreSQL, un proceso de Graphile Worker, la API, la aplicación web y un contenedor sandbox para cada bot activo. Rakazo es una alternativa de código abierto a Grok Bot, publicada por elie222 con licencia Apache 2.0. Cada bot tiene su propio hilo, su propio equipo, su propia memoria y su propio historial. También puede crear bots pares o subagentes de corta duración. Si términos como memoria, subagente y llamada a una herramienta no le resultan familiares en ese contexto, conviene dedicar primero una tarde a un recorrido gradual por el funcionamiento real de los agentes, porque la mayoría de los ajustes siguientes sólo tienen sentido cuando puede imaginar qué hace un bot al activarse.

Por eso esta configuración debe ejecutarse en un VPS (servidor privado virtual) y no en un equipo de escritorio. Un bot que conserva memoria y ejecuta tareas programadas debe estar disponible mientras usted duerme. Un portátil que entra en suspensión interrumpe la cola.

Rakazo se encuentra en una beta inicial en agosto de 2026, así que debe tratar esta configuración como un sistema funcional y no como un dispositivo terminado. Toda la pila está desarrollada en TypeScript: React 19 y Vite para la aplicación web, Hono para la API, Postgres con Prisma, Better Auth para las cuentas y Graphile Worker para los trabajos en segundo plano. Graphile Worker almacena su cola en Postgres, por lo que no es necesario ejecutar Redis ni un segundo almacén de datos. .env.example configura WAKEUP_DRIVER=graphile, lo que significa que la activación de un bot corresponde a un trabajo respaldado por Postgres. Si detiene Postgres, se detienen todas las acciones programadas de los bots. Si prefiere ensamblar un agente a partir de componentes en lugar de ejecutar el producto de otra persona, la otra opción es crear su propio agente a partir de componentes.

Por qué un plan de 1 GB no puede soportar esto

Cuente los procesos. Postgres es uno. La API es un proceso de Node. El worker es un segundo proceso. La aplicación web es un tercero. El supervisor del sandbox es un cuarto. Después, cada bot en ejecución obtiene un contenedor que incluye un escritorio gráfico de Linux y un navegador.

La documentación propia del proyecto para la instalación indica una cifra realista: una máquina con 2 vCPU y 4 GB es suficiente para la API, el worker y Postgres cuando E2B administra los escritorios de los bots. Esa cifra corresponde sólo al plano de control, con la parte pesada alojada en otro lugar. Configure SANDBOX_PROVIDER=docker y esos escritorios pasarán a su VPS, por lo que 4 GB será el mínimo y no el objetivo. Empiece con 8 GB si piensa mantener más de un bot activo y mida la cifra real con docker stats mientras un bot trabaja. El navegador dentro del sandbox es lo que aumenta el consumo de memoria, por lo que una hoja de especificaciones no le dará la respuesta. Para conocer el método general para dimensionar un servidor para tareas de agentes, cuánta RAM y CPU necesita realmente un VPS para agentes explica la medición en detalle.

Una opción evita que la situación empeore. .env.example incluye SANDBOX_IDLE_MS=600000 con el comentario de que pausa los equipos de E2B o detiene los contenedores de Docker después del número indicado de milisegundos inactivos. Tras diez minutos de inactividad, el equipo desaparece. El valor mínimo aceptado es 30000. Sin esta opción, cada bot que haya abierto conservaría memoria indefinidamente.

El disco también cuenta. La imagen del sandbox, los módulos de Node y el volumen de Postgres comparten un mismo disco, por lo que 40 GB es un punto de partida razonable.

Fija una versión antes de clonar

Rakazo avanza rápido y main no es una versión publicada. A fecha de 16 August 2026, el repositorio contiene exactamente una etiqueta, v0.1.0-beta, publicada el 13 August 2026 y marcada como versión preliminar.

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

Ese es el commit al que apunta v0.1.0-beta. Fije el commit, no la rama ni la etiqueta. Una rama cambia en el siguiente git pull, y una etiqueta es un nombre móvil que un mantenedor puede reasignar, por lo que ninguna de las dos identifica un árbol al que pueda volver. Un identificador de commit no puede cambiar. Anótelo junto con los demás datos del servidor, porque cuando una actualización rompe algo, la solución rápida y económica es git checkout <old commit> y reconstruir, y eso sólo funciona si sabe qué commit funcionaba. Fijar esta referencia con tanta precisión es un coste propio de la fase beta, no una regla universal. Un proyecto que publique versiones deliberadas puede fijarse en una etiqueta publicada, como hace una pila self-hosted más pequeña como openGym.

Requisitos: Node 22, pnpm 9 y Docker

node -v
pnpm -v
docker --version

package.json declara "engines": { "node": ">=22" } y "packageManager": "pnpm@9.15.0", por lo que node -v debe mostrar v22 o una versión posterior. El paquete de Node del repositorio de Ubuntu suele ser más antiguo, así que instale NodeSource o nvm. pnpm se incluye con Node mediante corepack:

corepack enable
corepack prepare pnpm@9.15.0 --activate

Docker Engine y el plugin compose cubren el resto. Su usuario debe poder acceder al daemon. Si docker ps responde permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, añada su usuario al grupo docker y abra un nuevo shell de inicio de sesión. Compruebe primero qué permisos concede esto: pertenecer a docker equivale a tener root en la máquina, porque cualquier usuario de ese grupo puede iniciar un contenedor que monte el sistema de archivos del host.

Configurar .env y, después, iniciar Postgres

cp .env.example .env
chmod 600 .env

Hay dos valores que deben cambiar antes de exponer cualquier servicio a la red. .env.example incluye BETTER_AUTH_SECRET=replace-with-32-plus-character-secret y ENCRYPTION_KEY=replace-with-64-char-hex-or-passphrase. Rakazo rechaza esos valores de marcador fuera del entorno de desarrollo. Así, un despliegue con una configuración incompleta falla de forma explícita en lugar de ejecutarse con un secreto publicado en el repositorio.

openssl rand -base64 48
openssl rand -hex 32

Después, inicie la base de datos por separado y ejecute las migraciones.

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 crea la imagen del equipo del bot, definida en package.json como docker build -t rakazo/computer:local infra/sandboxes/computer. Es una imagen gráfica, por lo que la primera compilación descarga muchos datos y tarda un tiempo. Confirme que se creó con docker image ls rakazo/computer, que debería mostrar una fila.

El archivo de Compose publica Postgres como 127.0.0.1:5433:5432, que sólo está disponible mediante loopback. Manténgalo así. Las credenciales de desarrollo son rakazo:rakazo y están en el repositorio. Un puerto de Postgres accesible desde Internet con una contraseña publicada aparece en los escáneres en cuestión de horas. El archivo de Compose de producción lee POSTGRES_PASSWORD en su lugar. Establézcalo como una cadena aleatoria cuando llegue a ese punto.

La primera ejecución

pnpm dev

Esto inicia cuatro componentes: la API en el puerto 3100, Graphile Worker, la aplicación web de Vite en 5173 y el supervisor del sandbox en 7091. La aplicación está disponible en http://127.0.0.1:5173 y debería mostrar una página de inicio de sesión.

En un VPS no se trabaja directamente desde esa máquina y no se debe publicar el puerto 5173 para acceder a la aplicación. En su lugar, reenvíe los puertos mediante SSH (secure shell) desde su propia máquina.

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

Tenga en cuenta la diferencia entre las dos formas de ejecutar la aplicación. pnpm dev ejecuta Vite en el host y lo enlaza localmente. El servicio web del archivo de Compose publica 5173:5173 en todas las interfaces. Si inicia toda la pila de desarrollo de Compose en un VPS público, la aplicación queda expuesta. Por tanto, use el archivo de producción y su reverse proxy para cualquier servicio que deje en ejecución.

¿Qué proveedor de sandbox es seguro en un servidor?

Esta es la única configuración que debe establecer correctamente. SANDBOX_PROVIDER en .env admite cuatro valores.

• docker es el valor predeterminado. Cada bot obtiene su propio contenedor en la máquina, creado a partir de la imagen producida por pnpm sandbox:build. Es la configuración autoalojada más rápida.
• e2b ejecuta los equipos de los bots en E2B y necesita E2B_API_KEY. El proyecto lo recomienda para implementaciones públicas o multiusuario, porque mantiene los equipos de los bots separados del host que ejecuta la API y la base de datos.
• desktop ejecuta directamente los comandos del bot en el host de la API y del worker. Las instrucciones del repositorio son claras: no lo use en un servidor público o compartido.
• fake es un emulador en proceso para pruebas. No es un entorno de ejecución.

Tome literalmente esa advertencia sobre el modo de escritorio. En el modo de escritorio no existe ningún límite de aislamiento, por lo que el bot ejecuta comandos de shell como el usuario que ejecuta el proceso de la API, con el directorio personal de ese usuario, sus claves SSH, sus credenciales de nube y sus .env. El texto de una página web que lee el bot se convierte en un comando en su servidor. Usar el modo de escritorio en un servidor es la forma de que un bot termine con sus credenciales. Úselo en una máquina frente a la que se siente, o no lo use. Cambiar de proveedor coloca un contenedor alrededor de esa ruta de la página web, pero no la cierra, y asignar al bot su propio backend de búsqueda SearXNG cubre la misma superficie de inyección desde el lado de las búsquedas.

docker es un límite real, aunque imperfecto. Un bot no puede leer los archivos de otro bot, porque cada uno tiene su propio contenedor. Sin embargo, el supervisor que crea esos contenedores monta /var/run/docker.sock, y controlar el socket de Docker del host equivale a controlar el host. Por eso, mantenga privado el supervisor. .env.example documenta SANDBOX_SUPERVISOR_TOKEN como una credencial de servicio independiente y opcional que usa BETTER_AUTH_SECRET de forma predeterminada cuando está vacía, lo que significa que dejar ese secreto con su marcador de posición protege el servicio que crea los contenedores con una cadena que cualquiera puede leer en GitHub. Establezca ambos valores. Para obtener la separación más sólida disponible aquí, use e2b o asigne a Rakazo una máquina que no contenga nada más. Ese es el mismo razonamiento que hay detrás de ejecutar agentes de programación en una máquina virtual desechable: la forma más barata de sobrevivir a que un agente haga algo incorrecto es que su máquina no tenga ningún valor.

¿Dónde se configuran las claves de API de los modelos?

Rakazo no gestiona la facturación de los modelos. Debe proporcionar usted la clave. .env.example establece PI_DEFAULT_PROVIDER=openrouter, por lo que OPENROUTER_API_KEY es la ubicación habitual, y las claves de los proveedores funcionan mediante la misma configuración.

Guarde la clave en .env y no la incluya en ningún archivo que confirme en git. Los dos comandos de compose del repositorio pasan --env-file .env, por lo que los valores llegan a los contenedores sin escribirse en archivos YAML que git rastrea. También puede dejar OPENROUTER_API_KEY vacío y pegar una clave en la aplicación durante la configuración inicial. Por eso ENCRYPTION_KEY debe tener un valor aleatorio real en lugar del marcador de posición incluido.

Establezca un límite de gasto para la clave en el proveedor antes de que ningún bot la use. Un bot que entra en un bucle es un bot que genera gastos, y un límite por clave es el único control que no depende de que usted lo supervise. Asigne a esta clave un nombre propio para poder revocarla de forma independiente. Si configura esto para un equipo en lugar de hacerlo para usted, la puerta de enlace única de OneCLI delante del agente de todos es otra solución para el mismo problema, porque mantiene las claves de los proveedores en un solo lugar en vez de tener una por persona.

Pasar del modo de desarrollo a una configuración que pueda dejar en ejecución

El repositorio incluye un archivo de Compose para producción que ejecuta Postgres, la API, el worker, la aplicación web y Caddy para los certificados TLS (seguridad de la capa de transporte) que obtiene automáticamente. Espera usar E2B para los equipos del 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 deshabilita el inicio de sesión SSH mediante contraseña, configura las reglas de UFW (firewall sin complicaciones) para SSH, HTTP y HTTPS, activa fail2ban y aplica perfiles de AppArmor. Léalo antes de ejecutarlo, porque cambia la forma de iniciar sesión. Mantenga abierta una segunda sesión SSH mientras se ejecuta.

El archivo .env de producción necesita más configuración que el de desarrollo. La documentación de instalación autónoma indica 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

Apunte un registro A al servidor antes de ejecutar por primera vez up. Caddy solicita un certificado para el nombre indicado en RAKAZO_HOST, y la solicitud falla si el nombre no resuelve a este equipo o si el puerto 80 está cerrado desde Internet.

Configure también SIGNUP_ALLOWLIST=you@example.com. SIGNUPS_ENABLED=true es el valor predeterminado, por lo que una instancia con un nombre público acepta registros de cualquier persona que la encuentre, y cada cuenta nueva obtiene un equipo. Configure primero una lista de permitidos. Puede relajarla más adelante si lo necesita. Si ya ejecuta varios servicios en el mismo equipo y prefiere mantener una sola lista de personas en lugar de una lista de permitidos por aplicación, colocar una instancia de Authentik delante de ellos traslada esa decisión al proxy, aunque se sitúa delante de las cuentas propias de Better Auth de Rakazo en lugar de sustituirlas.

Considere docs/self-host.md del repositorio como la fuente de autoridad para la configuración de producción, porque cambia junto con el código y esta guía no se actualiza al mismo ritmo. Como Compose se encarga de ejecutar los servicios, se aplican las reglas habituales, y los conceptos básicos de Docker Compose para un VPS explican por qué --env-file y los volúmenes con nombre adquieren más importancia cuando deja una pila sin modificar durante meses.

Copias de seguridad

Postgres y el directorio data/ constituyen la instancia completa.

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

backup.sh vuelca Postgres y archiva data/. En una máquina de la que dependa, instale infra/compose/backup-prod.sh como /usr/local/sbin/rakazo-backup con el temporizador que proporciona el repositorio, para que la rotación se realice automáticamente. Una copia de seguridad almacenada en el mismo disco que la base de datos no es una copia de seguridad, así que cópiela fuera del servidor. Después, restáurela una vez en un servidor de reserva, antes de necesitarla.

Por qué falla y qué verá

pnpm db:migrate no puede conectarse a la base de datos. La migración indica que no puede conectarse al servidor de base de datos en 127.0.0.1:5433. El contenedor de Postgres no está activo o todavía no está listo. Ejecute docker compose --env-file .env -f infra/compose/docker-compose.yml ps y busque que el servicio de postgres aparezca como saludable, porque el archivo compose le asigna una comprobación de estado que se ejecuta cada tres segundos. Si un contenedor se reinicia continuamente, normalmente significa que el volumen pgdata se creó con credenciales diferentes. docker compose ... down -v lo elimina junto con los datos.

El puerto ya está ocupado. La puesta en marcha de Postgres falla con bind: address already in use cuando otro proceso usa 5433, normalmente una pila de Rakazo anterior que olvidó detener. sudo ss -lntp | grep 5433 muestra el proceso.

Un bot nunca obtiene un equipo. Si se usan SANDBOX_PROVIDER=docker y no existe ninguna imagen rakazo/computer:local, no hay nada que iniciar. docker image ls rakazo/computer responde a esa situación en una línea y pnpm sandbox:build la corrige. Si el supervisor no puede acceder al socket de Docker, tampoco puede crear contenedores, y el mensaje muestra la ruta: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.

Un comando largo termina de forma prematura. .env.example establece SANDBOX_COMMAND_TIMEOUT_MS=300000, por lo que un solo comando dentro del equipo de un bot se interrumpe después de cinco minutos. Auméntelo para compilaciones lentas en lugar de asumir que el sandbox se bloqueó.

pnpm install falla de formas confusas. Compruebe node -v antes que nada. El espacio de trabajo declara >=22, y una versión antigua de Node falla en el código de las dependencias en lugar de mostrar un mensaje sobre las versiones.

El inicio de sesión funciona localmente, pero no a través del dominio. BETTER_AUTH_URL, WEB_ORIGIN y API_URL deben contener el mismo origen público que la barra de direcciones, incluido el esquema. Un http://127.0.0.1:5173 obsoleto en uno de ellos suele causar que la sesión nunca se mantenga.

Actualizar un checkout fijado

La ruta de actualización de la documentación para instalarlo por cuenta propia es breve: descargue el código fuente nuevo, ejecute la migración de la base de datos y reinicie la API y el 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

Haga primero una copia de seguridad. Las migraciones avanzan y una versión beta no ofrece una vía de reversión fiable. Lea los commits entre el SHA fijado y el nuevo antes de aplicarlos, porque un proyecto tan reciente cambia el nombre de las variables de entorno sin anunciarlo, y una variable ausente se manifiesta como un servicio que inicia y después termina. Si todavía está decidiendo si Rakazo es lo que realmente quiere ejecutar, el resumen de agentes de IA autohospedados explica qué otras opciones pertenecen a esta categoría y cuánto cuesta mantener cada una.

FAQ

¿Puedo ejecutar Rakazo en un VPS de 1 GB?

No. Postgres, la API, el worker, el supervisor del sandbox y la aplicación web se ejecutan al mismo tiempo. Además, con SANDBOX_PROVIDER=docker, cada bot activo añade un contenedor que incluye un escritorio gráfico y un navegador. La documentación del proyecto indica que 2 vCPU y 4 GB son suficientes para la API, el worker y Postgres sólo cuando E2B aloja los escritorios de los bots. Considere 4 GB como el mínimo para el plano de control y use más memoria cuando los escritorios se ejecuten en su máquina.

¿Es seguro usar el proveedor de sandbox de escritorio en un servidor?

No. desktop ejecuta directamente los comandos del bot en el host de la API y del worker, con el usuario que ejecuta ese proceso. Los archivos y las credenciales de ese usuario quedan accesibles. El repositorio indica que no debe usarse en un servidor público o compartido. Use docker para crear un contenedor por bot, o e2b cuando inicie sesión más de una persona.

¿Qué versión de Rakazo debo instalar?

A fecha de 16 August 2026 sólo hay una etiqueta, v0.1.0-beta, publicada el 13 August 2026 y marcada como prerelease. Extraiga el commit al que apunta, 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb, en lugar de seguir main. Una rama puede cambiar mientras la usa y una etiqueta puede reasignarse, por lo que ninguna identifica un árbol al que pueda volver. Registre el commit, porque sólo podrá revertir el despliegue si sabe cuál funcionaba.

¿Dónde coloco mi clave de API de OpenRouter?

En .env como OPENROUTER_API_KEY, y nunca en un archivo de compose que vaya a confirmar en el repositorio. Los dos comandos de compose del repositorio pasan --env-file .env, por lo que el valor llega a los contenedores sin escribirse en YAML versionado. También puede dejarlo vacío y pegar la clave en la aplicación durante la configuración inicial. Establezca un límite de gasto para la clave en el proveedor, porque un bot atrapado en un bucle seguirá llamando al modelo hasta que algo lo detenga.

¿Necesito un nombre de dominio y TLS?

Para cualquier uso posterior a una primera prueba, sí. El archivo de compose de producción ejecuta Caddy y obtiene los certificados automáticamente. Además, RAKAZO_HOST, BETTER_AUTH_URL, WEB_ORIGIN y API_URL deben usar el mismo origen HTTPS público. Para una primera comprobación puede omitir el dominio: ejecute pnpm dev y reenvíe el puerto 5173 mediante SSH en lugar de publicarlo.