meshcentral-openclaw-bridge/PROJECT.md

Project goals and scope

Primary goal

Build a secure, documented, local MeshCentral ↔ OpenClaw bridge that lets Rob ask OpenClaw for MeshCentral-backed system inventory and diagnostics, with confirmation-gated remote actions.

Goals

Goal 1 — Establish a reliable read-only foundation

• Identify the supported MeshCentral integration surface (API, server-side module, MCP adapter, or another maintained approach).
• Authenticate using a dedicated least-privilege integration identity.
• List device groups and managed devices.
• Retrieve online/offline state and safe metadata.
• Provide clear, structured results to OpenClaw.
• Add health checks, timeouts, logging, and failure handling.

Success condition: OpenClaw can answer questions such as “Which managed systems are offline?” and “Show the OS, uptime, and agent status for this host” without changing anything.

Goal 2 — Add safe diagnostics

• Define an allowlisted set of diagnostic checks.
• Support targeted checks for disk space, services, processes, OS details, network state, and relevant logs.
• Restrict execution by device/group allowlist and command policy.
• Return command output with device, timestamp, exit status, and truncation metadata.

Success condition: Rob can request a diagnostic investigation on one selected system and receive reproducible, auditable results.

Goal 3 — Add confirmation-gated remediation

• Separate read-only, reversible, and destructive capabilities.
• Require explicit confirmation immediately before every state-changing action.
• Start with narrowly scoped reversible actions such as restarting an approved service.
• Keep reboot, shutdown, file deletion, software removal, security-control changes, and fleet-wide actions disabled by default.

Success condition: A requested change cannot occur from an ambiguous instruction, and every change is logged with target, action, requester, confirmation, result, and timestamp.

Goal 4 — Make the integration operable and maintainable

• Document deployment, upgrades, rollback, secret handling, and incident response.
• Add automated tests and a non-production test target.
• Define backup and recovery expectations for bridge configuration.
• Record architectural decisions and known limitations.

Success condition: The bridge can be upgraded or removed without losing MeshCentral availability or creating unmanaged access.

Scope boundaries

In scope

• MeshCentral running in Rob’s Proxmox cluster
• A bridge deployed inside the trusted homelab network
• OpenClaw tool/MCP integration
• Device inventory, status, diagnostics, and selected confirmed actions
• Documentation, testing, auditability, and rollback

Out of scope initially

• Publicly exposing the bridge
• Unrestricted arbitrary shell access
• Autonomous remediation or scheduled fleet changes
• Production Proxmox administration through MeshCentral
• Credential rotation or security-policy changes
• Integrating every possible MeshCentral feature before the read-only path is proven

Proposed delivery phases

1. Discovery: confirm MeshCentral version, deployment topology, authentication options, API capabilities, and safe test devices.
2. Design: choose bridge protocol and deployment location; define trust boundaries and tool contracts.
3. Read-only MVP: inventory and status tools, structured responses, logging, tests.
4. Diagnostics: allowlisted checks against a non-production device first.
5. Controlled actions: confirmation gates and narrowly scoped reversible actions.
6. Hardening: failure testing, audit review, upgrade/rollback documentation, and operational handoff.

Each phase has a documented entry criterion, deliverables, verification, and exit criterion. No phase should silently expand into the next one.

Multi-agent workflow

1. Clawdia maintains the task list and assigns non-overlapping work.
2. Research and implementation may proceed in parallel only where implementation is based on explicit assumptions or mocks.
3. Implementation agents write code and local tests, but do not deploy or connect to live infrastructure.
4. Review/test agents work from the resulting files and challenge assumptions independently.
5. Clawdia reconciles findings, updates decisions and task status, and identifies blockers.
6. Rob is asked only for choices that require local facts, credentials, topology decisions, or approval for external/state-changing work.

First execution wave

• Research the available MeshCentral integration/API options and existing maintained adapters.
• Build a local, mock-backed read-only bridge scaffold with typed contracts and tests; do not assume live MeshCentral connectivity yet.
• After those outputs land, run an independent review/test pass before selecting the live-integration path.