Platypus

Un hub di gestione degli host per flotte di macchine Linux. Installa l'agente Platypus su ogni host che possiedi; l'agente si riconnette al tuo server Platypus tramite TLS + protobuf; dal server ottieni una shell interattiva, gestione dei file e tunneling di rete su ogni host gestito — attraverso un unico pannello di controllo centrale.

Screenshot

Un'interfaccia utente a navigazione piatta stile Vercel con una dashboard di progetto, un browser per host/listener/sessioni, una console di dispatch multi-host e un gestore utenti amministrativi. Vedi la galleria completa in docs/screenshots/. Esegui di nuovo make screenshots per rigenerarli dall'app live.

Architettura

Platypus viene fornito come due binari backend più un client desktop standalone:

Binario	Ruolo
platypus-server	Demone. Accetta connessioni agent in entrata sulle porte TLS; espone un'API REST + WebSocket per gli strumenti di amministrazione; serve i binari dell'agente per la distribuzione.
platypus-agent	Il processo che viene eseguito su ogni host gestito. Si riconnette al server tramite TLS + protobuf.
platypus-desktop	GUI desktop nativa (Wails v2). Collegati a qualsiasi server raggiungibile con URL + secret; interfaccia a schede per sessioni, terminali, listener, file, tunnel. Vedi desktop/.

Il server è puramente un'API — nessuna interfaccia web integrata. Più desktop possono connettersi allo stesso server contemporaneamente.

Funzionalità

• Canale TLS + protobuf tra agente e server
• Più porte di ingresso in modo che flotte in reti diverse condividano un unico hub
• Shell interattiva per host, trasmessa tramite WebSocket
• Lettura / scrittura / upload / download di file con trasferimento a blocchi
• Tunnel di rete: forward porta locale, forward porta remota, SOCKS5 dinamico
• API REST autenticata con token Bearer
• Python SDK
• Avvio automatico dei listener da config.yml
• Arresto graduale (scarica le connessioni su SIGINT/SIGTERM entro 30 secondi)

Documenti

• Cinese | 中文文档

Avvio rapido

Distribuzione con un clic (Consigliata)

Il modo più veloce per ottenere un sistema Platypus completo (inclusi Server, Web UI e un Distributore di Agenti basato su MinIO) è usare Docker Compose:

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

• Web UI: Apri https://localhost:9443 nel tuo browser (il container viene fornito con un certificato auto-firmato; il browser ti chiederà di accettarlo al primo accesso).
• Login: Il bootstrap_secret viene scritto in /app/data/bootstrap.secret all'interno del container al primo avvio (modalità 0600). Leggilo con docker compose exec platypus-server cat /app/data/bootstrap.secret, usalo una volta per creare il primo amministratore, poi elimina il file. Dopo il completamento del bootstrap il secret non viene più accettato.
• Aggiungere agenti: Clicca "Add Agent" nell'interfaccia per ottenere un comando curl ... | sh su una riga, firmato e associato alla CA del progetto, per distribuire agenti nella tua flotta.

Compilare dal sorgente

Richiede Go 1.24+ e protoc (solo se rigeneri il codice protobuf).

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

Altri target utili: make test, make lint, make snapshot (cross-platform tramite goreleaser), make help.

Sviluppo (hook pre-commit)

I contributori dovrebbero installare gli hook git in modo che gofmt / goimports / go vet / golangci-lint vengano eseguiti prima di ogni commit:

pip install pre-commit   # oppure: pipx install pre-commit
make hooks               # una tantum: collega .git/hooks/pre-commit
make pre-commit          # opzionale: esegui tutti gli hook su ogni file ora

Compilare l'app desktop

Richiede Node 22+, dipendenze Wails CLI (wails doctor) e le librerie WebView della piattaforma (webkit2gtk-4.1 su Linux, WebView2 su Windows, WKWebView su macOS).

make desktop-deps       # una tantum: installa Wails CLI + pacchetti pnpm
make desktop-build      # → desktop/build/bin/platypus-desktop
make desktop-dev        # modalità sviluppo con hot-reload

Oppure: usa l'interfaccia web standalone (nessuna installazione)

Stesse pagine, stesse funzionalità (tranne il push di eventi in tempo reale), funziona in qualsiasi browser:

make web-ui             # → desktop/frontend/dist-web/ (bundle statico)
make web-ui-serve       # anteprima su http://localhost:8080

dist-web/ è completamente statico; caricalo su GitHub Pages / S3 / nginx. Puntalo a qualsiasi platypus-server tramite il modulo di login.

Note complete in desktop/README.md.

Installare dai binari di rilascio

Scarica l'archivio appropriato per il tuo sistema operativo/architettura dalla pagina Releases, estrai ed esegui.

Eseguire 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 abilita il fallback KEK su disco in modo che un avvio fresco "funzioni subito"; per produzione, rimuovi quella variabile d'ambiente e imposta PLATYPUS_CA_KEK (32 byte esadecimali; openssl rand -hex 32) in modo che la chiave di crittografia della chiave privata CA non venga mai scritta accanto al database crittografato.

Eseguire

./build/platypus-server                # in primo piano; Ctrl-C per arresto graduale

Per produzione, esegui il server sotto systemd piuttosto che metterlo in background manualmente.

Avvertenze per la produzione