starrycli 0.1.0
dotnet tool install --global starrycli --version 0.1.0
dotnet new tool-manifest
dotnet tool install --local starrycli --version 0.1.0
#tool dotnet:?package=starrycli&version=0.1.0
nuke :add-package starrycli --version 0.1.0
🌟 STARRY
<p align="center"> <img src="site/public/logo.svg" width="128" height="128" alt="Starry Logo" /> </p>
<p align="center"> <strong>Decentralized GitOps Orchestrator for Docker, Podman, WireGuard, nftables, and VPS Fleets</strong> </p>
<p align="center"> <a href="https://github.com/perdub/starry/actions/workflows/ci.yml"><img src="https://github.com/perdub/starry/actions/workflows/ci.yml/badge.svg" alt="CI Status" /></a> <a href="https://github.com/perdub/starry/actions/workflows/ci-full-matrix.yml"><img src="https://github.com/perdub/starry/actions/workflows/ci-full-matrix.yml/badge.svg" alt="Matrix CI" /></a> <a href="https://perdub.github.io/starry/"><img src="https://img.shields.io/badge/Docs-VitePress-f59e0b" alt="Documentation" /></a> <a href="https://www.nuget.org/packages/starrycli"><img src="https://img.shields.io/nuget/v/starrycli.svg?color=blue" alt="NuGet" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License" /></a> </p>
📖 Overview
starry is an autonomous, single-binary GitOps orchestrator designed to run across heterogeneous cloud providers and low-cost virtual private servers (including NAT-isolated nodes and servers with small 10–20 GB SSDs).
It manages the entire lifecycle of:
- Container Runtimes: Direct Unix Domain Socket control of Docker Engine and Podman (Rootful & unprivileged Rootless).
- Encrypted Mesh Networking: P2P WireGuard (
starry0) with automated NAT traversal (PersistentKeepalive = 25) and Roaming Container VIPs (10.99.x.x). - Host Firewalls & NAT: Isolated table
inet starryinnftablesfor atomic DNAT port forwarding and strict packet filtering. - Operating System Packages: Unified abstraction across Apt (Debian/Ubuntu), Dnf (RHEL/AlmaLinux/Rocky/Fedora), Apk (Alpine), and Pacman (Arch Linux) with rolling security updates.
- Security & Secret Management: In-repository encrypted secrets using AES-256-GCM bound to canonical JSON paths with AAD (Additional Authenticated Data) to block cut-and-paste tampering.
- Zero-Disk Streaming Backups: Real-time volume backups via
tar | zstd | rclone rcatwithout creating intermediate files on constrained VPS disks. - Disaster Recovery Bundles: Export and re-import entire fleet configurations and states to spin up on new IP addresses within minutes.
Documentation is available online at: https://perdub.github.io/starry/ (available in English and Russian).
⚡ Quick Start
1. Installation
Option A: .NET Global Tool
dotnet tool install -g starrycli
Option B: Standalone Native AOT Binary (7.3 MB, Zero Dependencies)
Download the pre-compiled native binary for Linux (x64, arm64) from GitHub Releases:
curl -fsSL https://github.com/perdub/starry/releases/latest/download/starry-linux-x64 -o /usr/local/bin/starry
chmod +x /usr/local/bin/starry
2. Configuration (starry.yaml or Modular Directory)
Starry supports single-file configurations as well as modular multi-file directories (YAML, JSON, TOML):
version: "1.0"
cluster_name: "kessoku-prod"
mesh:
cidr: "10.99.0.0/16"
port: 51820
keepalive: 25
nodes:
bocchi:
host: "198.51.100.10"
port: 22
vpn_ip: "10.99.0.1"
is_public: true
ssh_key: "ENC[AES256_GCM:v1:...]"
services:
web:
image: "nginx:alpine"
node: "bocchi"
vip: "10.99.10.5"
priority: 80
ports:
- "80:80"
- "443:443"
files:
/etc/nginx/conf.d/default.conf: |
server {
listen 80;
location / { return 200 "Hello from Starry!"; }
}
3. Validate, Plan & Apply
# Validate cluster syntax, schema and secrets integrity
starry config validate ./cluster
# Build DAG migration execution plan
starry plan --config ./cluster
# Apply planned changes
starry apply --config ./cluster
🛠️ CLI Commands Reference
| Command | Description |
|---|---|
starry config validate [path] |
Validate configuration schema, references, and secret envelopes. |
starry config pack <dir> -o <file> |
Pack modular directory hierarchy into a single bundle file. |
starry config split <file> -o <dir> |
Split monolithic bundle back into modular folder structure. |
starry config fmt <file> |
Canonically format configuration files. |
starry config schema |
Print official JSON Schema for IDE autocompletion. |
starry encrypt [path] |
Encrypt all PLAIN[...] secrets in configuration into ENC[...]. |
starry encrypt global --reencrypt |
Rotate master key, re-encrypt all secrets, and commit to Git. |
starry nodes upgrade --rolling |
Execute zero-downtime rolling OS security updates across nodes. |
starry nodes rotate-keys |
Generate fresh Ed25519 SSH keys and update remote authorized_keys. |
starry plan |
Generate and visualize DAG migration graph with colored icons. |
starry apply |
Execute planned actions across the cluster fleet. |
starry volume open <node> <vol> |
Open remote container volume via secure SFTP tunnel. |
starry bundle export -o <archive> |
Export entire fleet into a disaster recovery capsule. |
starry bundle import <archive> |
Restore fleet capsule with optional --override-ip mappings. |
🔒 Security Architecture: AES-256-GCM + AAD
Starry uses Authenticated Encryption with Associated Data (AEAD):
- Cipher: AES-256-GCM with a 32-byte master key, 12-byte random nonce, and 16-byte authentication tag.
- AAD Binding: Every secret embeds its exact canonical JSON path (e.g.
nodes.bocchi.ssh_key) into the authentication tag. Moving an encrypted string to another field will fail decryption withCryptographicException! - Automated Key Rotation: Monthly automated rotation in GitHub Actions (
.github/workflows/rotate-master-key.yml).
🤝 Contributing & Architecture
- Built on C# (.NET 10) targeting Native AOT and NuGet Tool packaging.
- Clean architecture with zero third-party bloated Docker SDKs: pure Unix Domain Sockets over
SocketsHttpHandler. - Strict static analysis enforced with
TreatWarningsAsErrors=true,Meziantou.Analyzer,Roslynator, andSonarAnalyzer.
# Clone and build
git clone https://github.com/perdub/starry.git
cd starry
dotnet build Starry.slnx
# Run 57 Unit, Chaos, and E2E Tests
dotnet test Starry.slnx
📄 License
Licensed under the MIT License.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
This package has no dependencies.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.1.0 | 109 | 11/1/2026 |