Platypus

Un hub de gestion d'hôtes pour des flottes de machines Linux. Installez l'agent Platypus sur chaque hôte que vous possédez ; l'agent rappelle votre serveur Platypus via TLS + protobuf ; depuis le serveur, vous obtenez un shell interactif, une gestion de fichiers et un tunneling réseau sur chaque hôte géré — via un plan de contrôle central.

Captures d'écran

Une interface utilisateur à navigation plate de style Vercel avec un tableau de bord de projet, un navigateur d'hôtes/listeners/sessions, une console de répartition multi-hôtes et un gestionnaire d'utilisateurs admin. Voir la galerie complète sur docs/screenshots/. Relancez make screenshots pour les régénérer à partir de l'application en direct.

Architecture

Platypus est fourni sous forme de deux binaires backend plus un client de bureau autonome :

Binaire	Rôle
platypus-server	Démon. Accepte les connexions agents entrantes sur les ports TLS ingress ; expose une API REST + WebSocket pour les outils d'administration ; sert les binaires agents pour la distribution.
platypus-agent	Le processus qui s'exécute sur chaque hôte géré. Rappelle le serveur via TLS + protobuf.
platypus-desktop	Interface graphique native (Wails v2). Connectez-vous à tout serveur accessible avec URL + secret ; interface à onglets pour sessions, terminaux, listeners, fichiers, tunnels. Voir desktop/.

Le serveur est purement une API — pas d'interface web intégrée. Plusieurs bureaux peuvent se connecter au même serveur simultanément.

Fonctionnalités

• Canal TLS + protobuf entre l'agent et le serveur
• Plusieurs ports d'entrée (ingress) pour que des flottes dans différents réseaux partagent un même hub
• Shell interactif par hôte, diffusé via WebSocket
• Lecture/écriture/téléchargement/upload de fichiers avec transfert par morceaux
• Tunnels réseau : local-port-forward, remote-port-forward, SOCKS5 dynamique
• API REST authentifiée par jeton Bearer
• Python SDK
• Démarrage automatique des listeners depuis config.yml
• Arrêt gracieux (draine les connexions sur SIGINT/SIGTERM en 30s)

Documents

• Chinese | 中文文档

Démarrage rapide

Déploiement en un clic (Recommandé)

Le moyen le plus rapide d'obtenir un système Platypus complet (comprenant le serveur, l'interface Web et un distributeur d'agents basé sur MinIO) est d'utiliser Docker Compose :

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

• Interface Web : Ouvrez https://localhost:9443 dans votre navigateur (le conteneur est livré avec un certificat auto-signé ; votre navigateur vous demandera de l'accepter lors de la première visite).
• Connexion : Le bootstrap_secret est écrit dans /app/data/bootstrap.secret à l'intérieur du conteneur lors du premier démarrage (mode 0600). Lisez-le avec docker compose exec platypus-server cat /app/data/bootstrap.secret, utilisez-le une fois pour créer le premier administrateur, puis supprimez le fichier. Une fois l'amorçage terminé, le secret n'est plus accepté.
• Ajouter des agents : Cliquez sur "Add Agent" dans l'interface pour obtenir une commande en une ligne curl ... | sh, signée et épinglée au CA du projet, pour déployer des agents sur votre flotte.

Construire à partir des sources

Nécessite Go 1.24+ et protoc (uniquement si vous régénérez le code protobuf).

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

Autres cibles utiles : make test, make lint, make snapshot (multi-plateforme via goreleaser), make help.

Développement (hooks pre-commit)

Les contributeurs devraient installer les hooks git pour que gofmt / goimports / go vet / golangci-lint s'exécutent avant chaque commit :

pip install pre-commit   # or: pipx install pre-commit
make hooks               # one-time: wires .git/hooks/pre-commit
make pre-commit          # optional: run all hooks against every file now

Construire l'application de bureau

Nécessite Node 22+, les dépendances Wails CLI (wails doctor) et les bibliothèques WebView de la plateforme (webkit2gtk-4.1 sur Linux, WebView2 sur Windows, WKWebView sur macOS).

make desktop-deps       # one-time: install Wails CLI + pnpm packages
make desktop-build      # → desktop/build/bin/platypus-desktop
make desktop-dev        # hot-reload dev mode

Ou : utiliser l'interface Web autonome (sans installation)

Mêmes pages, mêmes fonctionnalités (sauf le push d'événements en temps réel), fonctionne dans n'importe quel navigateur :

make web-ui             # → desktop/frontend/dist-web/ (static bundle)
make web-ui-serve       # preview at http://localhost:8080

dist-web/ est entièrement statique ; déposez-le sur GitHub Pages / S3 / nginx. Pointez-le vers n'importe quel platypus-server via le formulaire de connexion.

Notes complètes dans desktop/README.md.

Installer à partir des binaires de version

Téléchargez l'archive appropriée pour votre OS/arch depuis la page des versions, extrayez-la et exécutez-la.

Exécuter avec 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 active le recours au KEK sur disque pour qu'un démarrage frais « fonctionne directement » ; en production, supprimez cette variable d'environnement et définissez PLATYPUS_CA_KEK (32 octets hexadécimaux ; openssl rand -hex 32) à la place pour que la clé de chiffrement de la clé privée du CA ne soit jamais écrite à côté de la base de données chiffrée.

Exécuter

./build/platypus-server                # foreground ; Ctrl-C for graceful shutdown

En production, exécutez le serveur sous systemd plutôt que de le mettre en arrière-plan manuellement.

Mises en garde pour la production