En resumen. KoboldCpp es un programa gratuito de un solo archivo que ejecuta modelos de lenguaje GGUF en tu propio servidor y los ofrece mediante una interfaz web y una API. En un VPS descargas un binario y un archivo de modelo, y los lanzas dentro de tmux. Un servidor solo con CPU y 11 GiB de RAM ejecuta un modelo de prueba de 500 millones de parámetros. El límite estimado es de 7 a 8 mil millones.
¿Para qué sirve KoboldCpp?
KoboldCpp sirve para ejecutar modelos de lenguaje de pesos abiertos en hardware que tú controlas. Se usa sobre todo para escribir historias, jugar roleplay y chatear, y como backend de otras herramientas de IA. Se basa en llama.cpp, el motor de inferencia en C++ detrás de muchas herramientas locales de LLM, y está inspirado en el proyecto original KoboldAI. Lo mantiene un desarrollador conocido como Concedo (LostRuins en GitHub) bajo la licencia AGPLv3.
El programa viene en un solo archivo autónomo y carga archivos de modelo GGUF. Incluye KoboldAI Lite, una interfaz de navegador con modos de historia, chat, instruct y aventura. También ofrece una API compatible con OpenAI, así que herramientas como SillyTavern o tus propios scripts pueden usarlo como backend. Existen además funciones de imagen, voz y música. Son opcionales y esta guía no las cubre.
Ejecutarlo en un VPS te da un endpoint privado siempre activo. KoboldCpp corre el modelo en tu propio servidor. Su worker de AI Horde, que comparte tu capacidad de cómputo con otros usuarios, es opcional y hay que activarlo de forma explícita. Un equipo pequeño también puede compartir una instancia, porque KoboldCpp pone en cola las solicitudes entrantes.
¿Qué necesitas antes de empezar?
Necesitas un VPS con Linux, un cliente SSH en tu computadora y cerca de 1 GB de espacio libre en disco para el binario y el modelo de prueba.
- Entorno probado: Ubuntu 24.04 con 6 vCPUs y 11 GiB de RAM, con KoboldCpp 1.122.1.
- Acceso: un inicio de sesión como root. Si usas un usuario normal, antepón
sudoal comandoaptdel paso 3. - Cliente SSH: los pasos marcados como «en tu computadora» usan PowerShell en Windows. Las terminales de macOS y Linux funcionan igual.
La RAM decide qué modelos caben, porque el archivo del modelo debe entrar en memoria con espacio de sobra para el contexto. Esta guía empieza con un modelo de 500 millones de parámetros, que sirve como prueba rápida. Como estimación, un modelo de 7 a 8 mil millones de parámetros con cuantización de 4 bits es el límite realista con 11 GiB. La generación en CPU es lenta, así que toma esta configuración como una forma de probar el stack, no como un servicio de chat para muchos usuarios.
Cómo desplegar KoboldCpp en un VPS
Despliegas KoboldCpp en ocho pasos: conectarte, revisar los recursos, instalar herramientas, descargar el binario y un modelo, iniciarlo en tmux, verificar y abrir la interfaz web mediante un túnel SSH.
Paso 1: Conéctate (en tu computadora). Ejecuta ssh root@YOUR_SERVER_IP y escribe yes cuando aparezca el aviso de la huella digital. Si SSH advierte que la identificación del host remoto cambió, algo que pasa después de reinstalar el VPS, elimina primero la llave anterior y vuelve a conectarte:
ssh-keygen -R YOUR_SERVER_IP
ssh root@YOUR_SERVER_IPPaso 2: Revisa los recursos (en el VPS). Este comando muestra la memoria, el espacio en disco y el número de CPU:
free -h && df -h / && nprocPaso 3: Instala las herramientas y crea las carpetas.
apt update && apt install -y curl tmux
mkdir -p ~/koboldcpp/models && cd ~/koboldcppPaso 4: Descarga KoboldCpp. Las notas de la versión KoboldCpp 1.122.1 listan tres builds para Linux. Esta guía usa el build para CPU, que pesa unos 130 MB.
| Archivo | Úsalo para |
|---|---|
koboldcpp-linux-x64 | Servidores con GPU NVIDIA (build con CUDA) |
koboldcpp-linux-x64-nocuda | Servidores sin GPU NVIDIA, descarga más pequeña |
koboldcpp-linux-x64-oldpc | CPU antiguas o GPU NVIDIA antiguas (CUDA 11 y AVX1) |
curl -fLo koboldcpp https://github.com/LostRuins/koboldcpp/releases/latest/download/koboldcpp-linux-x64-nocuda
chmod +x koboldcppLas versiones nuevas pueden cambiar los flags. Para fijar la versión probada, reemplaza latest/download en la dirección por download/v1.122.1.
Paso 5: Descarga el modelo de prueba. El modelo es Qwen2.5-0.5B-Instruct con cuantización Q4_K_M. En Hugging Face, la dirección de la página de un archivo contiene /blob/, que es una página de vista previa. Reemplaza /blob/ por /resolve/ para obtener el enlace de descarga directa:
curl -fLo models/test.gguf "https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct-GGUF/resolve/main/qwen2.5-0.5b-instruct-q4_k_m.gguf"
ls -lh modelsEl listado debe mostrar test.gguf con unos 469M. Un archivo de solo unos kilobytes significa que descargaste una página /blob/.
Paso 6: Inicia KoboldCpp en tmux. La sesión de tmux mantiene KoboldCpp en ejecución aunque cierres SSH.
tmux new -s kobold
./koboldcpp --model ./models/test.gguf --usecpu --host 127.0.0.1 --port 5001 --contextsize 2048Los flags cumplen cinco funciones: --model indica el archivo GGUF, --usecpu mantiene el trabajo en el procesador, --host define la dirección de escucha, --port define el puerto y --contextsize 2048 limita la memoria para el contexto, que por defecto es de 16,384. Define siempre --host. En la versión 1.122.1, un inicio sin este flag también aceptaba conexiones en la dirección de red del servidor, aunque el log muestre localhost. Cuando el modelo está listo, el log termina así:
Load Text Model OK: True
Please connect to custom endpoint at http://127.0.0.1:5001Paso 7: Sal de la sesión y verifica. Presiona Ctrl+B, suelta ambas teclas y luego presiona D. KoboldCpp sigue corriendo en segundo plano. Después comprueba que responda:
curl http://localhost:5001/api/extra/versionLa respuesta empieza con {"result": "KoboldCpp", "version": "1.122.1" y continúa con más campos.
Paso 8: Abre la interfaz web (en tu computadora). En una ventana nueva de PowerShell, abre un túnel SSH. Este redirige el puerto 5001 de tu computadora al puerto privado del servidor:
ssh -L 5001:localhost:5001 root@YOUR_SERVER_IPDeja esa ventana abierta y entra a http://localhost:5001 desde el navegador.
Cómo usar y detener el servidor en ejecución
Lo usas mediante tres direcciones en tu túnel y lo administras con tmux. http://localhost:5001/ abre KoboldAI Lite, http://localhost:5001/lcpp/ abre la interfaz de llama.cpp incluida y http://localhost:5001/api muestra la documentación de la API. Para probar la generación, elige Instruct en el menú desplegable Format, dentro de Basic Settings, y envía un prompt corto. El log también lista una API compatible con OpenAI en /v1/, que esta guía no prueba.
| Tarea | Comando |
|---|---|
| Salir de la sesión y dejarlo corriendo | Ctrl+B, soltar y luego D |
| Volver a la sesión | tmux attach -t kobold |
| Detener KoboldCpp | Vuelve a la sesión y presiona Ctrl+C |
| Reiniciar | Presiona la flecha hacia arriba en la misma sesión y ejecuta de nuevo el comando de inicio |
| Eliminar la sesión | tmux kill-session -t kobold |
¿KoboldCpp necesita CPU o GPU?
KoboldCpp funciona solo con CPU, pero una GPU acelera la generación cuando los modelos crecen. En CPU, los pesos del modelo viven en la RAM del sistema y el procesador los lee para cada token. Con GPU offloading, las capas pasan a la VRAM de la tarjeta, donde el hardware paralelo las procesa mucho más rápido.
Tres flags controlan esto. --usecpu mantiene todo en el procesador, --usecuda o --usevulkan activa la aceleración por GPU y --gpulayers define cuántas capas se mueven a la tarjeta. El texto de --help en la versión 1.122.1 indica -1 como valor por defecto de --gpulayers, lo que deja que KoboldCpp elija de forma automática. Empieza con CPU si tu modelo es pequeño y está cuantizado, y si puedes tolerar respuestas lentas. Pasa a una GPU cuando quieras respuestas que se sientan interactivas o necesites un modelo más grande.
Dimensiona el servidor según el modelo que planeas ejecutar, porque el archivo del modelo y su contexto deben caber en memoria. El wiki de KoboldCpp da una guía aproximada para modelos cuantizados a 4 bits con un contexto de 2,048 tokens: al menos 8 GB de RAM para un modelo de 7 mil millones de parámetros, 16 GB para 13 mil millones, 32 GB para 30 mil millones y 64 GB para 65 mil millones. El contexto por defecto en la versión 1.122.1 es de 16,384, así que deja margen o baja --contextsize. Para una configuración solo con CPU, Cloud VPS es una buena opción. Elige según la RAM. Escoge Performance VPS si quieres almacenamiento NVMe para cargar los modelos más rápido, o Max Performance VPS si quieres recursos dedicados para una velocidad de generación más estable. Más núcleos también ayudan, porque el wiki recomienda fijar el número de threads cerca de la cantidad de núcleos físicos.
Para modelos más grandes o respuestas más rápidas, GPU VPS combina una NVIDIA RTX PRO 6000 dedicada (96 GB de VRAM, compatible con CUDA) con 18 vCPUs y 96 GB de RAM. Así, los pesos viven en la VRAM y no en la RAM del sistema. Como estimación, un modelo de 70 mil millones de parámetros necesita unos 40 GB para sus pesos con cuantización de 4 bits, más memoria para el contexto, así que cabe en esa sola tarjeta.
¿Qué haces si algo sale mal?
La mayoría de los problemas vienen de SSH, de las descargas del modelo o de la memoria. La tabla cubre los que aparecieron durante las pruebas.
| Síntoma | Causa probable | Solución |
|---|---|---|
| SSH advierte que la identificación del host remoto cambió | Reinstalaste el VPS, así que cambió la llave del servidor | Ejecuta ssh-keygen -R YOUR_SERVER_IP y vuelve a conectarte |
| El archivo del modelo pesa solo unos kilobytes | Usaste un enlace /blob/ | Reemplaza /blob/ por /resolve/ y descarga de nuevo |
| El túnel falla con «Address already in use» | El puerto 5001 está ocupado en tu computadora | Usa ssh -L 5002:localhost:5001 root@YOUR_SERVER_IP y entra a http://localhost:5002 |
Aparece Killed y KoboldCpp se cierra | Al servidor se le acabó la memoria | Elige un modelo o una cuantización más pequeños, o baja --contextsize |
| La interfaz web no carga en el navegador | La ventana del túnel está cerrada, o KoboldCpp no está en ejecución | Mantén abierta la ventana SSH y repite la verificación del paso 7 |
¿Qué sigue?
Prueba un modelo más grande, hasta el límite de tu RAM, y compara sus respuestas con las del modelo de prueba. La velocidad baja conforme crecen los modelos, así que mide cuánto tarda una respuesta antes de quedarte con uno. Si abres el puerto en lugar de usar un túnel, define --password y restringe el puerto a tu propia dirección IP en el Firewall de Contabo. Ejecutar KoboldCpp como servicio de systemd también es posible, pero esta guía no lo cubre.
FAQ: KoboldCpp en tu propio servidor
¿KoboldCpp necesita una GPU para funcionar?
No. KoboldCpp funciona solo con CPU cuando lo inicias con --usecpu, lo que convierte a un VPS con mucha RAM en un host válido para modelos pequeños. Un Cloud VPS con CPU alcanza para modelos comunes y necesidades pequeñas. Una GPU, usada con --usecuda o --usevulkan junto con --gpulayers, es el camino hacia modelos más grandes y respuestas más rápidas.
¿KoboldCpp es gratuito?
Sí. KoboldCpp es software gratuito y de código abierto bajo la licencia AGPLv3, y puedes descargar el binario ya compilado o compilarlo desde el código fuente sin costo. Solo pagas el servidor donde lo ejecutas y dedicas tiempo a la configuración. Los archivos de modelo se descargan por separado y cada modelo tiene su propia licencia, así que revisa los términos antes de usar uno con fines comerciales.
¿Qué formatos de modelo admite KoboldCpp?
Para modelos de texto, KoboldCpp carga archivos GGUF y mantiene compatibilidad con el formato anterior, GGML. Otros formatos, como safetensors y los archivos .bin de PyTorch, no tienen soporte nativo y primero hay que convertirlos a GGUF. Encuentras archivos GGUF listos en Hugging Face, normalmente en varios niveles de cuantización, desde variantes pequeñas y rápidas hasta otras más grandes y de mayor calidad.
¿Cómo mantengo privado un servidor KoboldCpp?
Define --host 127.0.0.1 y accede al servidor mediante un túnel SSH. En la versión 1.122.1, un inicio sin --host también aceptaba conexiones en la dirección de red del servidor, aunque el log mostraba localhost. Si abres el puerto de todos modos, define --password, que protege los endpoints de texto pero no los de imagen, y restringe el puerto a tu propia dirección IP en el Firewall de Contabo.
