StudioForge 2.0: Cuentas, claves de API con alcance definido y un proceso de actualización seguro

StudioForge es el servidor de modelos basado únicamente en GPU que desarrollé para reemplazar a LM Studio en mi equipo (la historia completa está en el artículo original). La versión 2.0 cambia quién puede comunicarse con él. En la versión 0.2.0, el servidor escuchaba en todas las interfaces de red y confiaba en cualquier entidad que pudiera acceder a él; además, existía un PIN opcional para las herramientas de agentes. En la versión 2.0, en cambio, solo escucha en la máquina donde se ejecuta, a menos que se indique lo contrario; una vez habilitado, todo cliente necesita una clave para conectarse.

Código fuente en GitHub

Actualicé mi propio equipo el 19 de octubre de 2026. En cuestión de minutos, todos los programas que lo llamaban sin una clave comenzaron a recibir respuestas de tipo 401: mi herramienta de correo, mi aplicación de chat, el sistema de búsqueda de memoria del gateway de agentes y varios scripts. Ninguno de ellos estaba roto; simplemente no tenían clave todavía. Esta página es lo que hubiera querido leer antes.

¿Qué cambios hay para usted?

Tres cosas, en términos sencillos.

• Por defecto es privado. La puerta de enlace (puerto 1234), el panel de control (8080) y el mecanismo de recuperación (puerto 1235) se vinculan a 127.0.0.1. Ninguna otra máquina puede acceder a ellos en absoluto.
• Para abrir el acceso se necesita iniciar sesión. Si alguno de estos componentes escucha en una dirección de red y no existe ninguna cuenta de propietario ni clave de administrador, studioforge serve se detiene con el código de salida 4 y le indica cómo solucionarlo. Ya no es posible ejecutar accidentalmente un servidor abierto.
• Cada programa recibe su propia clave. Una clave es una cadena como sf-i-… que el programa envía como Authorization: Bearer <key>. Cada clave tiene un nombre, un ámbito, una fecha de expiración opcional y un límite opcional de solicitudes por minuto; además, puede revocar una clave sin afectar a las demás.

A continuación, el mensaje de rechazo, obtenido en mi prueba inicial con los tres hosts configurados como 0.0.0.0 y sin ninguna cuenta:

error: Refusing to start: the gateway, the control panel, the watchdog would listen on a
non-loopback address (0.0.0.0, 0.0.0.0, 0.0.0.0) but no owner account or admin API key exists,
so anyone on the network could drive this server. Fix: run `studioforge setup` (creates the
owner account) or `studioforge keys create --name admin --scope admin`, then start again.

Un detalle me tomó por sorpresa: al crear la primera clave, la autenticación se activa para todos, incluidos los programas que se ejecutan en la misma máquina. Creé una clave en un servidor de prueba que solo aceptaba conexiones locales; al instante, una solicitud sencilla mediante curl a /v1/models desde la misma máquina pasó de devolver 200 a 401. La CLI, la bandeja del sistema y el panel de StudioForge siguen funcionando porque generan su propia clave de administrador local (local-cli), que se almacena exclusivamente para el propietario en el directorio de datos. A partir de ese momento, todo lo demás requiere una clave para operar.

La actualización segura en diez minutos

Este es el orden de los pasos para minimizar las interrupciones del servicio. Sigue los pasos de migración indicados en el CHANGELOG, con dos correcciones basadas en mi propia experiencia.

1. Enumere todos sus clientes. Cada aplicación de chat, agente, script y otro dispositivo que se comunique con el servidor. Si no está seguro, busque en sus configuraciones la dirección del servidor mediante grep. Esta lista representa toda la tarea a realizar.
2. Haga copias de seguridad y una prueba previa. Copie el directorio de datos, actualice el código (git pull) y reinstálelo en su entorno virtual tal como describe el README para su plataforma. Luego ejecute studioforge migrate --dry-run. La versión 2.0.1 cambia el esquema de la base de datos a la versión 10; studioforge migrate realiza una copia de seguridad antes de aplicar los cambios.
3. Cree las credenciales necesarias para el inicio del servidor. Puede usar studioforge setup (el proceso guiado de primera ejecución; crea la cuenta de administrador y, si selecciona “mi red local”, activa HTTPS y genera una clave de administrador), o simplemente ejecute studioforge keys create --name admin --scope admin.
4. Cree una clave para cada cliente, todas a la vez, antes de iniciar el nuevo servidor:

   studioforge keys create --name chat-app  --scope inference --rate-limit-rpm 120
   studioforge keys create --name dashboard --scope read
   studioforge keys create --name laptop    --scope admin --expires-in-days 30

   Cada token se muestra una sola vez y no se almacena; por lo tanto, cópielo directamente en la configuración de cada cliente.
5. Inicie el servidor y pruebe cada cliente con una solicitud real. Un mensaje 401 invalid_api_key indica que ese cliente aún no tiene clave; un 403 permission_denied significa que el alcance de su clave es insuficiente para realizar la operación solicitada.
6. Retire las credenciales antiguas al final. Una vez que todos los clientes funcionen con sus respectivas claves: ejecute studioforge keys revoke legacy, elimine el valor de server.api_key y desactive el PIN de MCP. Consulte el problema relacionado con el PIN más abajo; simplemente eliminar el PIN no es suficiente.
7. Ejecute studioforge doctor y revise los resultados.

Si ya utilizaba server.api_key, la actualización en sí no causa problemas: la clave antigua se replica en la tabla de claves como una clave de administrador llamada legacy, por lo que sigue funcionando. En mi caso, no había ninguna clave compartida, solo el PIN; por eso todos los clientes dejaron de funcionar al mismo tiempo. Si hubiera realizado el paso 4 antes que el paso 5, habría evitado la mayor parte de esos problemas.

El panel: iniciar sesión, configurar y crear claves

Estas capturas de pantalla provienen de una instancia temporal de la versión 2.0.1 que ejecuté en Podman en un equipo sin ninguna GPU de NVIDIA (más detalles abajo); por eso, las dos tarjetas gráficas son simuladas y las claves no sirven para nada.

Ahora el panel cuenta con una página de inicio de sesión. Utilice el nombre de usuario y la contraseña del propietario, o deje el nombre de usuario en blanco y pegue una clave de administrador. Una clave de tipo read o inference no permite acceder al panel.

La guía de configuración en /setup explica ocho pasos: cuenta del propietario, hardware, motor, bibliotecas de modelos, un modelo de ejemplo, una prueba de chat, fragmentos de código para clientes y quién puede acceder al servidor. Cada paso se puede omitir. En el último paso se elige entre “solo este ordenador” y “mi red local, mediante HTTPS”.

Las claves se gestionan en Usuarios y Claves. Asigne un nombre que indique qué programa las usará, elija un ámbito y, opcionalmente, una fecha de caducidad y un límite de uso.

El token se muestra una sola vez. En esta captura lo he ocultado, pero en un servidor real este diálogo es el único momento en que podrá verlo.

La tabla muestra el ámbito de cada clave, los primeros caracteres del token, la última vez que se usó, su caducidad, el límite de uso y su estado. Debajo hay un registro de auditoría: todas las claves creadas o revocadas, todos los inicios de sesión y todos los cambios realizados por administradores, indicando quién los hizo y desde dónde. Los datos confidenciales nunca aparecen en este registro.

Ámbitos: read, inference, admin

Ámbito	Permisos	Para quién se otorgan
read	Consultar: estado del sistema, listas de modelos, /metrics, y herramientas MCP de solo lectura. No se puede realizar ningún POST.	Paneles de control, sistemas de monitoreo
inference	Lectura, además de chat (/v1/chat/completions, /v1/messages, /v1/responses), carga, descarga y prueba de modelos; también permite tomar o liberar el uso de la GPU.	Aplicaciones de chat, agentes, scripts y otros programas que utilizan GPU
admin	Modificar la configuración del sistema: ajustes, reinicios, instalación/actualización de motores, descargas, eliminación de datos, gestión de claves y cuentas, registro de auditoría, paquetes de soporte técnico y uso de herramientas MCP destructivas.	Solo usted

La regla se basa en el código, no en convenciones (api/auth.py:required_scope). Se realiza la coincidencia según el prefijo de la ruta; además, cualquier ruta que modifique el estado del sistema y que no tenga un ámbito asignado requiere admin, por lo que las nuevas rutas quedan cubiertas por defecto. El ámbito se verifica siempre que se envía una clave, incluso en servidores donde no se necesita: una clave de tipo read tampoco puede realizar operaciones POST en un servidor destinado únicamente a acceso local. He probado los casos límite en la instancia de prueba: una clave de tipo inference devolvió 200 para /v1/models y 403 para /api/keys.

Los agentes también reciben una clave, pero nunca la contraseña del propietario. En la página de Integraciones del panel se muestran bloques de código listos para copiar, destinados a OpenClaw, los SDKs de Python de OpenAI y Anthropic, DisPatch, curl y el archivo --mcp-config de Claude. Primero hay que seleccionar una clave en el menú desplegable; si se deja el marcador de posición seleccionado, el bloque de código curl omite el encabezado Authorization, por lo que al pegarlo tal cual se obtiene un error 401.

La cuenta de propietario, la clave compartida antigua y el PIN

En la versión 2.0 existen tres tipos de credenciales; dos de ellas están en proceso de ser retiradas.

• La cuenta de propietario: se utiliza para iniciar sesión en el panel. La contraseña debe tener al menos 10 caracteres y se encripta mediante argon2id. El hash resultante se guarda en el llavero del sistema operativo si está instalado el complemento opcional keyring; de lo contrario, se almacena en un archivo accesible solo por el propietario. Dicha contraseña no se guarda en la base de datos, por lo que una copia de esta no contendrá información de inicio de sesión.
• server.api_key (en desuso): sigue funcionando como credencial de administrador en todos los lugares; aparece como la clave legacy. El comando keys revoke legacy realmente la desactiva.
• mcp.pin (en desuso): es una credencial de administrador compuesta por ocho dígitos, válida únicamente para los endpoints de MCP. En un servidor sin ninguna otra clave, esta credencial sigue permitiendo el acceso a las rutas HTTP destinadas a llamadas remotas; por eso las configuraciones antiguas siguen funcionando. Sin embargo, en cuanto se crea cualquier otra clave con alcance específico, este comportamiento cesa.

El “truco” del PIN. En el CHANGELOG se indica que hay que “eliminar server.api_key y mcp.pin”. No obstante, si solo se establece mcp.pin: null, en el siguiente inicio del servidor se generará un nuevo PIN aleatorio y se guardará de nuevo, ya que mcp.pin_required sigue siendo true. Lo he comprobado personalmente. Para retirarlo definitivamente, hay que configurar ambos valores:

mcp:
  pin: null
  pin_required: false

Esta misma lógica hace que una instalación nueva de 2.0.1 genere un PIN en el primer inicio; posteriormente, studioforge doctor lo identifica como una credencial en desuso. No supone ningún problema, pero no se sorprendan si ocurre.

Vinculación de red, HTTPS y navegadores

• Regla de vinculación. server.host, gui.host y watchdog.host toman por defecto el valor 127.0.0.1. En las configuraciones creadas por versiones anteriores se especifica explícitamente 0.0.0.0; por eso el nuevo valor predeterminado no lo modifica. Dichas configuraciones impiden cualquier conexión hasta que se añada una credencial válida.
• HTTPS. server.tls.mode es un único parámetro para los tres tipos de escuchadores: off, self_signed (se genera un certificado en el directorio de datos; su huella SHA-256 se muestra en el panel para que los clientes puedan usarla como verificación) o cert (para utilizar sus propios archivos de certificado). Si se habilita la vinculación de red pero TLS está desactivado, doctor advierte que las claves se transmiten por la red sin cifrar. También funciona el uso de un proxy inverso o de tailscale serve como intermediario.
• Navegadores. Ahora, server.cors_origins toma por defecto un valor vacío (antes era ["*"]). Los clientes no basados en navegadores no se ven afectados. Los puntos de extremo MCP realizan además su propia comprobación de origen: las solicitudes que incluyan el encabezado Origin deben provenir de una página local o de un origen autorizado; un valor * no se considera válido. Esto evita que cualquier página web pueda acceder a las herramientas de gestión del sistema a través del navegador.
• Fuerza bruta. Los intentos con credenciales incorrectas se limitan a tres por dirección IP; después, el tiempo de espera se duplica hasta alcanzar un máximo de cinco minutos. Estas restricciones se aplican por separado a la API, al panel de control y al servicio watchdog.

Compartir las tarjetas: arrendamientos y inquilinos

Si hay otro programa en el sistema que utiliza las GPU (un generador de imágenes, un servidor de voz, un programa de pruebas), este puede obtener primero un arrendamiento sobre una tarjeta; StudioForge no cargará ningún modelo en dicha tarjeta hasta que el arrendamiento se libere o permanezca inactiva más allá del tiempo límite establecido. La versión 2.0 incorpora un registro de inquilinos, de modo que esos programas pueden autoregistrarse y aparecer en la página de colocación con su estado actual; además, incluye devices: "auto", lo cual permite a un inquilino solicitar cualquier tarjeta que tenga suficiente memoria libre, en lugar de especificar una en particular. StudioForge muestra los inquilinos y puede pedirles que “precalienten” una tarjeta o que la liberen, pero nunca los inicia ni los detiene.

La corrección de la versión 2.0.1 es importante si utiliza alguno de estos programas: en la versión 2.0.0, las rutas destinadas a los inquilinos requerían una clave admin; por eso, un servidor de voz o de generación de imágenes que usara una clave válida de tipo inference recibía un error 403 al intentar obtener un arrendamiento. En la versión 2.0.1, dichas rutas son ahora de tipo inference, y cada arrendamiento queda vinculado a la clave que lo solicitó: otra clave de tipo inference no puede liberarlo (lo intenté y obtuve el error 403 permission_denied con el mensaje “El arrendamiento … no fue creado por esta clave API”); en cambio, una clave admin sí puede hacerlo.

Un detalle importante al registrar un inquilino: los arrendamientos se asocian a ellos según la familia, que es el nombre del titular hasta el primer -. Un inquilino registrado como speech-demo no veía su propio arrendamiento speech-demo (la familia de ese arrendamiento es speech); en cambio, si se registraba como speech, sí lo veía. Por eso, conviene usar nombres de inquilinos sin guiones. El protocolo en sí está documentado en el archivo docs/TENANTS.md del repositorio.

sfctl 2.0.1, el control remoto

sfctl es un pequeño cliente para controlar un servidor StudioForge desde otra máquina, además de actuar como puente MCP para los agentes. Ahora requiere una clave para funcionar. No se encuentra en PyPI (el comando uv tool install studioforge-companion indicado en su README falla), por lo que debe instalarse mediante un clon del repositorio:

git clone https://github.com/LaserLloyd/StudioForge.git
uv tool install ./StudioForge/packages/studioforge-companion
sfctl servers add rig http://192.0.2.10:1234 --api-key sf-i-your-key --use
sfctl status

El perfil de configuración se guarda en ~/.config/studioforge/companion.toml; este archivo solo puede ser modificado por su propietario, ya que contiene la clave. También se puede utilizar la variable de entorno SF_API_KEY. Si el gateway no escucha en el puerto 1234, hay que añadir el parámetro --watchdog-url, ya que la dirección del watchdog se deriva de la del gateway. En mi instancia de prueba, utilicé una clave de tipo inference:

$ sfctl status
┏━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┓
┃ GPU ┃ Name                           ┃ Total    ┃ Used ┃ Free     ┃
┡━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━┩
│ 0   │ Demo GPU 0 (simulated) (sm_86) │ 24.0 GiB │ 0 B  │ 24.0 GiB │
│ 1   │ Demo GPU 1 (simulated) (sm_86) │ 24.0 GiB │ 0 B  │ 24.0 GiB │
└─────┴────────────────────────────────┴──────────┴──────┴──────────┘
no models loaded

$ sfctl leases add --devices 1 --holder image-render --reason "a render job outside StudioForge"
lease 933d9554c0c6 holds GPU 1 for image-render
release it with: sfctl leases release 933d9554c0c6

(He omitido las columnas Util y Temp, así como la tabla de servidores, para ajustar el texto al formato.)

Doctor y el paquete de soporte

studioforge doctor verifica los puertos, las GPUs, el motor, el disco, los permisos de archivos, el certificado, las migraciones y la configuración de autenticación; luego muestra una solución para cada problema encontrado. El parámetro --strict hace que el programa termine con código distinto de cero incluso ante advertencias, lo cual resulta útil para tareas de monitoreo. Este es el contenedor de demostración: escucha en la red con una cuenta de propietario y sin TLS activado:

[ok  ] GPU: 2 GPU(s) via fake: Demo GPU 0 (simulated) (24 GiB), Demo GPU 1 (simulated) (24 GiB).
[WARN] Engine: No llama.cpp engine is installed.
        fix: Run `studioforge setup` or `studioforge engine --update` to install and smoke-test one.
[ok  ] Permissions: The data directory is writable and credential files are owner-only.
[ok  ] Migrations: The database is at schema 10 (current).
[info] Authentication: The server listens on the network and requires an API key or an account.
[WARN] Authentication: The network listeners use plain HTTP, so keys and passwords cross the network in the clear.
        fix: Set server.tls.mode to self_signed (or cert), or front the server with a TLS reverse proxy / `tailscale serve`.
[info] Authentication: mcp.pin is set. It is deprecated and grants admin on the MCP endpoints.

9 ok, 3 info, 2 warnings, 0 failures.

En el servidor de pruebas local, donde aún estaba configurado server.api_key, el mismo comando emitió la advertencia: “server.api_key está configurado. Aún funciona (como clave de administrador ‘legacy’), pero está obsoleto”. La solución recomendada es crear claves con alcance específico, migrar los clientes y revocar legacy.

studioforge support-bundle genera un archivo ZIP pequeño para informes de errores: una configuración anonimizada, la salida del comando doctor, las versiones utilizadas, la lista de GPUs y fragmentos de los registros. En mi caso el archivo pesó 6 KiB; el PIN aparecía como [REDACTED]. El programa también anonimiza engine.pinned_tag, que es el número de versión de llama.cpp. Dicha información resulta útil en los informes de errores y no es un dato confidencial, así que conviene añadirla manualmente. El propio comando advierte: “mire bien antes de compartir”, y tiene razón.

Ejecución en un contenedor

La versión 2.0 incluye un Dockerfile con variantes para CUDA, ROCm y Vulkan; además, un usuario no root, un sistema de archivos raíz de solo lectura y un volumen con nombre. También hay archivos compose para Docker y Podman. El contenedor crea la cuenta de propietario en la primera ejecución sobre un volumen nuevo, utilizando SF_OWNER_PASSWORD o una contraseña generada que se guarda en el volumen; esto se debe a que cualquier puerto publicado se considera “fuera del loopback” desde el interior del contenedor. Los puertos se publican a 127.0.0.1, a menos que se defina SF_BIND.

Por ahora, las imágenes no están disponibles en ningún registro (hoy en día, intentar descargar ghcr.io/laserlloyd/studioforge resulta en un error), por lo que primero debe compilar usted mismo la imagen; el README contiene los comandos exactos para cada plataforma. Para estas capturas de pantalla, compilé la imagen Vulkan usando Podman: su tamaño es de 568 MB, y se ejecuta en modo de solo lectura, con todas las capacidades desactivadas. La imagen de NVIDIA es la única que ha logrado ejecutar un modelo real; las imágenes para AMD y Vulkan arrancan correctamente y responden a /health, pero aún no se han probado en hardware AMD o Intel. El tamaño de las imágenes, los parámetros de GPU, las pruebas de actualización y las copias de seguridad de todo el stack se detallan en Cada módulo en Docker; por eso no los repetiré aquí.

También hay novedades en la versión 2.0

• Más clientes siguen funcionando sin cambios: La API REST nativa de LM Studio bajo /api/v1, un endpoint /v1/messages compatible con Anthropic (funcionan tanto x-api-key como tokens bearer), y el endpoint sin estado de OpenAI: /v1/responses.
• Errores que indican cómo solucionarse: 76 códigos de error; cada uno incluye un campo fix y otro docs en el cuerpo del mensaje de error. El código 401 que recibe un cliente sin clave indica qué comando debe ejecutar para generar una clave.
• Más opciones que solo NVIDIA, en teoría: Detección de GPUs compatibles con ROCm, Vulkan y Metal; además, un instalador de motores que verifica las sumas de comprobación de los archivos. Se probó utilizando resultados simulados, no en hardware real de AMD o Apple. Los dispositivos Vulkan de tipo software, como llvmpipe, son rechazados, ya que StudioForge está diseñado precisamente para evitar el uso de modelos en la CPU.
• Un panel más amplio: 11 secciones (Descripción general, Modelos, Servicio, Motores, Ubicación, Integraciones, Usuarios y Claves, Actualizaciones, Registros y Métricas, Diagnóstico, Opciones avanzadas) y tres temas nuevos.
• Control de versiones semántico: La versión 2.0.0 corresponde a la antigua versión 1.26-09-23; el actualizador maneja correctamente ambos sistemas de numeración.

Cómo probé esto, y qué no probé

La máquina en la que escribo no cuenta con una GPU de NVIDIA, por lo que no pude cargar ningún modelo. StudioForge dispone de un backend de GPU simulado para su suite de pruebas (SF_GPU_PROBE=fake, junto con una lista de tarjetas gráficas en formato JSON en SF_FAKE_GPUS); el panel, las claves, las cuentas, los contratos de arrendamiento, los inquilinos, el módulo “doctor” y el paquete de soporte se ejecutan todos sobre este backend. Todo lo que aparece arriba con la indicación “Lo intenté” o que muestra alguna salida se ejecutó en la versión 2.0.1: una vez desde una copia del repositorio en un directorio temporal, y otra vez dentro de un contenedor Podman; ambas veces usando puertos de loopback y archivos de modelo de demostración que contienen encabezados pero no pesos reales. Los tamaños y niveles de cuantización de los modelos que se muestran en el panel son valores de encabezado reales; los modelos en sí, no lo son.

Lo que no probé aquí: cargar o servir un modelo, el uso de TLS en modo self_signed, la bandeja del sistema en Windows, y una actualización “in-place” a partir de un directorio de datos de la versión 1.26 (el artículo sobre Docker describe cómo realizar una actualización en el mismo volumen). La información sobre la actualización que se menciona al principio proviene de mi equipo real, no de la instancia temporal utilizada para las pruebas.

Aspectos pendientes de mejorar

• Todavía no hay versión oficial. La versión 2.0.1 se encuentra en la rama main, pero no cuenta con etiqueta alguna, ni lanzamiento en GitHub, ni paquete en PyPI, ni imagen publicada. El sistema de autoactualización no tiene nada que actualizar hasta que haya una nueva versión.
• Una advertencia engañosa. En un servidor conectado a la red que cuenta con una cuenta de administrador pero sin server.api_key, la lista de verificación de configuración indica que el servidor es accesible “sin necesidad de clave API: cualquiera en la red local puede cargar, descargar y eliminar modelos”. Eso no es cierto: tanto la página de Usuarios y Claves como las solicitudes reales muestran que el inicio de sesión es obligatorio. La lista de verificación solo tiene en cuenta la antigua clave compartida.
• La documentación no coincide respecto al motor del contenedor. En la ruta de instalación mediante Docker descrita en el README se utiliza la imagen de 14 GB -cuda-devel, la cual compila llama.cpp al iniciarse por primera vez; sin embargo, la guía de contenedores indica que la imagen más ligera -cuda descarga un motor ya compilado. No pude resolver esta discrepancia sin contar con una tarjeta NVIDIA; por ahora, sigan las instrucciones del README hasta que ambas fuentes coincidan.
• Nadie más lo ha auditado. El modelo de seguridad se describe en el archivo docs/SECURITY.md del repositorio; allí se detalla también lo que no se protege (por ejemplo, un administrador en la misma máquina o el uso de HTTP sin cifrado en redes ajenas). Léanlo antes de conectar StudioForge a una red compartida.

Descárgalo

git clone https://github.com/LaserLloyd/StudioForge.git

Luego, sigue las instrucciones del README para tu plataforma. El archivo zip más antiguo en el artículo original corresponde a la versión 0.2.0 y no incluye ninguna de estas características. Licencia: MIT.

Relacionado: StudioForge: un servidor LLM exclusivo para GPU (el planificador, las mediciones y las herramientas MCP), Cada módulo en Docker (la forma de ejecutar todo el stack en contenedores), y DisPatch (una aplicación de chat que se conecta a él mediante una clave).