meshclaw 1.2.30

AI-native server operations control plane for vssh-backed infrastructure

MeshClaw

MeshClaw is an infrastructure capability control plane for AI operators.

MeshClaw is not a chat assistant and must not become one. Users talk to Codex, Claude, ChatGPT, Open WebUI/local models, or another operator. MeshClaw only provides truthful infrastructure state, available capabilities, policy decisions, safe actions, diagnostics, provisioning hooks, and evidence.

The survival direction is fixed in docs/SURVIVAL_DIRECTION.md: MeshClaw is the AI-native server operations control plane for mixed private infrastructure. It survives by being the shared operational truth layer for Codex, Claude, local models, Matrix, and human operators.

User
  -> Codex mobile / Claude
  -> MeshClaw MCP / CLI
  -> inventory + capability vault + policy + capacity + doctor + runbooks + audit
  -> vssh-native over Tailscale / provider APIs / monitor agents
  -> servers / models / APIs / temporary capacity

Scope

MeshClaw owns:

• server inventory
• model and API capability registry
• workspace registry: which model/human is working on which server/folder
• capacity and budget facts
• fleet status
• policy answers
• safe remote execution
• server operations agent workflows
• log analysis
• security checks
• provision/bootstrap/deprovision hooks
• diagnostics and repair plans
• service/log/deploy runbooks
• audit and evidence
• CLI, dashboard, and MCP surfaces
• AI-operator friendly outputs for Codex and Claude

MeshClaw does not own:

• general chat
• assistant personality
• Matrix-first personal assistant behavior
• Siri or Shortcuts automation
• mail, calendar, browser, or lifestyle assistant tools
• multi-agent roleplay or broad coworker orchestration
• coding-agent replacement workflows

First Commands

Install the Python entrypoint package:

pip install meshclaw

The PyPI package provides the meshclaw command wrapper. The Go binary remains the server-operations runtime and can be built locally:

go build -o /Users/dragon/bin/meshclaw ./cmd/meshclaw
go run ./cmd/meshclaw direction
go run ./cmd/meshclaw list
go run ./cmd/meshclaw capabilities
go run ./cmd/meshclaw status
go run ./cmd/meshclaw monitor-check
go run ./cmd/meshclaw ops-control
go run ./cmd/meshclaw ops-control --apply-safe
go run ./cmd/meshclaw monitor-agent 5m
go run ./cmd/meshclaw monitor-agent 10m --hygiene
go run ./cmd/meshclaw fleet-scan --hosts d1,v1 --security --hygiene --logs --json
go run ./cmd/meshclaw autoheal-plan
go run ./cmd/meshclaw autoheal-apply-safe
go run ./cmd/meshclaw disk-investigate d1 /home/dell
go run ./cmd/meshclaw data-clean-plan d1 /home/dell/kobolt
go run ./cmd/meshclaw data-clean-apply d1 /tmp/meshclaw-data-clean-plan-d1-...
go run ./cmd/meshclaw policy-check codex read_state server
go run ./cmd/meshclaw policy-show
go run ./cmd/meshclaw policy-init --preset devops
go run ./cmd/meshclaw policy-presets
go run ./cmd/meshclaw matrix-plan
go run ./cmd/meshclaw workers
go run ./cmd/meshclaw workspace-list
go run ./cmd/meshclaw workspace-add meshclaw-local local /Users/dragon/meshclaw codex serverops
go run ./cmd/meshclaw workspace-activity meshclaw-local codex edit "added workspace registry"
go run ./cmd/meshclaw ops-chat
go run ./cmd/meshclaw ops-dispatch matrix "!workers"
go run ./cmd/meshclaw ops-dispatch openwebui "workspaces"
go run ./cmd/meshclaw evidence-list 10
go run ./cmd/meshclaw run d1 'hostname && uptime'
go run ./cmd/meshclaw doctor d1
go run ./cmd/meshclaw analyze-logs d1 syslog
go run ./cmd/meshclaw service-check v3 server-agent.service
go run ./cmd/meshclaw service-remove v3 walknews.service /root/walknews
go run ./cmd/meshclaw security-check d1
go run ./cmd/meshclaw hygiene-plan d1
go run ./cmd/meshclaw hygiene-scan-host d1
go run ./cmd/meshclaw provision-plan batch-log-analysis 10
go run ./cmd/meshclaw mcp

The execution path is vssh-native first over Tailscale/private network. SSH is only a fallback for nodes that do not have vssh server running yet. Wire remains legacy compatibility.

Default remote execution requires:

Tailscale/private route + vssh server + VSSH_SECRET

Fallback execution still needs Tailscale + sshd + SSH key/user mapping.

Product Claim

Kubernetes is for orchestrating containerized workloads. MeshClaw is for operating the servers that already exist: VPS nodes, home servers, GPU boxes, NAS devices, Docker hosts, mail servers, and small private infrastructure. When existing capacity is not enough, MeshClaw exposes approved provisioning hooks so an AI operator can plan, rent, bootstrap, attach, use, and tear down temporary servers under policy.

Agent Workflows

MeshClaw should expose repeatable infrastructure workflows as MCP tools and CLI commands. These workflows return structured findings, risk levels, evidence, and recommended next actions. Codex, Claude, or a local model explains and coordinates the plan; MeshClaw supplies the operational truth.

Initial workflows:

• doctor: diagnose reachability, services, capacity, and runtime health
• monitor-check: check the whole fleet and store evidence
• ops-control: summarize fleet health, service risks, auto-safe candidates, next commands, and evidence in one server-management control report
• monitor-agent: continuously collect fleet state and alert evidence; with --hygiene, it also stores redacted sensitive-data leak findings
• fleet-scan: run monitor, security, logs, and redacted hygiene checks across selected hosts and store one evidence bundle for AI review
• autoheal-plan: convert fleet alerts into read-only or auto-safe actions
• autoheal-apply-safe: execute bounded non-destructive cleanup actions
• disk-investigate: collect disk evidence without deleting data
• data-clean-plan: find raw/intermediate/checkpoint cleanup candidates while preserving clean/final outputs
• data-clean-apply: apply a manifest generated by data-clean-plan
• analyze-logs: summarize recent logs, detect errors, and cite evidence
• service-check: collect read-only systemd status, unit config, and logs
• service-quarantine: disable a flapping service only when its ExecStart target is missing
• service-remove: stop/disable a local systemd service, remove its local unit, and optionally remove its matching working directory
• security-check: check SSH exposure, users, updates, firewall, open ports, failed logins, risky services, and secret handling
• hygiene-plan: continuously detect sensitive data leaks, log leaks, risky permissions, and safe remediation opportunities
• hygiene-scan-host: scan likely remote logs/config files for redacted secret and PII leak evidence without storing raw values
• capacity-plan: decide whether existing servers are enough
• provision-plan: propose temporary VPS/GPU capacity under budget policy

Policy is loaded from ~/.meshclaw/policy.json, or from MESHCLAW_POLICY_FILE when set. Configured rules are evaluated before the built-in safety defaults, so operators can grant or restrict Codex, Claude, local LLMs, and automations without changing code.

Natural-language conversation is owned by Codex, Claude, ChatGPT, Open WebUI, or another model frontend. MeshClaw makes that conversation operational by exposing MCP tools, policy decisions, vssh execution, and evidence.

Hygiene workflows are allowed to auto-apply only safe repairs such as permission hardening, redacted log copies, and quarantine. Destructive actions, secret rotation, database edits, service restarts, and provider revocation need approval.

Non-Conversation Rule

All natural-language planning belongs to Codex, Claude, ChatGPT, local LLMs, or another operator frontend. MeshClaw interfaces return structured facts and action results. Matrix is allowed as an operations room, notification channel, approval channel, and optional MCP command surface; it is not the assistant brain.

Real Matrix bridge commands:

meshclaw matrix-config-init --force
meshclaw matrix-post "MeshClaw Matrix bridge connected"
meshclaw matrix-sync-once
meshclaw matrix-bridge

Archived Previous Version

The previous broad personal-AI-runtime version was archived outside this repo:

/Users/dragon/meshclaw-archive-20260516-serverops-pivot

Current Handoff

See:

docs/HANDOFF_2026-05-16.md
docs/MCP_SETUP.md

MCP

Run:

meshclaw mcp

Initial tools:

• meshclaw.server_list
• meshclaw.workers
• meshclaw.workspace_list
• meshclaw.workspace_add
• meshclaw.workspace_activity
• meshclaw.capability_list
• meshclaw.monitor_check
• meshclaw.autoheal_plan
• meshclaw.autoheal_apply_safe
• meshclaw.evidence_list
• meshclaw.policy_check
• meshclaw.policy_show
• meshclaw.matrix_plan
• meshclaw.ops_dispatch
• meshclaw.provision_plan
• meshclaw.run_evidence
• meshclaw.disk_investigate
• meshclaw.data_clean_plan
• meshclaw.data_clean_apply
• meshclaw.service_check
• meshclaw.service_quarantine
• meshclaw.service_remove