Metadata-Version: 2.4
Name: meshclaw
Version: 1.2.28
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
- 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:

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

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

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

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