control-os

Controlling the OS with os-control-mcp

The sanctioned "motor cortex" for the host: act through systemd / logind / journald / D-Bus, not raw PID hacks. Tools: os_diag, os_services, os_service, os_journal, os_resources, os_processes, os_power, os_notify, os_dbus, os_reload.

The loop: sense → act → confirm

1. Sense first. os_diag (health, privilege, what's available) → os_services (list/status), os_journal (logs), os_resources / os_processes (pressure). Understand the state before changing it.
2. Act through the sanctioned tool. os_service (start/stop/restart/enable/…), os_power (suspend/reboot/poweroff), os_dbus (call a method), os_notify (tell the human).
3. Confirm. Re-run os_services unit=… / os_journal unit=… to verify the new state — don't assume the action took.

The two guards (and how to pass them)

• Self-preservation guard. A severing action (stop/restart/disable/mask/kill) on a unit the agent depends on — dbus, systemd-logind, sshd, NetworkManager/networkd, tailscaled, the user@… session, goosed, etc. — is REFUSED. This stops you cutting off your own bus / login / network / remote access. If you genuinely mean it, pass force=true. (start/enable/reload are never blocked.)
• Power confirm. os_power is irreversible/disruptive → refused unless confirm=true. State what you're about to do, then call with confirm=true.
• D-Bus call. os_dbus op=call has side effects → needs force=true. list/tree/introspect are free.

Privilege

Read-only tools work unprivileged. System-scope mutations (os_service on system units, os_power) need root or polkit — when not root the server tries sudo -n; if that's not set up it tells you plainly. Options: run goosed/the server as root, add passwordless sudo for systemctl, or a polkit rule. scope="user" manages the user's own units with no root.

Patterns

• Diagnose a crash: os_services unit=foo.service (state/last result) → os_journal unit=foo.service priority=err lines=80 → fix → os_service unit=foo.service action=restart → confirm.
• Find the hog: os_resources → os_processes by=cpu (or by=mem) → act.
• Health sweep: os_services state=failed to list everything broken at once.
• Reach the human: os_notify summary="build done" urgency=normal.

Pairs with screen-mcp (GUI eyes+hands), NATS (messaging), and A2A (inter-agent) for a full-stack agent: sense the kernel/services, act on the system, drive the desktop, coordinate the fleet.