planeops 0.10.3

Install · Quickstart · What you can do · Docs · Spec

planeops is an inventory and drift detector for the AI tooling on your machine: coding assistants, MCP servers, local models, background services, API keys. You declare what should exist and why in plain YAML; planeops tells you when reality disagrees, and changes nothing without showing the diff and asking first.

$ plane status --short
drift:2

$ plane drift
✗ 2 alert(s) on mymac 16:20

alerts (2)
  ✗ launchd/ai.gateway  ungoverned always-on service; declare it or add an unmanaged glob
  ✗ ollama/qwen3:8b     expected present, not observed

  full report ~/planeops/observed/mymac/DRIFT.md

A machine with six things running that nobody wrote down, caught by one read-only scan.

Why

Your machine accretes AI tooling: coding harnesses, MCP servers wired into three different clients, local models, background services, API keys in dotfiles. Nobody writes down what is installed, how it is wired, or why it is there. Six months later, something is listening on a port and you cannot say what put it there.

planeops turns the pile into a registry: every asset declared with its reason for existing, every scan diffed against that intent, every fix a rendered change you confirm one at a time.

What you can do with it

The guarantees under all of it: observation never writes, there is no daemon and no open port, a registry typo fails at load instead of silently meaning nothing, exit codes are scriptable (0 clean, 1 operator error, 2 drift), and the engine names no vendor: adapters, schedulers, and secret stores are all discovery seams.

Install

$ uv tool install planeops        # or: pipx install planeops / pip install planeops

Installs the plane command. Python 3.12+, macOS and Linux.

Want your AI assistant to query the plane over MCP? Install the extra: uv tool install "planeops[mcp]" (adds plane-mcp).

$ git clone https://github.com/albertorsesc/planeops
$ cd planeops
$ uv sync            # engine + plane CLI
$ make check         # the full gate: lint, format, types, tests

Quickstart

# scaffold an instance and seed the registry from what's already installed
$ plane init --seed
create the instance at /Users/you/planeops? (path or Enter to accept)
instance ready at /Users/you/planeops
  wrote 73 entries to /Users/you/planeops/registry/imported.yaml; prune, then `plane drift`

# scan the machine, diff it against the registry
$ plane observe
✓ observed 73 facts on mymac /Users/you/planeops/observed/mymac/snapshot.json
  brew 21 · mcp 14 · ollama 9 · npm 8 · launchd 6 · ...
$ plane drift
✓ no drift on mymac 16:04

# keep it fresh: an OS timer, previewed and confirmed
$ plane schedule --every 6h

# one glance forever after (empty means clean; wire it into your prompt)
$ plane status --short
drift:3

From there, plane apply walks the drift one confirmed change at a time.

plane init created an instance: a directory that is yours, not the tool's. Git it like a dotfiles repo:

~/planeops/
├── registry/           desired state: the YAML you declare, edit, and prune
├── instance.yaml       this machine's adapter settings
├── secrets.sops.yaml   encrypted values, if you use the secrets store
└── observed/<host>/    generated per machine: snapshot.json, DRIFT.md

registry/ and instance.yaml are your setup's documentation; observed/ is regenerated by every scan. Layout, multi-machine use, and the tool's exact footprint: docs/instance.md.

Going further

• SPEC.md: the architecture, entry schema, adapter contracts, and exit codes.
• docs/instance.md: your instance directory, several machines on one registry, the tool's footprint.
• docs/secrets.md: the secrets flow (declare, secrets add/list/remove with the store bootstrapped on first use, apply materializes) and how values stay sealed.
• docs/mcp.md: every MCP server across every client in one view, the opt-in unwire of retired servers, and the read-only server your assistant can query.
• docs/footprint.md: discovering tools by the config traces they leave, and how debris and already-governed tools stay out of the way.
• CHANGELOG.md: releases and what is coming.

What planeops is not

• Not a runtime. It never sits in any request path and starts no long-running process.
• Not an installer. Adapters shell out to the tools you already trust (brew, systemctl, ollama); planeops decides whether, they do how.
• Not a fleet manager. One human, their machines, their intent. Multi-host is on the roadmap as bundles of the same registry, not an agent mesh.

Status

Pre-1.0: the loop, twelve adapters, scheduling, secrets, importers, and the MCP server work on macOS and Linux and govern this project's own machines daily. Contracts may still move; a breaking change bumps the minor and lands in the CHANGELOG with its migration.

Built on

planeops delegates instead of reinventing: sops and age hold the secrets, chezmoi reproduces config files, your OS's own scheduler runs the ambient loop, and the package managers you already use keep doing the installing. The engine rides on ruamel.yaml for the registry, Rich with rich-argparse for the console, and the MCP Python SDK for the optional server, and is built with uv, ruff, mypy, and pytest. Thanks to all of them.

Contributing, security, license

CONTRIBUTING.md has the dev setup, the quality gate, and how to write an adapter. Security posture and reporting: SECURITY.md. Licensed Apache-2.0.