Linux Agent
Administra Debian/Ubuntu por Telegram: sesiones de agentes, mantenimiento con confirmación humana, root temporal y alarmas sostenidas.
Enlaces relacionados
Acerca del agente
Linux Agent · 0.1.0
Linux Agent permite administrar servidores Debian y Ubuntu desde Telegram. Integra
sesiones de agentes, mantenimiento de paquetes y servicios, elevación temporal de
privilegios y monitorización con alertas. Requiere systemd, Python 3.11 o posterior
y sudo con soporte para NOTAFTER.
Cómo funciona
- Bot de control (
linux-agent-bot): valida propietario y chat privado, conserva el token y exige confirmaciones de un solo uso que caducan en dos minutos. - Agente (
linux-agent): cuenta separada sin grupos privilegiados ni sudo general. Codex app-server gestiona sesiones persistentes y aprobaciones del runtime. El relay solo permite registrar temas, entregar respuestas y leer/acusar mensajes. - Root temporal:
/root 15mmuestra una confirmación. El helper root valida entre un minuto y ocho horas, genera una regla conNOTAFTER, desactiva la caché de sudo y programa su retirada./root offrevoca nuevas elevaciones. Al arrancar el servidor la ventana se cierra. El modelo no tiene acceso al token del bot ni al componente que concede la ventana. - Mantenimiento: APT y reinicios se ejecutan como jobs de systemd, con bloqueo para evitar operaciones simultáneas, log root y resultado consultable. Requieren confirmación humana y una ventana root activa al comenzar.
- Alarmas: RAM, carga normalizada por CPU, ocupación de disco/inodos, servicios configurados y heartbeat del puente. Umbrales sostenidos, histéresis, deduplicación, reintento de entrega y aviso de recuperación. Las acciones correctivas se solicitan desde el bot y requieren autorización según la operación.
Preparación del servidor
Descarga linux-agent-0.1.0.agent.json desde la ficha del catálogo. El campo files
contiene el árbol de archivos y su contenido. Puedes consultarlos en el visor o
extraerlos en una carpeta nueva con el siguiente comando. La configuración de
cuentas, permisos y servicios se realiza en los pasos posteriores.
python3 - linux-agent-0.1.0.agent.json linux-agent <<'PYTHON'
import json, pathlib, sys
snapshot = json.loads(pathlib.Path(sys.argv[1]).read_text())
root = pathlib.Path(sys.argv[2]).resolve()
root.mkdir(mode=0o700, exist_ok=False)
def write(nodes, parent):
for node in nodes:
name = node["name"]
if not name or name in (".", "..") or "/" in name or "\\" in name:
raise ValueError("Invalid snapshot path")
target = parent / name
if node["type"] == "directory":
target.mkdir(mode=0o700)
write(node["children"], target)
elif node["type"] == "file":
with target.open("x", encoding="utf-8") as output:
output.write(node["content"])
target.chmod(0o600)
else:
raise ValueError("Invalid snapshot node")
write(snapshot["files"], root)
PYTHON
cd linux-agent
sha256sum -c SHA256SUMS
Mantén una sesión SSH administrativa independiente durante la configuración.
Consulta los escenarios de comprobación en VALIDATION.md.
Como administrador, prepara dos cuentas de sistema nuevas, sin grupos privilegiados
ni shell de login: linux-agent, con HOME /var/lib/linux-agent, y
linux-agent-bot, con estado /var/lib/linux-agent-bot. Ambos directorios son de su
cuenta respectiva y tienen modo 0700.
Copia los módulos Python en /opt/linux-agent y los wrappers de bin en su
subdirectorio bin: todo root:root, Python 0644 y wrappers 0755. Revisa que los
wrappers apuntan a esas rutas. Copia HARNESS.md como /opt/linux-agent/HARNESS.md.
Prepara /opt/linux-agent/workspace root:root 0755 y copia allí HARNESS.md como
AGENTS.md root:root 0644. Solo workspace/work pertenece a linux-agent, modo 0700.
El padre root-owned impide reemplazar el harness borrándolo desde una carpeta propia.
Crea /etc/linux-agent root:root 0755. Copia configuration/server.json y
configuration/runtime.json con modo 0644 y configuration/telegram.env.example
como telegram.env, root:linux-agent-bot 0640. Introduce el token del bot y los
identificadores del propietario y del chat en ese archivo. Activa los temas privados
en BotFather. Define los servicios permitidos, los montajes y los umbrales de alarma.
Mantén el token fuera de los argumentos de comandos y de los logs.
Crea /var/lib/linux-agent-ops root:linux-agent-bot 2750. Revisa el archivo sudoers
con visudo -cf, cópialo como /etc/sudoers.d/linux-agent root:root 0440 y comprueba
visudo -c. No amplíes las reglas a shells o argumentos arbitrarios.
Instala una versión revisada de Codex en una ruta root-owned, ajusta runtime.json
y autentícala como linux-agent usando su HOME. Configura el proveedor y el modelo
según tu entorno. Las nuevas sesiones usan workspace-write con aprobación
on-request.
Copia las unidades de systemd en /etc/systemd/system, root:root 0644. Tras
revisarlas, recarga systemd y activa el cierre de root al arrancar antes del bot:
sudo systemctl daemon-reload
sudo systemctl enable --now linux-agent-root-disable.service
sudo systemctl enable --now linux-agent-bot.service
sudo systemctl enable --now linux-agent-bridge.service linux-agent-monitor.timer
Comprueba el estado de los servicios y los permisos de sus archivos. En el chat
autorizado, ejecuta /help, /status y /new Mi servidor. Cada sesión queda
asociada a su tema; un fallo al crearlo interrumpe la operación.
Archivos y recuperación de sesiones
Envía documentos o imágenes en el tema de una sesión registrada. Los adjuntos se verifican y guardan con permisos 0600 en directorios 0700 separados por sesión. El agente recibe sus rutas locales; las imágenes PNG/JPEG se entregan también como entradas visuales. Las rutas permanecen estables al reintentar y los archivos se conservan después de confirmar la recepción. El límite por documento y por mensaje es 8 MiB. El contenido de los adjuntos se trata como datos no confiables.
Para devolver un documento creado en el workspace:
/opt/linux-agent/bin/send-file /opt/linux-agent/workspace/work/report.zip --thread SESSION_ID
La utilidad confirma el envío únicamente cuando Telegram lo acepta. Para reintentar
la misma entrega, conserva una clave con --key REQUEST_ID; una entrega confirmada
con esa clave no se repite. Usa rutas regulares del workspace, sin enlaces
simbólicos. Revisa el contenido antes de enviarlo y excluye secretos. La integración
puede configurarse en el agente siguiendo HARNESS.md.
Un fallo de entrega conserva el mensaje pendiente y aplaza únicamente esa sesión. Las demás siguen funcionando. El puente actualiza su heartbeat durante el trabajo; las aprobaciones del runtime siguen ligadas a su sesión y caducan en dos minutos.
Uso
| Comando | Comportamiento |
|---|---|
/new nombre | Crea una sesión/tema del agente |
/sessions | Enumera las sesiones registradas |
/status | Muestra monitorización, resultado del último job y root restante |
/updates | Simula la actualización con el índice APT disponible |
/root 15m, /root 2h | Solicita root temporal; requiere confirmación |
/root status, /root off | Consulta/revoca nuevas elevaciones |
/refresh | Refresca el índice APT; confirmación + root |
/upgrade | apt-get upgrade --with-new-pkgs; confirmación + root |
/restart nombre.service | Reinicia un servicio permitido; confirmación + root |
/reboot | Programa reinicio en un minuto; confirmación + root |
/agentstop | Solicita detener el turno en su tema; no mata el daemon |
/approve token, /deny token | Responde a una aprobación del runtime en su sesión |
Las operaciones de mantenimiento se ejecutan de forma asíncrona. Consulta /status
para comprobar su finalización y verifica el servicio afectado. El log completo
se conserva en /var/lib/linux-agent-ops/last-operation.log, accesible al
administrador; Telegram muestra el estado y el resultado de la operación.
Prepara un backup y un procedimiento de restauración antes de actualizar paquetes:
la recuperación se realiza mediante ese procedimiento.
Límites de protección
El código, las unidades, la política y el harness son root-owned. El agente no puede modificarlos sin elevación. El archivo AGENTS.md describe la conducta esperada; las cuentas, permisos y helpers constituyen la barrera técnica.
Root completo puede modificar el harness, leer secretos o crear persistencia.
NOTAFTER impide nuevas invocaciones de sudo tras caducar, incluso si falla el timer,
pero no detiene procesos ya elevados ni revierte sus cambios. El aislamiento frente
a un proceso con root requiere una VM separada y autorización externa. Los permisos del runtime son otra capa:
una ventana de sudo no desactiva automáticamente su sandbox ni sus aprobaciones.
Los permisos del runtime se configuran de forma independiente de sudo. Las tareas
administrativas predefinidas del bot se ejecutan mediante sus helpers; la
configuración inicial del runtime mantiene workspace-write y on-request.
Telegram y la conexión a Internet son dependencias externas: un servidor apagado, sin red o con el bot roto no puede alertar sobre sí mismo. Para esa situación usa un monitor exterior independiente. systemd reinicia procesos caídos; no se reinician turnos sanos por un heartbeat atrasado. El monitor local avisa de puente desconectado.
Verificación y retirada
PYTHONPATH=. python3 -m unittest discover -s tests
Antes de producción prueba: propietario incorrecto/grupo rechazados; confirmación caducada/repetida/de otro tema; root cerrado/abierto/caducado/revocado/tras reboot; permisos de código, token y sudo; bloqueo de mantenimiento; paquete simulado en VM; alarma sostenida y recuperación; caída/reinicio del runtime; routing entre dos temas; recepción de adjuntos, rechazo de rutas inválidas, entrega confirmada de documentos y reintentos de una sesión sin bloquear las demás. No uses una actualización o reinicio reales para comprobar un bot de producción.
Para retirar: cierra root desde tu acceso administrativo independiente, detén y
deshabilita linux-agent-bot, linux-agent-bridge y linux-agent-monitor.timer, y
retira reglas/unidades después de verificar que no quedan jobs o procesos elevados.
Revoca el token en BotFather y las credenciales del proveedor. Conserva auditoría
privada; no borres backups automáticamente.
Referencias y licencia
Linux Agent 0.1.0 se distribuye bajo licencia AGPL-3.0-only. Consulta LICENSE
para los términos y VALIDATION.md para las comprobaciones realizadas.
Ficheros y descargas
Linux Agent · 0.1.0
Linux Agent permite administrar servidores Debian y Ubuntu desde Telegram. Integra
sesiones de agentes, mantenimiento de paquetes y servicios, elevación temporal de
privilegios y monitorización con alertas. Requiere systemd, Python 3.11 o posterior
y sudo con soporte para NOTAFTER.
Cómo funciona
- Bot de control (
linux-agent-bot): valida propietario y chat privado, conserva el token y exige confirmaciones de un solo uso que caducan en dos minutos. - Agente (
linux-agent): cuenta separada sin grupos privilegiados ni sudo general. Codex app-server gestiona sesiones persistentes y aprobaciones del runtime. El relay solo permite registrar temas, entregar respuestas y leer/acusar mensajes. - Root temporal:
/root 15mmuestra una confirmación. El helper root valida entre un minuto y ocho horas, genera una regla conNOTAFTER, desactiva la caché de sudo y programa su retirada./root offrevoca nuevas elevaciones. Al arrancar el servidor la ventana se cierra. El modelo no tiene acceso al token del bot ni al componente que concede la ventana. - Mantenimiento: APT y reinicios se ejecutan como jobs de systemd, con bloqueo para evitar operaciones simultáneas, log root y resultado consultable. Requieren confirmación humana y una ventana root activa al comenzar.
- Alarmas: RAM, carga normalizada por CPU, ocupación de disco/inodos, servicios configurados y heartbeat del puente. Umbrales sostenidos, histéresis, deduplicación, reintento de entrega y aviso de recuperación. Las acciones correctivas se solicitan desde el bot y requieren autorización según la operación.
Preparación del servidor
Descarga linux-agent-0.1.0.agent.json desde la ficha del catálogo. El campo files
contiene el árbol de archivos y su contenido. Puedes consultarlos en el visor o
extraerlos en una carpeta nueva con el siguiente comando. La configuración de
cuentas, permisos y servicios se realiza en los pasos posteriores.
python3 - linux-agent-0.1.0.agent.json linux-agent <<'PYTHON'
import json, pathlib, sys
snapshot = json.loads(pathlib.Path(sys.argv[1]).read_text())
root = pathlib.Path(sys.argv[2]).resolve()
root.mkdir(mode=0o700, exist_ok=False)
def write(nodes, parent):
for node in nodes:
name = node["name"]
if not name or name in (".", "..") or "/" in name or "\\" in name:
raise ValueError("Invalid snapshot path")
target = parent / name
if node["type"] == "directory":
target.mkdir(mode=0o700)
write(node["children"], target)
elif node["type"] == "file":
with target.open("x", encoding="utf-8") as output:
output.write(node["content"])
target.chmod(0o600)
else:
raise ValueError("Invalid snapshot node")
write(snapshot["files"], root)
PYTHON
cd linux-agent
sha256sum -c SHA256SUMS
Mantén una sesión SSH administrativa independiente durante la configuración.
Consulta los escenarios de comprobación en VALIDATION.md.
Como administrador, prepara dos cuentas de sistema nuevas, sin grupos privilegiados
ni shell de login: linux-agent, con HOME /var/lib/linux-agent, y
linux-agent-bot, con estado /var/lib/linux-agent-bot. Ambos directorios son de su
cuenta respectiva y tienen modo 0700.
Copia los módulos Python en /opt/linux-agent y los wrappers de bin en su
subdirectorio bin: todo root:root, Python 0644 y wrappers 0755. Revisa que los
wrappers apuntan a esas rutas. Copia HARNESS.md como /opt/linux-agent/HARNESS.md.
Prepara /opt/linux-agent/workspace root:root 0755 y copia allí HARNESS.md como
AGENTS.md root:root 0644. Solo workspace/work pertenece a linux-agent, modo 0700.
El padre root-owned impide reemplazar el harness borrándolo desde una carpeta propia.
Crea /etc/linux-agent root:root 0755. Copia configuration/server.json y
configuration/runtime.json con modo 0644 y configuration/telegram.env.example
como telegram.env, root:linux-agent-bot 0640. Introduce el token del bot y los
identificadores del propietario y del chat en ese archivo. Activa los temas privados
en BotFather. Define los servicios permitidos, los montajes y los umbrales de alarma.
Mantén el token fuera de los argumentos de comandos y de los logs.
Crea /var/lib/linux-agent-ops root:linux-agent-bot 2750. Revisa el archivo sudoers
con visudo -cf, cópialo como /etc/sudoers.d/linux-agent root:root 0440 y comprueba
visudo -c. No amplíes las reglas a shells o argumentos arbitrarios.
Instala una versión revisada de Codex en una ruta root-owned, ajusta runtime.json
y autentícala como linux-agent usando su HOME. Configura el proveedor y el modelo
según tu entorno. Las nuevas sesiones usan workspace-write con aprobación
on-request.
Copia las unidades de systemd en /etc/systemd/system, root:root 0644. Tras
revisarlas, recarga systemd y activa el cierre de root al arrancar antes del bot:
sudo systemctl daemon-reload
sudo systemctl enable --now linux-agent-root-disable.service
sudo systemctl enable --now linux-agent-bot.service
sudo systemctl enable --now linux-agent-bridge.service linux-agent-monitor.timer
Comprueba el estado de los servicios y los permisos de sus archivos. En el chat
autorizado, ejecuta /help, /status y /new Mi servidor. Cada sesión queda
asociada a su tema; un fallo al crearlo interrumpe la operación.
Archivos y recuperación de sesiones
Envía documentos o imágenes en el tema de una sesión registrada. Los adjuntos se verifican y guardan con permisos 0600 en directorios 0700 separados por sesión. El agente recibe sus rutas locales; las imágenes PNG/JPEG se entregan también como entradas visuales. Las rutas permanecen estables al reintentar y los archivos se conservan después de confirmar la recepción. El límite por documento y por mensaje es 8 MiB. El contenido de los adjuntos se trata como datos no confiables.
Para devolver un documento creado en el workspace:
/opt/linux-agent/bin/send-file /opt/linux-agent/workspace/work/report.zip --thread SESSION_ID
La utilidad confirma el envío únicamente cuando Telegram lo acepta. Para reintentar
la misma entrega, conserva una clave con --key REQUEST_ID; una entrega confirmada
con esa clave no se repite. Usa rutas regulares del workspace, sin enlaces
simbólicos. Revisa el contenido antes de enviarlo y excluye secretos. La integración
puede configurarse en el agente siguiendo HARNESS.md.
Un fallo de entrega conserva el mensaje pendiente y aplaza únicamente esa sesión. Las demás siguen funcionando. El puente actualiza su heartbeat durante el trabajo; las aprobaciones del runtime siguen ligadas a su sesión y caducan en dos minutos.
Uso
| Comando | Comportamiento |
|---|---|
/new nombre | Crea una sesión/tema del agente |
/sessions | Enumera las sesiones registradas |
/status | Muestra monitorización, resultado del último job y root restante |
/updates | Simula la actualización con el índice APT disponible |
/root 15m, /root 2h | Solicita root temporal; requiere confirmación |
/root status, /root off | Consulta/revoca nuevas elevaciones |
/refresh | Refresca el índice APT; confirmación + root |
/upgrade | apt-get upgrade --with-new-pkgs; confirmación + root |
/restart nombre.service | Reinicia un servicio permitido; confirmación + root |
/reboot | Programa reinicio en un minuto; confirmación + root |
/agentstop | Solicita detener el turno en su tema; no mata el daemon |
/approve token, /deny token | Responde a una aprobación del runtime en su sesión |
Las operaciones de mantenimiento se ejecutan de forma asíncrona. Consulta /status
para comprobar su finalización y verifica el servicio afectado. El log completo
se conserva en /var/lib/linux-agent-ops/last-operation.log, accesible al
administrador; Telegram muestra el estado y el resultado de la operación.
Prepara un backup y un procedimiento de restauración antes de actualizar paquetes:
la recuperación se realiza mediante ese procedimiento.
Límites de protección
El código, las unidades, la política y el harness son root-owned. El agente no puede modificarlos sin elevación. El archivo AGENTS.md describe la conducta esperada; las cuentas, permisos y helpers constituyen la barrera técnica.
Root completo puede modificar el harness, leer secretos o crear persistencia.
NOTAFTER impide nuevas invocaciones de sudo tras caducar, incluso si falla el timer,
pero no detiene procesos ya elevados ni revierte sus cambios. El aislamiento frente
a un proceso con root requiere una VM separada y autorización externa. Los permisos del runtime son otra capa:
una ventana de sudo no desactiva automáticamente su sandbox ni sus aprobaciones.
Los permisos del runtime se configuran de forma independiente de sudo. Las tareas
administrativas predefinidas del bot se ejecutan mediante sus helpers; la
configuración inicial del runtime mantiene workspace-write y on-request.
Telegram y la conexión a Internet son dependencias externas: un servidor apagado, sin red o con el bot roto no puede alertar sobre sí mismo. Para esa situación usa un monitor exterior independiente. systemd reinicia procesos caídos; no se reinician turnos sanos por un heartbeat atrasado. El monitor local avisa de puente desconectado.
Verificación y retirada
PYTHONPATH=. python3 -m unittest discover -s tests
Antes de producción prueba: propietario incorrecto/grupo rechazados; confirmación caducada/repetida/de otro tema; root cerrado/abierto/caducado/revocado/tras reboot; permisos de código, token y sudo; bloqueo de mantenimiento; paquete simulado en VM; alarma sostenida y recuperación; caída/reinicio del runtime; routing entre dos temas; recepción de adjuntos, rechazo de rutas inválidas, entrega confirmada de documentos y reintentos de una sesión sin bloquear las demás. No uses una actualización o reinicio reales para comprobar un bot de producción.
Para retirar: cierra root desde tu acceso administrativo independiente, detén y
deshabilita linux-agent-bot, linux-agent-bridge y linux-agent-monitor.timer, y
retira reglas/unidades después de verificar que no quedan jobs o procesos elevados.
Revoca el token en BotFather y las credenciales del proveedor. Conserva auditoría
privada; no borres backups automáticamente.
Referencias y licencia
Linux Agent 0.1.0 se distribuye bajo licencia AGPL-3.0-only. Consulta LICENSE
para los términos y VALIDATION.md para las comprobaciones realizadas.
Versiones (1)
| Versión | Descargas (semana) | Descargas (total) | Publicación |
|---|---|---|---|
0.1.0latest Primera versión publicada. | 0 | 3 | 12 de octubre de 2026 |