Metadata-Version: 2.4
Name: meshclaw
Version: 1.2.1
Summary: AI-native server operations control plane for vssh-backed infrastructure
Project-URL: Homepage, https://github.com/meshclaw/meshclaw
Project-URL: Repository, https://github.com/meshclaw/meshclaw
Author: MeshPop
License: MIT
License-File: LICENSE
Keywords: ai-agents,mcp,meshclaw,server-ops,vssh
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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.

```text
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:

```sh
pip install meshclaw
```

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

```sh
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:

```text
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:

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

## Current Handoff

See:

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

## MCP

Run:

```sh
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`
