meshclaw 1.2.1

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.

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
• 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
• natural-language conversation
• 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 list
go run ./cmd/meshclaw capabilities
go run ./cmd/meshclaw status
go run ./cmd/meshclaw monitor-check
go run ./cmd/meshclaw monitor-agent 5m
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 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 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
• monitor-agent: continuously collect fleet state and alert evidence
• 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
• capacity-plan: decide whether existing servers are enough
• provision-plan: propose temporary VPS/GPU capacity under budget policy

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 conversation belongs to Codex, Claude, ChatGPT, or another operator. MeshClaw interfaces return structured facts and action results. If a Matrix adapter or web UI is added later, it is only a notification, approval, or shared operations channel; it is not the assistant brain.

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.capability_list
• meshclaw.monitor_check
• meshclaw.autoheal_plan
• meshclaw.autoheal_apply_safe
• meshclaw.evidence_list
• meshclaw.policy_check
• 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