CLI-first server inventory management with YAML as the single source of truth
rostr is a lightweight, CLI-first server inventory system that uses YAML files as the single source of truth. It automatically generates SSH configs, Ansible inventories, and more from your inventory files.
- YAML-based inventory - Simple, readable, version-controllable
- SSH config generation - Auto-generate
~/.ssh/configentries - Ansible inventory - Dynamic inventory with groups by tag, OS, and notes
- Fuzzy SSH matching -
rostr ssh webmatchesweb-prod-01 - OS auditing - Detect OS mismatches via parallel SSH
- Git sync - Auto-commit and push inventory changes
- Monitoring setup - One-command Uptime Kuma + rootless Docker installation
- Cloud-init automation - Auto-register servers on boot via webhooks
# One-line install (recommended)
curl -fsSL https://raw.githubusercontent.com/wnstify/rostr/main/install.sh | bashAlternative installation methods
# Install via pipx
pipx install git+https://github.com/wnstify/rostr.git
# Or clone and install manually
git clone https://github.com/wnstify/rostr.git ~/.rostr
cd ~/.rostr
python -m venv venv
source venv/bin/activate
pip install -e .# Initialize rostr
rostr init
# Add your first server
rostr add
# Generate configs
rostr sync
# Include in your SSH config
echo "Include ~/.rostr/generated/ssh_config" >> ~/.ssh/config# List servers
rostr list # All active servers
rostr list -g production # Filter by group
rostr list --tag webserver # Filter by tag
rostr list --all # Include inactive
rostr list -q # Hostnames only (for scripting)
# Server management
rostr add # Interactive add
rostr add --hostname web-01 --ip 10.0.1.10 -g production
rostr remove web-01 # Mark as inactive
rostr purge web-01 # Permanent delete
rostr move web-01 staging # Move to different group
# Information
rostr info web-01 # Server details
rostr search prod # Search by hostname/IP/notes
rostr groups # List all groups
rostr stats # Statistics
# Operations
rostr ssh web # SSH with fuzzy matching
rostr sync # Regenerate all configs
rostr validate # Check for issues
rostr backup # Create timestamped backup
# OS auditing
rostr audit-os # Compare inventory vs actual
rostr audit-os --fix # Auto-update inventory
# Dry run (preview changes)
rostr --dry-run add --hostname test --ip 10.0.0.1 -g staging
# Setup wizards (optional features)
rostr setup monitoring # Install Uptime Kuma + rootless Docker
rostr setup automation # Configure cloud-init registration~/.rostr/
├── config.yaml # Configuration
├── inventory/
│ ├── _defaults.yaml # Default values
│ └── groups/
│ ├── production.yaml # Production servers
│ ├── staging.yaml # Staging servers
│ └── ...
├── generated/ # Auto-generated (don't edit)
│ ├── ssh_config # SSH config
│ ├── ansible-inventory.yaml
│ └── hosts.txt
├── backups/ # Timestamped backups
└── logs/ # Operation logs
# inventory/groups/production.yaml
group:
name: Production
code: production
description: Production servers
servers:
- hostname: web-prod-01
ip: 10.0.1.10
os: ubuntu-24.04
tags:
- webserver
- docker
notes: Primary web server
created_at: '2026-01-01'
active: true# ~/.rostr/generated/ssh_config
Host web-prod-01
HostName 10.0.1.10
User admin
Groups are auto-generated by:
- Server group:
production,staging - Tag:
tag_webserver,tag_docker - OS:
os_ubuntu_24_04 - Notes:
notes_primary
ansible -i ~/.rostr/generated/ansible-inventory.yaml tag_webserver -m pingSee docs/CONFIGURATION.md for all options.
# config.yaml
defaults:
ssh_user: admin
ssh_port: 22
os: ubuntu-22.04
integrations:
uptime_kuma:
enabled: false
git_sync:
enabled: falseSecrets must be stored in environment variables:
# For Uptime Kuma integration
export ROSTR_UPTIMEKUMA_DB_PASS='your-password'
# For registration API
export ROSTR_REGISTRATION_TOKEN='your-token'During rostr init, you'll be prompted to set up optional features:
Install Uptime Kuma with rootless Docker for server monitoring:
rostr setup monitoring # Interactive installer
rostr setup monitoring-status # Check status
rostr setup monitoring-update # Update to latest
rostr setup monitoring-uninstall # Remove installationSee docs/UPTIME-KUMA.md for details.
Automatically register new servers when they boot:
rostr setup automation # Configure webhook + API
rostr setup automation-status # Check status
rostr setup automation-restart # Restart API serviceSee docs/CLOUD-INIT.md for details.
- Installation - Setup methods, dependencies, shell completions
- Configuration - All config options and environment variables
- Usage Reference - Complete command reference with examples
- Security - Best practices, secrets management, audit checklist
- Uptime Kuma Integration - Server monitoring setup
- Cloud-Init Automation - Auto-registration on boot
- Rootless Docker - Secure Docker setup
- Python 3.12+
- Linux or macOS (Unix-only)
Simon - Infrastructure engineer and automation enthusiast.
Webnestify s.r.o. is a Slovakia-based company providing dedicated hosting, security, performance optimization, and managed services.
"Access best-in-class dedicated hosting, security, performance, support, and more - all in one nest."
rostr is part of a larger ecosystem of server management and automation tools:
| Project | Description |
|---|---|
| server-configs | Production-ready cloud-init templates and security hardening |
| backupd | Menu-driven backup solution for web apps and databases |
| docker | Docker project templates for open-source applications |
| tubeflow | Research-first YouTube content creation system |
See all public projects at github.com/wnstify.
Follow @webnestify for tutorials on self-hosting, server management, and automation.
MIT License - see LICENSE
Issues and discussions are welcome. Pull requests are not accepted at this time - this is a personal project that I maintain for my own infrastructure needs.