rostr

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.

Features

• YAML-based inventory - Simple, readable, version-controllable
• SSH config generation - Auto-generate ~/.ssh/config entries
• Ansible inventory - Dynamic inventory with groups by tag, OS, and notes
• Fuzzy SSH matching - rostr ssh web matches web-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

Quick Start

# One-line install (recommended)
curl -fsSL https://raw.githubusercontent.com/wnstify/rostr/main/install.sh | bash

Alternative 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 configecho"Include ~/.rostr/generated/ssh_config">>~/.ssh/config

Usage

# 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

Directory Structure

~/.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 Format

# inventory/groups/production.yamlgroup:
name: Productioncode: productiondescription: Production serversservers:
- hostname: web-prod-01ip: 10.0.1.10os: ubuntu-24.04tags:
- webserver
- dockernotes: Primary web servercreated_at: '2026-01-01'active: true

Generated Files

SSH Config

# ~/.rostr/generated/ssh_config
Host web-prod-01
HostName 10.0.1.10
User admin

Ansible Inventory

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 ping

Configuration

See docs/CONFIGURATION.md for all options.

# config.yamldefaults:
ssh_user: adminssh_port: 22os: ubuntu-22.04integrations:
uptime_kuma:
enabled: falsegit_sync:
enabled: false

Environment Variables

Secrets must be stored in environment variables:

# For Uptime Kuma integrationexport ROSTR_UPTIMEKUMA_DB_PASS='your-password'# For registration APIexport ROSTR_REGISTRATION_TOKEN='your-token'

Optional Features

During rostr init, you'll be prompted to set up optional features:

Server Monitoring

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 installation

See docs/UPTIME-KUMA.md for details.

Cloud-Init Automation

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 service

See docs/CLOUD-INIT.md for details.

Documentation

• 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

Optional Features

• Uptime Kuma Integration - Server monitoring setup
• Cloud-Init Automation - Auto-registration on boot
• Rootless Docker - Secure Docker setup

Requirements

• Python 3.12+
• Linux or macOS (Unix-only)

About

Author

Simon - Infrastructure engineer and automation enthusiast.

Webnestify

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."

Related Projects

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.

YouTube

Follow @webnestify for tutorials on self-hosting, server management, and automation.

License

MIT License - see LICENSE

Contributing

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.