Cómo autoalojar open-kritt para escanear código con IA

Por qué ejecutar open-kritt en un VPS y no en tu portátil

Ejecuta open-kritt en un servidor que puedas destruir y reconstruir. La herramienta ejecuta sus agentes de análisis como root dentro de contenedores de trabajo desechables, proporciona a cada uno una copia escribible de tu código y acceso directo a Internet, y monta el socket Docker del host en su servicio de motor. Este riesgo puede ser aceptable en un equipo dedicado a esa tarea. No lo es en el equipo que contiene tus claves SSH.

Cuatro propiedades de la configuración predeterminada justifican esta recomendación. Las cuatro proceden del propio README y del archivo compose del proyecto.

Los agentes están diseñados para tener amplios privilegios. El README indica que los agentes con herramientas se ejecutan como root dentro de contenedores de trabajo desechables, con copias escribibles de los repositorios y acceso directo a Internet. Así pueden instalar herramientas, compilar objetivos, ejecutar pruebas y crear pruebas de concepto. Un análisis no consiste en que un linter lea archivos. Es una ejecución arbitraria de código que has solicitado. Ese acceso a Internet tiene riesgos en ambos sentidos: cualquier contenido que un agente descargue al investigar un objetivo es texto no confiable que entra en su prompt. Es la misma exposición que aceptas cuando das a un agente su propia búsqueda web.

El motor tiene acceso al socket Docker. docker-compose.yml monta el socket Docker del host en el servicio de motor porque el motor crea e inicia un contenedor de análisis por cada trabajo. Cualquier proceso que pueda acceder a ese socket puede iniciar un contenedor que monte el sistema de archivos del host. Por tanto, el motor tiene de facto privilegios root sobre el host donde se ejecuta.

No hay pantalla de inicio de sesión. El backend se distribuye sin autenticación de aplicación. Tener acceso al puerto equivale a tener acceso a tus resultados y al crédito de tu proveedor.

El código que analizas a menudo no es tuyo. Dirigir los agentes a un repositorio de terceros implica ejecutar la compilación de ese repositorio en tu equipo, como root y con acceso a la red.

Si has leído por qué los agentes de programación deben ejecutarse en una VM desechable, este es el mismo modelo de amenazas, pero más intenso. Proporciona a open-kritt un VPS que no aloje nada más y administra ese VPS desde una cuenta de usuario independiente con privilegios mínimos en lugar de root.

Qué hace realmente open-kritt

open-kritt (el repositorio es Kritt-ai/open-kritt y usa la licencia AGPL-3.0) divide la investigación de vulnerabilidades en tareas pequeñas, ejecuta esas tareas en paralelo mediante agentes de IA y después elimina duplicados y clasifica los resultados. Se define un flujo de trabajo como una cadena de indicaciones específicas, y cada paso recibe contexto estructurado de los pasos anteriores. El objetivo del análisis es un repositorio git remoto o local. El motor de análisis es Codex o Claude Code. Cuando aparece un candidato, unos scripts posteriores opcionales pueden intentar validarlo o crear una prueba de concepto.

Al final se obtiene una lista clasificada de candidatos. Debe tratarse como una cola de triaje, no como un informe.

Qué necesita antes de empezar

• Un VPS con Ubuntu 24.04, Debian 12 o Rocky Linux 9. La documentación de instalación indica que son las distribuciones probadas, en x86_64 y ARM64.
• Docker Engine con el complemento Compose.
• Node.js 20 o posterior en el host, porque la CLI ./kritt se ejecuta en el host y no dentro de un contenedor.
• Un proveedor de modelos: un inicio de sesión de Codex, o OPENAI_API_KEY, CODEX_API_KEY, ANTHROPIC_API_KEY o OPENROUTER_API_KEY.
• GITHUB_TOKEN sólo si planea analizar repositorios privados. El .env.example incluido lo indica claramente: un token de GitHub por sí solo no permite ejecutar análisis.

Instale primero Docker y Node 20

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

Cierre la sesión y vuelva a iniciarla para aplicar la nueva pertenencia al grupo. Después, confirme que el complemento Compose está disponible.

docker compose version

Una cadena de versión indica que Compose está instalado como complemento. docker: 'compose' is not a docker command indica que, en su lugar, tiene el binario independiente antiguo docker-compose, y open-kritt llama a docker compose. La pertenencia al grupo docker equivale a tener acceso root en el host. Por tanto, añada únicamente a este grupo la cuenta que ejecuta open-kritt. Para consultar la versión más extensa de esta configuración, consulte ejecutar Docker en un VPS.

Ubuntu 24.04 incluye Node 18 en su propio repositorio, pero la CLI se cierra con cualquier versión inferior a 20. Use NodeSource.

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node -v

node -v debe mostrar v20. o una versión posterior. En Rocky Linux 9, el equivalente es sudo dnf module enable nodejs:20 -y seguido de sudo dnf install -y nodejs.

Clonar open-kritt y fijar una versión etiquetada

git clone https://github.com/Kritt-ai/open-kritt
cd open-kritt
git fetch --tags
git tag --list
git checkout v1.3.0

main cambia con el tiempo. Una etiqueta no cambia. En agosto de 2026, la etiqueta más reciente es v1.3.0, publicada el 4 de agosto de 2026, y git tag --list muestra lo que existe el día en que se clona el repositorio. Al cambiar a una etiqueta, el repositorio queda en estado HEAD separado. Esto es correcto en este caso: se trata este clon como una implementación fijada, no como una rama en la que se realizan commits. Para actualizarlo más adelante, lea las notas de la versión, ejecute git fetch --tags, cambie a la etiqueta nueva y ejecute ./kritt start de nuevo, porque start vuelve a crear las imágenes.

No ejecute ./kritt con sudo. La documentación lo indica explícitamente. La CLI administra los directorios de credenciales locales del proyecto en .data/. Por tanto, si se ejecuta como root, esos directorios quedan propiedad de root y la siguiente ejecución normal no puede escribir en ellos.

Configurar el acceso a los modelos con ./kritt setup

./kritt setup

El comando crea .env a partir de .env.example cuando no existe, muestra el estado de cada credencial y permite configurarlas o eliminarlas. Nunca muestra sus valores en la terminal. Tanto .env como el archivo de credenciales del motor se escriben con el modo 0600.

Si prefiere hacerlo manualmente:

cp .env.example .env
chmod 600 .env
mkdir -p .data/codex
chmod 700 .data/codex

A continuación, edite la clave del proveedor en .env y mantenga el archivo con el modo 0600. En ambos casos, el servidor tendrá una credencial válida del proveedor. Por eso es preferible que no aloje nada más. Cree una clave exclusiva para este proyecto. Así, revocarla más adelante no afectará a otros servicios importantes. Mantener los secretos fuera del alcance de los agentes de IA explica esta práctica con más detalle.

Establezca un límite de gasto del proveedor antes del primer análisis

open-kritt está diseñado para distribuir el trabajo, y esa distribución es lo que genera el coste. Los valores predeterminados de .env.example en v1.3.0 son conservadores: ENGINE_WORKER_COUNT=2, descrito en el archivo como un valor predeterminado conservador para una máquina pequeña con 2 vCPU, y ENGINE_MAX_CONCURRENT_SCANS=1. Por encima de ellos están ENGINE_WORKERS_PER_ACCOUNT=15, el número máximo de llamadas simultáneas al modelo principal permitidas en una cuenta de proveedor, y ENGINE_CODEX_MAX_SUBAGENTS_PER_SESSION=5, porque una sesión de Codex puede ejecutar hasta cinco agentes secundarios. Si aumenta el número de workers en un VPS más grande, también aumenta el número de llamadas al modelo en curso.

El repositorio no limita el gasto. .env.example no incluye ningún ajuste de presupuesto. Las propias condiciones de parada del motor son esos límites de workers y ENGINE_HARNESS_TIMEOUT_SECONDS, que establece de forma predeterminada 7200 segundos por ejecución del harness. Por tanto, el límite debe configurarse en el proveedor. Abra la consola del proveedor y establezca un límite mensual estricto antes del primer análisis, no después. Controlar el coste de un agente de IA en un VPS explica la configuración de cada proveedor.

También existe un freno local. Establecer ENGINE_WORKER_COUNT=0 pausa la recogida de trabajos nuevos, y puede cambiar los mismos valores de workers en la pantalla Settings cuando el stack esté en ejecución.

Esta guía no indica un precio por análisis, porque el coste depende del tamaño del repositorio, del workflow que cree y del modelo que utilice. Ejecute un análisis contra un repositorio pequeño y, después, consulte la página de uso del proveedor antes de analizar algo grande.

Inicie la pila y compruebe que está funcionando correctamente

./kritt start

Esto comprueba .env y al menos una credencial, y después ejecuta docker compose up --build. La primera compilación es lenta porque genera las imágenes del frontend, el backend, el motor, la vista del ejecutor y la base de datos. También se ejecuta en primer plano, por lo que cerrar la sesión SSH detiene la pila. Iníciela dentro de tmux o ejecútela en segundo plano una vez que la primera compilación haya terminado correctamente. Ninguna de estas opciones sobrevive por sí sola a un reinicio. Si quiere que la pila vuelva a iniciarse después de reiniciar el equipo, el patrón de unidad de systemd descrito en mantener un agente autohospedado en ejecución tras los reinicios se puede aplicar directamente.

docker compose up -d --build
docker compose ps

docker compose ps debe mostrar open-kritt-frontend, open-kritt-backend, open-kritt-engine, open-kritt-executor-view y open-kritt-db. Después, compruebe que el backend responde en el propio servidor.

curl -s http://127.0.0.1:3002/api/health

Una respuesta JSON indica que el backend está activo. Failed to connect to 127.0.0.1 port 3002: Connection refused indica que no lo está, y docker compose logs backend mostrará la causa. Detenga todo con docker compose down desde el directorio del repositorio.

Una opción adicional: docker compose exec backend npm run seed carga datos de demostración. Es una forma sencilla de revisar la interfaz antes de gastar dinero en un análisis real.

Acceda a la interfaz en el puerto 5173 mediante un túnel SSH

Todos los servicios del archivo compose se enlazan a 127.0.0.1 de forma predeterminada: el frontend en 5173, el backend en 3002, la vista del executor en 8090 y PostgreSQL en 5432. Mantenga esos enlaces sin cambios y reenvíe el puerto mediante SSH desde su propio equipo.

ssh -N -L 5173:127.0.0.1:5173 you@your-server-ip

Abra http://localhost:5173 en el navegador local mientras se ejecuta ese comando. -N indica que la conexión transporta el reenvío y no abre un shell. Añada un segundo -L 8090:127.0.0.1:8090 al mismo comando cuando también necesite la vista del executor.

La opción más tentadora es configurar FRONTEND_BIND_ADDRESS=0.0.0.0 y omitir el túnel. No lo haga. El backend no tiene pantalla de inicio de sesión, por lo que cualquiera que acceda a esa página puede iniciar análisis y consumir el crédito de su proveedor. Hay otro problema menos evidente: los puertos publicados de los contenedores se procesan antes de que se aplique la política predeterminada de ufw, por lo que una regla ufw deny 5173 parece correcta, pero no bloquea nada. Puertos de Docker que omiten ufw muestra la cadena de reglas que lo provoca.

Dimensionamiento del VPS

ENGINE_MIN_FREE_STORAGE_GB tiene un valor predeterminado de 20, y el motor no inicia un contenedor de análisis nuevo por tarea cuando el almacenamiento libre es inferior a ese valor. Las imágenes creadas, la caché de checkout, los datos de Postgres y los espacios de trabajo de las tareas se encuentran en el mismo disco, por lo que un VPS de 20 GB nunca inicia un análisis. Considere 40 GB como el mínimo y asigne más espacio si analiza repositorios grandes.

La memoria se calcula con una aritmética sencilla. ENGINE_MEMORY_RESERVE_GB=2 reserva memoria para el motor, la base de datos, la API y la sobrecarga temporal, y cada ejecutor de análisis tiene una reserva y un límite máximo de ENGINE_SCAN_RUNNER_MEMORY_MB=1536. Por tanto, dos workers necesitan unos 5 GB antes de ejecutar cualquier otra cosa. El motor sólo admite los ejecutores que caben en el presupuesto restante, por lo que en un servidor pequeño los análisis se ponen en cola en lugar de fallar. Es un comportamiento mucho mejor que la intervención del OOM killer.

Dos opciones de limpieza tienen el valor predeterminado true: ENGINE_AUTO_PRUNE_DOCKER_BUILD_CACHE y ENGINE_AUTO_PRUNE_UNUSED_DOCKER_IMAGES. Cuando termina una tarea, el motor elimina la caché de compilación no utilizada, las imágenes no utilizadas y los contenedores de análisis detenidos. Se conservan las imágenes utilizadas por un contenedor en ejecución, los bind mounts, los datos de la base de datos, las credenciales y los volúmenes. Es otra razón para no compartir el host: un proceso de limpieza que no configuró está actuando sobre ese Docker daemon.

Analizar un repositorio local sin exponerlo

LOCAL_REPOS_PATH se establece de forma predeterminada en ./local_repos y se monta mediante bind mount en los contenedores backend y engine en /local_repos, por lo que un repositorio que coloque en esa carpeta del host aparece de inmediato dentro de los contenedores. Use un clon nuevo, no su árbol de trabajo. El contenedor del trabajo obtiene una copia con permisos de escritura, tiene acceso como root dentro de sí mismo y acceso saliente a Internet. Por tanto, cualquier elemento de esa copia se puede modificar o enviar fuera del equipo. Elimine los archivos .env y las claves privadas antes de copiar un proyecto.

Lo que recibe y lo que no

Recibe hallazgos candidatos ordenados por prioridad. No recibe vulnerabilidades verificadas. La ordenación y la deduplicación determinan el orden de la cola de triaje. No demuestran que una entrada sea real. Los post-scripts pueden intentar validar el hallazgo y crear una prueba de concepto. Esa es la señal más sólida que ofrece la herramienta. Sin embargo, que un post-script falle no demuestra que el hallazgo sea falso. Una persona debe revisar cada candidato.

Esta guía no afirma cuántos errores reales encuentra open-kritt porque no lo hemos medido. Quien cite una tasa de detección para su base de código no la ha ejecutado contra su base de código. Empiece por analizar un repositorio que ya conozca bien. Los hallazgos que pueda evaluar personalmente son la calibración más económica disponible.

La autorización es más importante en este caso que con la mayoría de las herramientas autoalojadas. Los agentes compilan y ejecutan código, y acceden a la red. Por tanto, un paso de prueba de concepto puede interactuar con sistemas en producción. Apunte la herramienta a código de su propiedad o cuyo análisis tenga contratado, y documente el alcance del objetivo antes de ejecutar cualquier acción. Si configura ANTHROPIC_API_KEY y usa el motor Claude Code, los hábitos de aislamiento descritos en ejecutar Claude Code de forma segura en un VPS también se aplican a estos agentes.

FAQ

¿Por qué open-kritt necesita su propio VPS?

Porque sus agentes de análisis se ejecutan como root dentro de contenedores de trabajo desechables, con copias modificables de su código y acceso directo a Internet. Además, el servicio del motor monta el socket de Docker del host para poder iniciar un contenedor por trabajo. Cualquier proceso que acceda a ese socket puede iniciar un contenedor que monte el sistema de archivos del host. Por tanto, debe tratar toda la pila como root en ese host. En un VPS dedicado, este intercambio es aceptable y reconstruir el servidor no tiene coste. En su estación de trabajo habitual, las claves SSH y los perfiles del navegador quedan dentro del mismo límite de confianza que el código que está analizando.

¿Puedo exponer el puerto 5173 en lugar de usar un túnel SSH?

No debería hacerlo. El backend se distribuye sin autenticación de aplicación. Por tanto, el puerto es la única barrera entre Internet, los resultados de sus análisis y el crédito de su proveedor. El archivo compose enlaza todos los servicios con 127.0.0.1 por ese motivo. Ejecute ssh -N -L 5173:127.0.0.1:5173 you@your-server-ip y acceda localmente a http://localhost:5173. Una regla de ufw no sustituye esta medida, porque un puerto publicado por Docker se procesa antes de que se aplique la política predeterminada de ufw.

¿Cómo puedo evitar que open-kritt gaste más de lo previsto?

Establezca un límite estricto en la consola de su proveedor de modelos antes del primer análisis, porque open-kritt no tiene su propia configuración de presupuesto. Mantenga los valores de concurrencia distribuidos de forma predeterminada durante las primeras ejecuciones, ENGINE_WORKER_COUNT=2 y ENGINE_MAX_CONCURRENT_SCANS=1, y recuerde que una cuenta de proveedor permite de forma predeterminada hasta 15 llamadas simultáneas al modelo root, mientras que una sesión de Codex puede ejecutar hasta cinco agentes secundarios. ENGINE_WORKER_COUNT=0 detiene la recogida de trabajos nuevos y es la forma más rápida de detenerlo localmente.

¿Qué versión debo obtener?

Una etiqueta, nunca main. git fetch --tags seguido de git tag --list muestra lo que está disponible, y v1.3.0, publicado el 4 de agosto de 2026, es la versión más reciente en el momento de redactar este texto. Fijar la versión garantiza que una reconstrucción realizada meses después produzca la misma pila. También convierte la actualización en una decisión que toma después de leer las notas de la versión, en lugar de dejarla como efecto secundario de clonar en otro día.

Un análisis nunca se inicia. ¿Qué debo comprobar?

Compruebe primero el espacio libre en disco, porque el motor no iniciará un contenedor de análisis por trabajo cuando el almacenamiento libre sea inferior a ENGINE_MIN_FREE_STORAGE_GB, cuyo valor predeterminado es 20 GB. Después, compruebe que ENGINE_WORKER_COUNT no sea 0, porque ese valor detiene la recogida de trabajos nuevos. Luego confirme que realmente hay una credencial de modelo configurada mediante ./kritt setup, porque un GITHUB_TOKEN por sí solo no puede ejecutar análisis. docker compose logs engine indica el motivo por el que se omitió el trabajo.