FreeLLMAPI en tu VPS: Claude Code con modelos gratuitos

Qué es FreeLLMAPI y qué no es

FreeLLMAPI es un servidor que instalas tú en tu VPS (servidor privado virtual). Junta las capas gratuitas de varios proveedores de modelos de lenguaje detrás de una sola API. Entre esos proveedores están Groq, Google AI Studio, Mistral, Cerebras y OpenRouter. El servidor habla el formato de OpenAI y también el formato Messages de Anthropic, así que Claude Code puede usarlo como si fuera la API de Anthropic. El modelo que responde, en cambio, no es Claude. Es el modelo gratuito que el router de FreeLLMAPI elige en ese momento.

Si llegaste aquí buscando «Claude gratis», esta es la respuesta corta. Claude Code, el programa de terminal, puede funcionar sin pagar a Anthropic. Claude, el modelo, no está en el catálogo. Al consultar el catálogo público en freellmapi.co/models el 12 de octubre de 2026, no aparece ningún modelo de Anthropic. Hay modelos de Google, Mistral, Meta, Qwen, DeepSeek, Cohere y muchos más, pero ninguno se llama Claude. Para saber qué da Anthropic sin coste en su propia plataforma, lee lo que incluye de verdad la capa gratuita de la API de Claude.

Esta guía instala FreeLLMAPI con Docker Compose en un VPS con Ubuntu 24.04 y conecta Claude Code desde tu portátil, con el panel cerrado a internet. Antes de los comandos, dedica unos minutos a la parte que casi nadie lee: qué pagas cuando no pagas con euros ni con pesos.

Por qué existe la cadena de respaldo y qué es un 429

Cada capa gratuita tiene límites por minuto y por día. Cuando los superas, el proveedor responde con el código HTTP 429, que significa «Too Many Requests» (demasiadas peticiones). Si solo tienes una clave de un solo proveedor, tu sesión de Claude Code se detiene en ese momento.

FreeLLMAPI guarda tus claves de varios proveedores y cuenta el uso de cada una. Cuando un proveedor está limitado, el router pasa la petición al siguiente de la lista. Esa lista es la cadena de respaldo, en inglés «failover chain». El resultado práctico es importante: dos peticiones seguidas pueden recibir respuesta de dos modelos distintos, de dos empresas distintas. La cabecera x-routed-via de cada respuesta indica por dónde se enrutó la petición. Más abajo verás cómo leerla.

El propio README del proyecto lo describe sin adornos: son capas gratuitas con límites reales y sin SLA (acuerdo de nivel de servicio). A última hora del día baja la calidad disponible, porque los mejores modelos agotan sus cuotas diarias.

Lo que cuesta lo gratis: tus datos y las condiciones de cada proveedor

Cada proveedor tiene sus propias condiciones para la capa gratuita, y FreeLLMAPI no las cambia. El README lo dice así: «Your relationship with each upstream provider is governed by the terms you accepted when you created your account». Es decir, las condiciones que aceptaste al crear cada cuenta siguen vigentes aunque el tráfico pase por tu servidor.

Esto importa más con Claude Code que con un chat. Claude Code lee archivos de tu repositorio y los envía como contexto al modelo. Por eso, todo lo que haya en ese repositorio puede acabar en el proveedor que responda: código de un cliente, un archivo .env, una clave olvidada en un script o un volcado de la base de datos.

Estas son las condiciones de los proveedores que nombra esta guía, consultadas el 12 de octubre de 2026. Léelas tú también antes de añadir cada clave, porque cambian.

• Google AI Studio (Gemini API). Los términos adicionales de la Gemini API llaman «Unpaid Services» a la cuota gratuita. Para esa cuota, Google dice que usa el contenido que envías y las respuestas generadas «to provide, improve, and develop Google products and services and machine learning technologies». También dice que revisores humanos pueden leer y anotar la entrada y la salida, y pide no enviar información sensible, confidencial o personal. Hay una excepción que afecta a España: en el Espacio Económico Europeo, Suiza y el Reino Unido, las condiciones de uso de datos de los servicios de pago se aplican a todos los servicios, incluida la cuota gratuita. Desde México, Colombia, Argentina o Chile se aplica la versión de la cuota gratuita.
• Mistral. El centro de ayuda de Mistral, actualizado el 31 de agosto de 2026, dice sobre el modo gratuito de Mistral AI Studio, la plataforma de su API: «we may use your data (input and output) to train our artificial intelligence models». Su política de privacidad dice que puedes oponerte a ese uso desde los ajustes de tu cuenta, y otro artículo de ayuda sitúa el interruptor en el menú Privacy de admin.mistral.ai, bajo «Anonymous improvement data». Si no lo desactivas, tus prompts pueden servir para entrenar. Además, la retención de 30 días es la norma general, no una excepción: salvo en APIs concretas, la política de privacidad dice que Mistral guarda la entrada y la salida el tiempo necesario para generar la respuesta «and then for thirty (30) rolling days to monitor abuse (unless zero data retention is activated)». Si usas la API de agentes (Agents API), las guarda hasta que cierras la cuenta.
• OpenRouter. OpenRouter enruta hacia muchos proveedores, y algunos entrenan con los datos según su propia política. Su documentación explica que en los ajustes de la cuenta eliges si permites proveedores que puedan entrenar con tus datos. Hay ajustes separados para modelos de pago y para modelos gratuitos. Si desactivas el entrenamiento, OpenRouter no enruta hacia proveedores que entrenan, así que algunos modelos gratuitos pueden quedar fuera.
• Groq. Su página sobre datos dice: «By default, Groq does not retain customer data for inference requests». Guarda datos hasta 30 días en casos concretos, como trabajos por lotes o investigación de abuso. Permite activar la retención cero (Zero Data Retention) en los ajustes. Esa página no dice nada explícito sobre entrenamiento.
• Cerebras. Su artículo de soporte sobre retención dice que no guarda «Prompt content, API requests or responses», ni registros de chat, ni la entrada o salida del modelo. Solo conserva datos de cuenta y métricas de uso.

La regla práctica sale de esa lista. Con un proveedor que puede entrenar con tus datos, trabaja solo en repositorios que podrías publicar mañana. Para código de clientes o datos personales, usa un proveedor que no retiene datos, o una API de pago.

Varias cuentas en el mismo proveedor

FreeLLMAPI permite cargar varias claves y cuenta el uso de cada una. Es tentador abrir tres cuentas en el mismo proveedor para triplicar la cuota. Las condiciones de uso suelen prohibir justo eso, porque es una forma de eludir los límites que el proveedor puso a propósito. Si el proveedor lo detecta, puedes perder todas las cuentas, no solo la última. Por eso el README define el proyecto como «personal experimentation and learning, not production». Una cuenta por proveedor, para probar y aprender.

Qué necesitas antes de empezar

• Un VPS con Ubuntu 24.04 y acceso SSH (Secure Shell) con un usuario que pueda usar sudo.
• Docker Engine con el plugin de Compose. Si aún no lo tienes, sigue la guía básica de Docker Compose en un VPS y vuelve aquí.
• Node.js en tu portátil, porque el asistente de configuración de Claude Code se ejecuta con npx.
• Una cuenta y una clave de API en cada proveedor que quieras usar, creadas por ti en la web de cada uno.

Tú ejecutas los comandos de esta guía, en tu servidor o en tu portátil, según indique cada sección. Si tu usuario no está en el grupo docker, añade sudo delante de cada docker.

Instalar FreeLLMAPI con Docker Compose y una versión fija

El README ofrece un instalador de una línea con curl | bash. Aquí no lo usamos, porque ejecuta un script remoto que no has leído y usa la imagen latest. El proyecto publica versiones casi a diario, así que latest cambia sin aviso. Con una etiqueta fija, tú decides cuándo actualizar.

La versión actual al escribir esto, el 7 de octubre de 2026, es la v0.13.6. El 12 de octubre de 2026 la última publicada ya era la v0.13.10. Comprueba la última en la página de releases del repositorio y cambia la etiqueta si hay una más nueva.

En el VPS, clona el repositorio en esa versión:

sudo apt update && sudo apt install -y git openssl
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
git checkout v0.13.6

Git avisará de que estás en «detached HEAD». Es normal, porque estás en una etiqueta y no en una rama.

El archivo docker-compose.yml del repositorio apunta a la imagen latest. Cámbialo por la etiqueta fija y comprueba el resultado:

sed -i 's#ghcr.io/tashfeenahmed/freellmapi:latest#ghcr.io/tashfeenahmed/freellmapi:v0.13.6#' docker-compose.yml
grep 'image: ghcr' docker-compose.yml

La salida debe mostrar image: ghcr.io/tashfeenahmed/freellmapi:v0.13.6. Si todavía dice latest, el sed no encontró la línea y debes editarla a mano.

Ahora crea el archivo .env con la clave de cifrado. Es el procedimiento que documenta el proyecto, con una línea más que fija la escucha en localhost:

ENCRYPTION_KEY="$(openssl rand -hex 32)"
printf "ENCRYPTION_KEY=%s\nPORT=3001\nHOST_BIND=127.0.0.1\n" "$ENCRYPTION_KEY" > .env
chmod 600 .env

ENCRYPTION_KEY cifra las claves de los proveedores dentro de la base de datos SQLite, que vive en el volumen freellmapi-data. Si pierdes el .env, nadie puede descifrar las claves guardadas y tendrás que introducirlas de nuevo. Guarda una copia del .env fuera del servidor.

Descarga la imagen fijada y arranca el contenedor sin compilar nada:

docker compose pull freellmapi
docker compose up -d --no-build

El archivo de Compose incluye también un servicio opcional de actualización automática, con el perfil autoupdate. Déjalo apagado. Ese servicio monta el socket de Docker, que según el propio archivo equivale a acceso root en el servidor. Además, actualizar solo va en contra de fijar la versión.

Comprueba que el servicio responde

docker compose ps
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3001/api/ping
ss -tln | grep 3001

docker compose ps debe mostrar el servicio freellmapi como healthy tras unos segundos. Mientras dice starting, el chequeo de salud aún no ha terminado. El curl debe imprimir 200. La línea de ss debe mostrar 127.0.0.1:3001 y no 0.0.0.0:3001. Si ves 0.0.0.0, el servicio está abierto a internet. Revisa HOST_BIND en el .env antes de seguir.

Por qué el puerto 3001 se queda en localhost

El README es claro: «FreeLLMAPI is local-first and single-user by design». Solo existe un usuario, y una única clave unificada protege la API. Si alguien consigue esa clave, gasta tus cuotas en tu nombre.

Hay una segunda razón, propia de Docker. Docker publica los puertos con sus propias reglas de iptables, así que un puerto publicado en 0.0.0.0 queda accesible aunque ufw diga que está bloqueado. Por eso la protección real es la dirección de escucha, 127.0.0.1, y no el cortafuegos. Cualquier API de modelos expuesta tiene el mismo problema, y cómo proteger un endpoint de API de Ollama lo explica con más detalle.

Abrir el panel con un túnel SSH o con Tailscale

Túnel SSH

Desde tu portátil, abre un túnel que lleva tu puerto local 3001 al puerto 3001 del servidor:

ssh -N -L 3001:127.0.0.1:3001 usuario@IP_DE_TU_VPS

El comando no muestra nada y se queda abierto. Eso es lo correcto. Mientras siga abierto, http://localhost:3001 en el navegador de tu portátil abre el panel de FreeLLMAPI. Si cierras el túnel con Ctrl+C, el panel deja de responder.

Tailscale

Si el VPS y tu portátil ya están en la misma red de Tailscale, el servicio puede escuchar en la dirección de Tailscale del servidor en lugar de en localhost. En el VPS:

tailscale ip -4

Copia la dirección 100.x.y.z que imprime y ponla en HOST_BIND dentro del .env. Después vuelve a crear el contenedor con docker compose up -d --no-build. El panel queda en http://100.x.y.z:3001, solo para los equipos de tu red Tailscale. Un detalle: si al arrancar el servidor Docker levanta el contenedor antes de que Tailscale tenga su dirección, la publicación del puerto falla con cannot assign requested address. El túnel SSH no tiene ese problema, por eso es la opción por defecto en esta guía.

Añadir proveedores y obtener la clave unificada

En el panel, añade la clave de API de cada proveedor que elegiste. Después copia la clave unificada, que empieza por freellmapi-. Tus clientes usarán solo esa clave. Si olvidas la contraseña del panel, el código para restablecerla aparece en los registros del servidor, que ves con docker compose logs freellmapi.

Prueba la API desde el VPS. Para no dejar la clave en el historial del shell, léela primero en una variable:

read -rs FREELLMAPI_KEY
curl -si http://127.0.0.1:3001/v1/chat/completions \
  -H "Authorization: Bearer $FREELLMAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Responde solo: hola"}]}' | grep -i -e '^HTTP' -e 'x-routed-via'

read -rs espera a que pegues la clave y pulses Enter, sin mostrarla en pantalla. La salida debe incluir una línea HTTP/1.1 200 y una cabecera x-routed-via que indica por dónde se enrutó la petición. El valor auto deja que el router elija el modelo. Repite el comando varias veces. Es normal que x-routed-via cambie: es la cadena de respaldo en acción.

Conectar Claude Code a FreeLLMAPI

Claude Code corre en tu portátil, y FreeLLMAPI corre en el VPS. Gracias al túnel SSH de la sección anterior, http://localhost:3001 funciona igual en los dos sitios. Deja el túnel abierto en una terminal.

En otra terminal del portátil, lee la clave unificada y mira qué cambiaría el asistente sin escribir nada:

read -rs FREELLMAPI_KEY
npx freellmapi setup-claude --url http://localhost:3001 --api-key "$FREELLMAPI_KEY" --dry-run

Si el cambio te parece bien, ejecútalo sin --dry-run:

npx freellmapi setup-claude --url http://localhost:3001 --api-key "$FREELLMAPI_KEY"

Según la documentación del proyecto, setup-claude lee el catálogo de modelos de tu servidor y hace una copia de seguridad de tu configuración. Después añade a ~/.claude/settings.json las variables ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN. Con --model <id> puedes fijar un modelo concreto en lugar de dejar que elija el router.

Si prefieres no tocar ese archivo, define las mismas dos variables solo para una sesión:

export ANTHROPIC_BASE_URL=http://localhost:3001
export ANTHROPIC_AUTH_TOKEN="$FREELLMAPI_KEY"
claude

Fíjate en que la URL es la raíz del servidor, sin /v1. Claude Code añade por su cuenta la ruta de la API Messages de Anthropic. Si escribes http://localhost:3001/v1, la ruta queda duplicada y las peticiones fallan.

Qué calidad esperar del modelo que responde

Claude Code no se limita a chatear. Trabaja con herramientas: lee archivos, busca en el código, edita archivos y ejecuta comandos. Para eso, el modelo tiene que pedir cada herramienta en el formato exacto que Claude Code espera. La calidad de esas llamadas a herramientas depende del modelo gratuito que responda, y cambia mucho de un modelo a otro.

Claude Code también envía contextos largos. Cada petición lleva las instrucciones de sistema, las definiciones de herramientas, el historial de la conversación y el contenido de tus archivos. Un modelo con una ventana de contexto corta no puede con todo eso. Si una sesión se comporta de forma extraña, por ejemplo si el modelo describe un cambio en lugar de hacerlo, fija un modelo con --model y compara. Así sabes qué modelo responde y dejas de depender del orden de la cadena.

Ten expectativas realistas. Con FreeLLMAPI tienes la interfaz de Claude Code y un modelo que cambia según la hora y tus cuotas. Para aprender y para proyectos personales, es útil. Para trabajo con plazos, compara antes con usar un modelo abierto en lugar de un plan de Claude o con las formas reales de pagar menos por Claude.

Actualizar sin sorpresas y hacer copias de seguridad

Para actualizar, lee primero el registro de cambios del proyecto. Después cambia la etiqueta en docker-compose.yml, descarga la nueva imagen y recrea el contenedor. Por ejemplo, para pasar a la v0.13.10, la última publicada el 12 de octubre de 2026:

sed -i 's#freellmapi:v0.13.6#freellmapi:v0.13.10#' docker-compose.yml
docker compose pull freellmapi
docker compose up -d --no-build

Conserva el mismo .env y el mismo volumen. Sin la misma ENCRYPTION_KEY, la nueva versión no puede leer las claves que ya guardaste.

Para la copia de seguridad, detén el contenedor, así la base SQLite no cambia mientras la copias. Busca primero el nombre real del volumen, porque Compose le añade como prefijo el nombre del directorio:

docker volume ls | grep freellmapi
docker compose stop freellmapi
docker run --rm -v freellmapi_freellmapi-data:/data -v "$PWD":/backup alpine tar czf /backup/freellmapi-data.tgz -C /data .
docker compose start freellmapi

Si el volumen tiene otro nombre en tu servidor, cámbialo en el comando docker run. Guarda freellmapi-data.tgz junto con una copia del .env, fuera del VPS. Una copia sin la clave de cifrado no sirve para recuperar las claves de los proveedores.

Cuándo FreeLLMAPI no es la herramienta adecuada

FreeLLMAPI está pensado para una sola persona que experimenta. Si necesitas varias personas, claves por usuario, presupuestos o registros de auditoría, lo que buscas es una pasarela de modelos con claves de pago, como una pasarela LiteLLM en tu propio VPS. Y si trabajas con código de clientes, las condiciones de uso de datos de las cuotas gratuitas suelen bastar para descartarlo.

Problemas frecuentes y los mensajes que verás

El túnel no arranca. SSH muestra bind [127.0.0.1]:3001: Address already in use. Algo en tu portátil ya usa el puerto 3001, quizá un túnel anterior que sigue abierto. Ciérralo, o usa otro puerto local con -L 3002:127.0.0.1:3001 y apunta los clientes a http://localhost:3002.

El curl del VPS no conecta. Ves curl: (7) Failed to connect to 127.0.0.1 port 3001. El contenedor no está escuchando. Revisa docker compose ps y lee los últimos registros con docker compose logs --tail 50 freellmapi.

El contenedor no arranca tras poner la IP de Tailscale. Docker muestra cannot assign requested address. Esa dirección todavía no existe en el servidor, normalmente porque Tailscale no ha terminado de arrancar. Vuelve a ejecutar docker compose up -d --no-build cuando tailscale ip -4 devuelva la dirección, o vuelve al túnel SSH.

Claude Code no conecta. Comprueba primero que el túnel sigue abierto. Después comprueba que ANTHROPIC_BASE_URL no termina en /v1.

Claude Code conecta pero trabaja mal. No hay error, pero el modelo no edita archivos o repite pasos. La causa más probable es el modelo que respondió, no la instalación. Fija un modelo más capaz con --model en setup-claude y repite la tarea.

FAQ

¿FreeLLMAPI me da acceso gratis a Claude?

No. FreeLLMAPI permite usar Claude Code, el programa, con modelos gratuitos de otros proveedores. Al consultar el catálogo en freellmapi.co/models el 12 de octubre de 2026, no aparecía ningún modelo de Anthropic. Lo que Anthropic ofrece sin pagar está en su propia API y en sus propios planes, no en FreeLLMAPI.

¿Los proveedores gratuitos usan mis prompts para entrenar sus modelos?

Depende del proveedor y de dónde vives. A 12 de octubre de 2026, la cuota gratuita de la Gemini API permite a Google usar tus datos para mejorar sus productos, salvo en el Espacio Económico Europeo, Suiza y el Reino Unido. El plan gratuito de la API de Mistral puede usar tu entrada y tu salida para entrenar, y puedes oponerte desde los ajustes de tu cuenta. Aparte del entrenamiento, Mistral guarda por defecto la entrada y la salida de la API durante 30 días para vigilar abusos, salvo que actives la retención cero. Groq y Cerebras dicen que por defecto no retienen el contenido de las peticiones. Lee las condiciones de cada proveedor antes de añadir su clave.

¿Puedo abrir varias cuentas en el mismo proveedor para tener más cuota?

FreeLLMAPI acepta varias claves, pero las condiciones de uso de los proveedores suelen prohibir eludir sus límites. Abrir varias cuentas para multiplicar la cuota es justo eso, y puedes perder todas las cuentas. El README del proyecto limita su uso a la experimentación personal y el aprendizaje.

¿Por qué no debo exponer el puerto 3001 de FreeLLMAPI a internet?

FreeLLMAPI es de un solo usuario, y solo la clave unificada protege su API. Además, Docker publica los puertos con sus propias reglas de iptables, así que ufw no los bloquea. Deja HOST_BIND=127.0.0.1 y entra por un túnel SSH o por Tailscale.