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, monitorización, 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 reserva 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 visión general 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 ficheros, los recuentos 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 ficheros. 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. Envía 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 ficheros existente. Envía name para identificarlo y un objeto filesystem con el name y/o la quota actualizados.

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

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

Descarga un fichero comprimido con el contenido de un subvolumen. Devuelve un fichero 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 en una sola llamada todos los volúmenes que pertenecen a un paquete, en lugar de quitarlos uno a 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 array 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. Envía 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. Envía 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 array de cadenas con los identificadores de versión.

Lista los paquetes hijos. Envía repo y name. Devuelve un array 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. Envía repo, name y version.

Inicia el flujo de dispositivo OAuth de una pregunta oauth. Envía 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 comprueban antes de llamarlas: solo https, y nunca una dirección de la propia red del anfitrión.

Sondea un flujo iniciado arriba. Envía flow_id. Devuelve status: pending mientras el usuario no haya aprobado, approved junto con el token, o expired una vez que el flujo ha caducado o su token ya se ha recogido — 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. Envía 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. Envía repo, name, version y, si quieres borrar los datos asociados, purge_volumes (booleano).

Deshabilita un paquete instalado (detiene su servicio). Envía repo y name.

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

Borra todos los volúmenes de datos de un paquete instalado. Envía repo y name.

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

Borra los volúmenes que quedaron de versiones desinstaladas anteriormente. Envía 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. Envía un objeto JSON vacío.

Devuelve la definición YAML en bruto del paquete. Envía repo, name y version. Devuelve el contenido del fichero con Content-Type: text/x-yaml. Devuelve 404 si el fichero del paquete no existe.

Lista los paquetes destacados de todos los repositorios.

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

Borra el fichero de últimas respuestas en caché de un paquete. Envía repo y name.

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

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.

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

Ajustes predeterminados

Páginas

Alojamiento de sitios estáticos con tres tipos de origen de contenido: subir un fichero 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 ordenación, 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 aprovisionan de forma asíncrona.

Sube un fichero tar con el contenido de una página de tipo fichero. Acepta un formulario multiparte con name y el fichero 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.

Recompila 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 fichero 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 limitados 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 mera pertenencia fuera una forma de entrar en un túnel — y el par guardado describiría un túnel que no existe.

Deshabilitar una red tira abajo ú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 ejecutándose.

Lista las redes. Cada entrada lleva el nombre, el TLD, la subred, la dirección del propio ordenador en la superposición, la clave pública, el puerto de escucha y el indicador de habilitación. La clave privada nunca se serializa.

Crea una red. La subred se deriva de forma determinista de una semilla de identidad del ordenador 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 del ordenador hace que dos ordenadores Town OS que sirvan pares elijan subredes distintas, así que un dispositivo que se une a los 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.

Tira abajo el transporte dejando el DNS y los contenedores en marcha.

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 ámbito 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 retira los que vencen.

Retira un par de una red.

La autoridad certificadora local

Descarga en formato PEM la autoridad certificadora local del ordenador. 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.

Monitorización

Conjunto integrado de Prometheus, Node Exporter y Grafana para la monitorización del sistema. Todo se ejecuta como contenedores de podman supervisados por systemd con Restart=always.

Devuelve el estado del contenedor (nombre, imagen, si está en marcha, puerto) de cada servicio de monitorización. Devuelve {"status": "disabled"} cuando la monitorización no está configurada.

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 monitorización se sirven en su propio puerto dedicado, el 5308, y el navegador habla directamente 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 predeterminado) — 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 directamente en el 5308 mediante una asignación de puertos de podman, y la interfaz lo incrusta en un iframe.

TOWN_OS_MONITORING_PORT reubica 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 anterior 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 ficheros sobre el socket son el control de acceso, así que poder llegar a él ya significa ser root en el ordenador. El socket vive en el volumen btrfs porque es el único sistema de ficheros que ven a la vez el contenedor de gfehd y el del controlador del sistema.

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

Dónde viven los ficheros 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")

Establece 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

Ficheros comprimidos

Salud

Referencia de desarrollo

El backend de Town OS se ejecuta 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 compilación