HomeOps

HomeOps is a safe, extensible command-line tool for checking, backing up, and maintaining self-hosted infrastructure.

It is designed for self-hosters running infrastructure across one or more sites and aims to provide a consistent CLI for inspecting systems such as:

• Linux hosts
• Docker
• Proxmox
• WireGuard
• Home Assistant
• OpenWrt
• Restic-backed backups

HomeOps is designed around a simple rule:

Inspection should be safe by default. Changes should always be explicit.

Status

HomeOps is currently in early development.

The initial implementation focuses on read-only infrastructure checks before backup, restore, cleanup, or maintenance operations are introduced.

Expect interfaces and configuration formats to change before the first stable release.

Goals

HomeOps aims to provide:

• a generic multi-site inventory;
• read-only infrastructure health checks;
• consistent checks across different technologies;
• backup-status verification;
• backup orchestration using existing native tools;
• restore verification;
• human-readable CLI output;
• structured JSON output;
• explicit operation risk classification;
• mandatory confirmation for state-changing and destructive actions;
• interactive handling of passwords and other credentials;
• extensible technology providers.

Non-goals

HomeOps is not intended to become:

• a monitoring server;
• an Ansible replacement;
• a configuration-management system;
• a secrets manager;
• a backup format;
• a container orchestrator;
• a CMDB;
• a web dashboard.

Where mature tools already exist, HomeOps should orchestrate or inspect them instead of reimplementing them.

Safety Model

HomeOps distinguishes operations by risk:

READ_ONLY
SAFE_WRITE
DESTRUCTIVE
HIGH_RISK

Read-only commands must never modify infrastructure.

Examples:

homeops list
homeops check all
homeops check docker
homeops check wireguard
homeops check proxmox
homeops check backup
homeops report

State-changing actions are separate commands.

Potentially destructive actions require explicit interactive approval.

High-risk operations require stronger typed confirmation.

HomeOps does not initially provide destructive confirmation bypasses such as:

--yes
--force
--assume-yes

Credentials

Passwords and equivalent secrets must not be stored in HomeOps configuration.

HomeOps must not accept passwords through command-line arguments.

When a password is required, it is requested interactively using hidden terminal input.

HomeOps prefers existing authentication mechanisms such as:

• OpenSSH configuration;
• SSH agents;
• SSH keys;
• native authentication mechanisms provided by supported tools.

Secrets must never appear in:

• logs;
• JSON output;
• normal terminal output;
• inventory files;
• command history;
• exception messages.

Inventory

Infrastructure is defined using an inventory file.

Example:

[sites.home]
description = "Primary site"

[sites.remote]
description = "Remote site"

[hosts.router]
site = "home"
address = "router.example.internal"
ssh_user = "root"
roles = ["openwrt", "wireguard"]

[hosts.pve1]
site = "home"
address = "pve1.example.internal"
ssh_user = "ops"
roles = ["proxmox"]

[hosts.docker1]
site = "home"
address = "docker1.example.internal"
ssh_user = "ops"
roles = ["docker"]

Inventory files contain infrastructure descriptions, not secrets.

A real local inventory should normally remain untracked by Git.

Planned CLI

The initial CLI is expected to follow this structure:

homeops
├── list
├── check
│   ├── all
│   ├── network
│   ├── wireguard
│   ├── proxmox
│   ├── docker
│   ├── homeassistant
│   ├── storage
│   └── backup
├── backup
│   ├── config
│   ├── docker
│   ├── proxmox
│   └── homeassistant
├── restore-check
└── report

Example future usage:

homeops check all
homeops check docker
homeops check wireguard --site home
homeops check proxmox --host pve1

homeops report --json

Architecture

Technology-specific integrations are implemented as providers.

Planned initial providers include:

• generic Linux
• network
• WireGuard
• Docker
• Proxmox
• Home Assistant
• OpenWrt
• Restic

The HomeOps core owns:

• CLI behavior;
• inventory;
• credentials;
• safety enforcement;
• confirmation;
• logging;
• structured results;
• output rendering.

Providers own technology-specific inspection and operations.

See ARCHITECTURE.md for the detailed design.

Backlog

Development work is tracked in BACKLOG.md.

The initial priority is the read-only inspection foundation:

homeops list
homeops check network
homeops check wireguard
homeops check proxmox
homeops check docker
homeops check all
homeops check backup
homeops report
homeops report --json

Backup execution and destructive maintenance operations come later.

Engineering Principles

Development rules and safety constraints are documented in ENGINEERING_PRINCIPLES.md.

Important rules include:

• checks never mutate infrastructure;
• state-changing actions are explicit;
• destructive actions require confirmation;
• passwords are requested interactively;
• secrets are never persisted;
• operations fail safely;
• native infrastructure tools are preferred;
• provider code cannot bypass core safety controls.

Development

The project targets modern Python and should prefer the Python standard library where practical.

Planned repository structure:

homeops/
├── pyproject.toml
├── README.md
├── LICENSE
├── SECURITY.md
├── ARCHITECTURE.md
├── BACKLOG.md
├── ENGINEERING_PRINCIPLES.md
├── src/
│   └── homeops/
├── examples/
└── tests/

External dependencies should only be introduced when they provide substantial value.

Contributing

HomeOps is intended to become an extensible open-source project.

Contributions are welcome once the initial architecture and provider interfaces stabilize.

Before contributing, please:

1. read ARCHITECTURE.md;
2. read ENGINEERING_PRINCIPLES.md;
3. follow the safety model;
4. include tests for new behavior;
5. never introduce secrets into examples or tests.

Any feature capable of modifying infrastructure requires particular attention to failure modes and confirmation behavior.

Security

Security issues should not be reported through public issue trackers.

See SECURITY.md.

License

HomeOps is licensed under the Apache License, Version 2.0.

See LICENSE.