Platypus

Un centro de gestión de hosts para flotas de máquinas Linux. Instala el agente Platypus en cada host que poseas; el agente se conecta de vuelta a tu servidor Platypus a través de TLS + protobuf; desde el servidor obtienes una shell interactiva, gestión de archivos y túneles de red en cada host gestionado — todo desde un único plano de control central.

Capturas de pantalla

Una interfaz de navegación plana estilo Vercel con un panel de proyecto, un navegador de hosts/listeners/sesiones, una consola de envío multi-host y un gestor de usuarios administrador. Consulta la galería completa en docs/screenshots/. Vuelve a ejecutar make screenshots para regenerarlas desde la aplicación en vivo.

Arquitectura

Platypus se distribuye como dos binarios de backend más un cliente de escritorio independiente:

El servidor es puramente una API — no tiene interfaz web integrada. Varios escritorios pueden conectarse al mismo servidor simultáneamente.

Características

• Canal TLS + protobuf entre agente y servidor
• Múltiples puertos de ingreso para que flotas en diferentes redes compartan un mismo hub
• Shell interactiva por host, transmitida a través de WebSocket
• Lectura / escritura / subida / bajada de archivos con transferencia por fragmentos
• Túneles de red: reenvío de puerto local, reenvío de puerto remoto, SOCKS5 dinámico
• API REST autenticada con token Bearer
• Python SDK
• Listeners de inicio automático desde config.yml
• Apagado ordenado (drena conexiones en SIGINT/SIGTERM en 30 segundos)

Documentos

• Chino | 中文文档

Inicio rápido

Despliegue con un clic (Recomendado)

La forma más rápida de poner en marcha un sistema Platypus completo (incluyendo el Servidor, la Interfaz Web y un Distribuidor de Agentes respaldado por MinIO) es usando Docker Compose:

git clone https://github.com/WangYihang/Platypus
cd Platypus
docker-compose up -d

• Interfaz Web: Abre https://localhost:9443 en tu navegador (el contenedor incluye un certificado autofirmado; tu navegador te pedirá que lo aceptes en la primera visita).
• Inicio de sesión: El bootstrap_secret se escribe en /app/data/bootstrap.secret dentro del contenedor en el primer arranque (modo 0600). Léelo con docker compose exec platypus-server cat /app/data/bootstrap.secret, úsalo una vez para crear el primer administrador y luego elimina el archivo. Tras completar el bootstrap, el secreto ya no será aceptado.
• Añadir Agentes: Haz clic en "Add Agent" en la interfaz para obtener un comando de una línea curl ... | sh, firmado y vinculado a la CA del proyecto, para desplegar agentes en tu flota.

Compilar desde el código fuente

Requiere Go 1.24+ y protoc (solo si se regenera el código protobuf).

git clone https://github.com/WangYihang/Platypus
cd Platypus
make build              # → ./build/{platypus-server,platypus-agent}

Otros targets útiles: make test, make lint, make snapshot (multiplataforma mediante goreleaser), make help.

Desarrollo (ganchos pre-commit)

Los colaboradores deben instalar los ganchos de git para que gofmt / goimports / go vet / golangci-lint se ejecuten antes de cada commit:

pip install pre-commit   # o: pipx install pre-commit
make hooks               # una vez: configura .git/hooks/pre-commit
make pre-commit          # opcional: ejecuta todos los ganchos sobre todos los archivos ahora

Compilar la aplicación de escritorio

Requiere Node 22+, dependencias de Wails CLI (wails doctor) y las bibliotecas WebView de la plataforma (webkit2gtk-4.1 en Linux, WebView2 en Windows, WKWebView en macOS).

make desktop-deps       # una vez: instala Wails CLI + paquetes pnpm
make desktop-build      # → desktop/build/bin/platypus-desktop
make desktop-dev        # modo desarrollo con recarga en caliente

O: usar la interfaz web independiente (sin instalación)

Las mismas páginas, las mismas funciones (excepto la notificación de eventos en tiempo real), funciona en cualquier navegador:

make web-ui             # → desktop/frontend/dist-web/ (paquete estático)
make web-ui-serve       # vista previa en http://localhost:8080

dist-web/ es completamente estático; súbelo a GitHub Pages / S3 / nginx. Apúntalo a cualquier platypus-server mediante el formulario de inicio de sesión.

Notas completas en desktop/README.md.

Instalar desde los binarios de las versiones

Descarga el archivo adecuado para tu sistema operativo/arquitectura desde la página de versiones, extráelo y ejecútalo.

Ejecutar con Docker

docker build -t platypus-server .
docker run --rm -p 9443:9443 \
  -e PLATYPUS_DEV=1 \
  -v $(pwd)/config.yml:/config.yml \
  platypus-server

PLATYPUS_DEV=1 habilita la alternativa de KEK en disco para que un inicio fresco "funcione sin más"; para producción, elimina esa variable de entorno y establece PLATYPUS_CA_KEK (32 bytes en hex; openssl rand -hex 32) para que la clave de cifrado de la clave privada de la CA nunca se escriba junto a la base de datos cifrada.

Ejecutar

./build/platypus-server                # en primer plano; Ctrl-C para apagado ordenado

Para producción, ejecuta el servidor bajo systemd en lugar de ponerlo en segundo plano manualmente.

Advertencias de producción

• Solo una instancia. El verificador de tokens opacos almacena en caché los tokens verificados en un LRU por proceso. La revocación (cierre de sesión, cambio de contraseña, revocación de AAT, eliminación de usuario) elimina la entrada en el mismo proceso de forma síncrona, pero un despliegue con múltiples réplicas no tiene un canal de invalidación entre procesos hoy en día, por lo que un token revocado puede seguir funcionando en otras réplicas durante el TTL de la caché (30s). No ejecutes más de un platypus-server contra la misma BD hasta que llegue la revocación entre procesos. La escala vertical + una espera en alta disponibilidad es la forma compatible; las réplicas horizontales con balanceo de carga no lo son.
• PLATYPUS_CA_KEK en el entorno. La clave privada de la CA está sellada con AES-256-GCM contra este valor hexadecimal de 32 bytes. Sin él, el servidor se niega a iniciar a menos que también esté presente PLATYPUS_DEV=1 (que habilita una alternativa solo para desarrollo en disco en <data-dir>/ca.kek — inseguro para producción porque el texto cifrado y la clave terminan en el mismo volumen).
• Ventana de escritorio, sin diseño móvil (todavía). La interfaz web está orientada a ventanas ≥ 1280px; la barra lateral / barra de estado / barra de navegación ocupa ~300px, dejando el cuerpo del contenido en el punto óptimo de lectura de 80–100 caracteres. No hay colapso responsive para ventanas estrechas hoy en día — las ventanas inferiores a 1024px mostrarán barras de desplazamiento horizontales en las tablas. El soporte para tabletas / teléfonos está en la lista de tareas pendientes (P4 en la auditoría de UX) pero no es bloqueante; el trabajo de administración es trabajo de escritorio.
• Credenciales del almacén de objetos. Cuando el distribuidor está habilitado (distributor.store.endpoint establecido), establece PLATYPUS_DISTRIBUTOR_STORE_ACCESS_KEY_ID y PLATYPUS_DISTRIBUTOR_STORE_SECRET_ACCESS_KEY en lugar de incluirlos en . El incluido se distribuye con los campos YAML en blanco por esa razón.

Uso

Topología

• Servidor: 192.168.88.129
  • Ingress TLS unificado (API REST + enlace de agente + instalador): 0.0.0.0:9443
• Host gestionado: 192.168.88.130 (ejecuta platypus-agent)

Visita rápida

Primero, ejecuta ./platypus-server. Se genera un config.yml a partir de assets/config.example.yml si no existe ninguno. Los valores predeterminados son razonables.

Para inscribir un nuevo host gestionado:

1. Abre la interfaz web / aplicación de escritorio, navega al proyecto, haz clic en Add Agent.
2. Selecciona el SO / arquitectura objetivo y TTL, haz clic en Generate.
3. Copia el comando de una línea que muestra la interfaz y ejecútalo en el host gestionado.

El comando de una línea generado por el servidor tiene el siguiente aspecto:

curl -fsSL https://<server>:9443/api/v1/install/<one-shot-token> | sh

El token de instalación de un solo uso caduca poco después de su emisión y se consume en el primer acierto exitoso. El script que devuelve el servidor:

• incrusta la CA del proyecto para que la descarga del binario del agente se verifique con curl --cacert (sin -k, sin TOFU);
• inyecta un PAT de un solo uso para que el agente pueda completar la inscripción y obtener su certificado de cliente mTLS;
• se niega a ejecutarse si el servidor no tiene una CA de proyecto configurada, a menos que el operador establezca explícitamente PLATYPUS_INSECURE_DOWNLOAD=1.

No escribas manualmente URLs curl http://... contra la ruta /agent/<host>:<port> heredada — ese flujo se ha eliminado. Siempre renderiza el comando de instalación a través de la interfaz para que lleve el ancla de confianza.

Escritorio / Web

Abre la aplicación de escritorio (platypus-desktop) o la interfaz web (make web-ui-serve), rellena la URL del servidor y el secreto, y ya estás dentro. Pestañas: Sessions (cada agente que se haya conectado), Terminal, Files, Tunnels, Listeners.

Usos avanzados

• API REST
• Python SDK

Otros materiales

• Presentación en KCon 2019
• Presentación en GCSIS 2021

Contribuidores

Este proyecto existe gracias a todas las personas que contribuyen.

Patrocinadores

Gracias a todos nuestros patrocinadores. 🙏 [Conviértete en patrocinador]

Sponsors

Apoya este proyecto convirtiéndote en sponsor. Tu logo aparecerá aquí con un enlace a tu sitio web. [Conviértete en sponsor]