Documentación de la API

Referencia completa de la API del systemcontroller de Town OS — 77 endpoints entre cuentas, almacenamiento, repositorios, paquetes, systemd, ajustes, auditoría, páginas, DNS, monitoreo, servicios del sistema, idiomas, imágenes de máquina virtual y estado.

Autenticación

Autentícate llamando a POST /account/authenticate con un usuario y una contraseña. La respuesta trae un token Bearer. Inclúyelo en las peticiones siguientes:

Authorization: Bearer <token>

Las sesiones caducan a los 7 días de inactividad. Hay cinco niveles de autorización:

Crear una partición de almacenamiento de objetos queda reservado a los administradores aunque los extremos de dentro de una partición no lo estén: una partición es la raíz de un árbol de permisos y aparta un subvolumen btrfs con cuota, así que la concesión te admite a los usuarios que hay dentro de una partición, no a la decisión de que deba existir.

Estado

Comprobación de salud y panorama del sistema. Quien llame sin autenticarse recibe una respuesta mínima con status y needs_setup. Quien llame autenticado recibe los datos completos del panel, incluyendo el número de sistemas de archivos, los conteos de paquetes, el resumen del estado de las unidades, el uso de disco, la IP externa e interna y si hay actualizaciones disponibles.

Almacenamiento

Lista los sistemas de archivos. Además de los parámetros de paginación, acepta en el cuerpo un name opcional (filtro por prefijo) y un state (user, installed o uninstalled).

Crea un subvolumen btrfs nuevo. Manda name y, si quieres, quota (en bytes). Si la cuota es 0 o se omite, se usa el valor predeterminado del sistema (50 GB). Los nombres reservados (installed, uninstalled, archives) se rechazan.

Modifica un sistema de archivos existente. Manda name para identificarlo y un objeto filesystem con el name y/o la quota actualizados.

Elimina un sistema de archivos. Cuerpo de la petición: {"name": "mydata"}.

Sube y descomprime un archivo dentro de un subvolumen de destino. Acepta multipart/form-data con un campo subvolume y un archivo archive. Admite .tar.gz, .tgz, .tar.bz2, .tbz2, .tar.xz, .txz, .tar, .zip y .7z.

Descarga un archivo comprimido con el contenido de un subvolumen. Devuelve un archivo transmitido en el formato solicitado.

Lista los volúmenes de los paquetes agrupados por paquete, con la opción de incluir los volúmenes desinstalados.

Borra un volumen concreto de un paquete usando su nombre interno.

Borra de una sola llamada todos los volúmenes que pertenecen a un paquete, en lugar de quitarlos uno por uno por nombre interno.

Paquetes

Lista todos los paquetes disponibles en todos los repositorios. Cada entrada incluye el repositorio, el nombre, la versión, la descripción, las etiquetas supplies, el estado de instalación y si hay una actualización disponible. Admite parámetros de paginación.

Lista los paquetes agrupados por repositorio. Acepta un parámetro de consulta search opcional. Devuelve un arreglo de grupos {"repo": "...", "packages": [...]}.

Lista los identificadores de los paquetes instalados. Admite parámetros de paginación.

Obtiene información detallada de un paquete instalado. Manda repo, name y version. Devuelve las preguntas, las respuestas del usuario, las notas y los tipos de nota.

Obtiene las respuestas guardadas de un paquete instalado. Manda repo, name y version. Devuelve un mapa de clave y valor.

Lista las versiones disponibles de un paquete. Cuerpo de la petición: {"name": "nginx"}. Devuelve un arreglo de cadenas con los identificadores de versión.

Lista los paquetes hijos. Manda repo y name. Devuelve un arreglo de cadenas.

Obtiene las preguntas de instalación de un paquete. Cuerpo de la petición: {"name": "nginx"}. Devuelve un mapa de clave de pregunta a {"query": "...", "type": "..."}.

Obtiene las preguntas de una versión concreta de un paquete. Manda repo, name y version.

Inicia el flujo de dispositivo OAuth de una pregunta oauth. Manda repo, name, version y question. El controlador del sistema ejecuta el paso inicial del flujo contra el proveedor y devuelve flow_id, approve_url (ábrela en el navegador del usuario), un user_code opcional y interval_ms — cada cuánto sondear.

Las URL del proveedor vienen del paquete, no de Town OS, así que se revisan antes de llamarlas: solo https, y nunca una dirección de la propia red del anfitrión.

Sondea un flujo iniciado arriba. Manda flow_id. Devuelve status: pending mientras el usuario no haya aprobado, approved junto con el token, o expired una vez que el flujo caducó o su token ya se recogió — cada flujo es de un solo uso. El token después se envía como respuesta de esa pregunta a /packages/install, igual que una respuesta escrita a mano.

Muestra qué hará una instalación antes de comprometerse. Manda repo, name y version. Devuelve los detalles de los volúmenes, las asignaciones de puertos, el uso de disco, la información de cuotas, la versión de origen de la actualización y un resumen legible.

Instala un paquete.

Desinstala un paquete. Manda repo, name, version y, si quieres borrar los datos asociados, purge_volumes (booleano).

Deshabilita un paquete instalado (detiene su servicio). Manda repo y name.

Vuelve a habilitar un paquete deshabilitado (arranca su servicio). Manda repo y name.

Borra todos los volúmenes de datos de un paquete instalado. Manda repo y name.

Revisa si un paquete tiene volúmenes sobrantes de una instalación anterior. Manda repo y name. Devuelve has_uninstalled_volumes, uninstalled_versions e installed_versions.

Borra los volúmenes que quedaron de versiones desinstaladas anteriormente. Manda repo y name.

Lista las actualizaciones disponibles de los paquetes instalados. Cada entrada incluye installed_version, latest_version y si la definición del paquete ha changed.

Descarta las notificaciones de actualización actuales. Manda un objeto JSON vacío.

Devuelve la definición YAML cruda del paquete. Manda repo, name y version. Devuelve el contenido del archivo con Content-Type: text/x-yaml. Devuelve 404 si el archivo del paquete no existe.

Lista los paquetes destacados de todos los repositorios.

Recupera las últimas respuestas en caché de un paquete. Manda repo y name. Devuelve las respuestas guardadas de una desinstalación previa, para reutilizarlas al reinstalar.

Borra el archivo de últimas respuestas en caché de un paquete. Manda repo y name.

Trae los últimos cambios de los volúmenes sembrados por git de un paquete instalado y reinicia el servicio que depende de ellos. Manda repo, name y version. Las variables de plantilla se vuelven a evaluar con las respuestas guardadas antes de reconstruir.

Ajustes

Obtiene todos los ajustes como un objeto de clave y valor.

Obtiene un solo ajuste. Cuerpo de la petición: {"key": "default_quota"}. Devuelve key y value.

Define el valor de un ajuste. Cuerpo de la petición: {"key": "default_quota", "value": "107374182400"}.

Ajustes predeterminados

Páginas

Hospedaje de sitios estáticos con tres tipos de origen de contenido: subir un archivo comprimido, imágenes de contenedor y repositorios git. Los usuarios asignan un dominio y el sistema sirve el contenido desde un contenedor de Caddy. Todos los endpoints que modifican algo requieren autenticación de administrador; el de listado requiere autenticación normal.

Lista todas las páginas, con ordenamiento, búsqueda y paginación. Se puede ordenar por nombre, URL del repositorio, rama, dominio, tipo de origen, estado y marcas de tiempo.

Crea una página nueva. Acepta el nombre, el tipo de origen (archive, container_image o git), la URL del repositorio, la rama, el dominio, la imagen de contenedor y el directorio dentro de la imagen. El tipo de origen es archive por omisión. Las páginas de git y de imagen de contenedor se preparan de forma asíncrona.

Sube un archivo tar con el contenido de una página de tipo archivo. Acepta un formulario multiparte con name y el archivo archive. Solo es válido para páginas con tipo de origen archive; para otros tipos devuelve 400.

Actualización parcial de la URL del repositorio, la rama, el dominio, el tipo de origen, la imagen de contenedor o el directorio de la imagen de una página. Solo se cambian los campos que envíes.

Borra una página de la base de datos, quita el enlace simbólico del webroot y elimina el subvolumen btrfs.

Reconstruye el contenido de una página desde su origen. Las páginas de git traen los últimos cambios; las de imagen de contenedor vuelven a extraer desde la imagen. Las páginas de archivo devuelven 400 (vuelve a subirlo con /pages/upload).

Redes

Una red es una superposición WireGuard con nombre, emparejada con un TLD de DNS. Los paquetes se instalan en una red, los pares se unen a ella y el TLD es lo que divide quién puede resolver qué. Los nombres de red son seguros como etiqueta DNS y están topados a 32 caracteres, porque se reutilizan como sufijos de interfaz WireGuard y como nombres de unidad de systemd.

La red home siempre existe — se siembra junto con la propia base de datos, no se crea al arrancar — y es especial de tres maneras: no se puede eliminar ni crear una segunda vez, es solo de DNS (sin interfaz WireGuard, sin subred, sin pares), y el enrolamiento de pares en ella se rechaza con un 400. Toda cuenta pertenece a la red home, así que aceptar el enrolamiento ahí haría que la simple membresía fuera una manera de entrar a un túnel — y el par guardado describiría un túnel que no existe.

Deshabilitar una red baja únicamente el transporte: la interfaz WireGuard no se levanta, lo que corta el acceso remoto, mientras la resolución DNS local y los contenedores siguen corriendo.

Lista las redes. Cada entrada trae el nombre, el TLD, la subred, la dirección de la propia computadora en la superposición, la llave pública, el puerto de escucha y la bandera de habilitación. La llave privada nunca se serializa.

Crea una red. La subred se deriva de forma determinista de una semilla de identidad de la computadora y del nombre de la red, tomada de 10.64.0.0/10 para no chocar con los rangos que reparten los routers domésticos. Derivarla de la identidad de la computadora hace que dos computadoras Town OS que sirvan pares elijan subredes distintas, así que un dispositivo que se une a las dos nunca ve una colisión. Crear home devuelve 409 por la comprobación de colisión de TLD.

Elimina una red. Rechaza la red home.

Levanta el transporte WireGuard de la red.

Baja el transporte dejando el DNS y los contenedores corriendo.

Pares

Lista los pares enrolados en una red.

Lista los pares conectados en este momento, a diferencia de los que solo están enrolados.

Enrola un par. La concesión de wireguard es lo que deja pasar a quien no es administrador; el alcance por red y la pertenencia de cada par los aplica el manejador. Devuelve 400 para la red home, que es solo de DNS.

Renueva el enrolamiento de un par antes de que caduque su TTL. Los enrolamientos tienen vigencia y un recolector quita los que se vencen.

Quita un par de una red.

La autoridad certificadora local

Descarga en formato PEM la autoridad certificadora local de la computadora. Town OS emite sus propios certificados para los nombres de los paquetes, así que confiar en este certificado es lo que hace que esos nombres funcionen en un navegador sin advertencias. Es público a propósito: un certificado de CA es justo la parte que se reparte, y un cliente lo necesita antes de tener cualquier credencial con la que autenticarse.

Monitoreo

Conjunto integrado de Prometheus, Node Exporter y Grafana para el monitoreo del sistema. Todo corre como contenedores de podman supervisados por systemd con Restart=always.

Devuelve el estado del contenedor (nombre, imagen, si está corriendo, puerto) de cada servicio de monitoreo. Devuelve {"status": "disabled"} cuando el monitoreo no está configurado.

Cómo se llega a los datos del panel

No hay ningún proxy inverso a través del controlador del sistema. Los datos de monitoreo se sirven en su propio puerto dedicado, el 5308, y el navegador habla directo con ese puerto; el puerto del controlador (5309) solo lleva /monitoring/status. Lo que escucha en el 5308 depende del backend configurado:

• Modo uPlot (el de omisión) — un reenviador socat expone la API HTTP de Prometheus en el 5308, y la interfaz consulta /api/v1/query_range directamente y dibuja las gráficas ella misma.
• Modo Grafana — Grafana escucha directo en el 5308 mediante un mapeo de puertos de podman, y la interfaz lo empotra en un iframe.

TOWN_OS_MONITORING_PORT cambia de lugar el puerto del panel; TOWN_OS_PROMETHEUS_PORT y TOWN_OS_NODE_EXPORTER_PORT hacen lo mismo con los dos puertos de loopback.

Idiomas

Información de idiomas del sistema para la internacionalización.

Devuelve el idioma actual, la lista de idiomas ya poblados, los idiomas comunes (con sus nombres en su propia escritura) y los idiomas extendidos. Usa códigos de idioma BCP 47.

API de administración del almacenamiento de objetos (gfeh)

Todo lo de arriba es la API de Town OS, que es la que normalmente debe usar una aplicación. Por debajo de ella, cada partición de gfehd tiene su propia superficie administrativa: JSON sobre HTTP en únicamente su socket Unix, nunca en un puerto.

En esta superficie no hay token ni autenticación. Los permisos del sistema de archivos sobre el socket son el control de acceso, así que poder llegar a él ya significa ser root en la computadora. El socket vive en el volumen btrfs porque es el único sistema de archivos que ven a la vez el contenedor de gfehd y el del controlador del sistema.

gfehd mapea sus errores internos a códigos de estado HTTP — 404, 409, 400 — y el cliente de Go los mapea de vuelta a errores centinela, así que errors.Is funciona al otro lado del socket.

Dónde viven los archivos de una partición, para una red llamada <network>:

Bibliotecas cliente

Town OS trae bibliotecas cliente de Go y de JavaScript que cubren la API completa. Ambos clientes lanzan errores con tipo ante respuestas distintas de 200, usando el detalle de problema del RFC 9457.

Cliente de Go

El cliente de Go vive en src/svc/systemcontroller/client.go e implementa la interfaz Client. Admite tanto conexiones por socket Unix como por HTTP.

// Conectar por socket de dominio Unix (producción)
client := systemcontroller.InitClient("/run/town-os/systemcontroller.sock")

// Conectar por HTTP (desarrollo / pruebas)
client := systemcontroller.FromClient(http.DefaultClient, "http://localhost:5309")

Define client.Token después de autenticarte. Todos los métodos reciben un context.Context como primer parámetro.

Almacenamiento

Repositorios

Paquetes

Systemd

Cuentas

Auditoría, ajustes y actualizaciones

Archivos comprimidos

Salud

Referencia de desarrollo

El backend de Town OS corre en el puerto 5309, con un servidor de desarrollo de Vite en el 5173. Usa make dev para levantar todo el entorno de desarrollo.

Objetivos principales

Objetivos de pruebas

Objetivos de construcción