Getting Started with Starry
Welcome to the Starry quickstart guide! This tutorial guides you through installing the CLI, initializing your infrastructure GitOps repository, bootstrapping server nodes, and deploying your first containerized services.
1. CLI Installation
Starry is distributed in two official formats: as a self-contained Native AOT executable (requiring zero runtime dependencies) and as a global .NET Tool.
# Download the latest binary for your architecture
curl -fsSL https://github.com/starry-project/starry/releases/latest/download/starry-linux-x64 -o starry
# Grant execution permissions
chmod +x starry
# Move binary to system PATH
sudo mv starry /usr/local/bin/starry
# Verify installation
starry --version# Install via .NET SDK (.NET 10+ required)
dotnet tool install -g starrycli
# Verify command availability
starry --version# Download and setup in PowerShell
Invoke-WebRequest -Uri "https://github.com/starry-project/starry/releases/latest/download/starry-win-x64.exe" -OutFile "$HOME\starry.exe"
# Add to user PATH
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$HOME", "User")
starry --version2. Initializing the Repository
To manage your fleet using declarative GitOps patterns, create a dedicated Git repository and initialize Starry:
mkdir my-fleet && cd my-fleet
git init
starry initThe starry init command creates the initial project layout:
my-fleet/
├── starry.yaml # Main declarative cluster manifest
├── .starry/
│ ├── keys/ # Local SSH & WireGuard keys (git-ignored)
│ └── cache/ # Local state cache
├── .gitignore # Ignores private keys and runtime artifacts
└── README.md3. Configuring Master Encryption Key
Starry employs AES-256-GCM authenticated envelope encryption with PBKDF2/Argon2 key derivation. Sensitive tokens, database credentials, and certificates are safely committed directly into starry.yaml.
Generating a Master Key
Generate a cryptographically secure 256-bit key:
starry secret keygenExport the generated base64 string to your environment:
export STARRY_MASTER_KEY="your-generated-base64-master-key"CI/CD Automation
When running automated workflows in GitHub Actions or GitLab CI, set the STARRY_MASTER_KEY repository secret.
Encrypting Secrets
To encrypt confidential values:
starry secret encrypt "my-super-secret-password"The command returns an authenticated envelope: ENC[AES256_GCM,data:c3VwZXJzZWNyZXQ=,iv:...,tag:...]
Paste this value directly into the env or secrets block of your starry.yaml.
4. Bootstrapping Server Nodes
Prepare a clean Linux server running any supported distribution (Ubuntu, Debian, AlmaLinux, Rocky Linux, Alpine, or Arch).
Run the automated bootstrap command:
starry nodes bootstrap root@203.0.113.10 --name node-01 --engine dockerDuring the bootstrap process, Starry will:
- Connect via SSH and inspect host capabilities.
- Install the specified container engine (
dockerorpodman) if missing. - Install and configure
wireguard-toolsandnftables. - Generate WireGuard keys and assign a mesh IP from
10.42.0.0/16. - Append the validated node entry into
starry.yaml.
5. Planning and Applying Changes
Edit your starry.yaml file to define desired state:
version: "3.0"
mesh:
prefix: "fd67:b00b::/32"
port: 51820
nodes:
node-01:
ssh: "root@203.0.113.10:22"
engine: "docker"
services:
web:
image: "nginx:alpine"
node: "node-01"
ports:
- "80:80"
env:
API_SECRET: "ENC[AES256_GCM:v1:...]"Dry Run (Plan)
Preview planned configuration changes without executing mutations:
starry planStarry reconciles desired state against live servers and displays an actionable diff (container creates/updates, firewall rule adjustments, package installs).
Apply
Enforce desired state across your fleet:
starry apply6. Running the Server Agent Daemon
For autonomous health checking, automatic container restarts, and real-time monitoring, Starry features a lightweight server agent.
Install the systemd service on your target server:
sudo starry agent install-service
sudo systemctl status starry-agentOr run the agent in the foreground for debugging:
starry agent run --verboseCongratulations! Your initial Starry cluster is up, running, and secured. Proceed to the Architecture Overview to explore the system internals.