container-host-aiops 0.1.0__tar.gz

container_host_aiops-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+# Trusted Publishing (OIDC) — publishes from GitHub's runners with no API token,
+# sidestepping the local-IP / account new-project rate limit. Configure a matching
+# "trusted publisher" for this package on PyPI (see the repo release notes).
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

container_host_aiops-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+*.egg-info/

container_host_aiops-0.1.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to container-host-aiops are documented here. This project adheres
+to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — preview
+
+Initial preview release: governed AI-ops for **non-orchestrator container hosts**
+across the **Docker Engine API** (unix socket or TCP) and **Portainer** (its
+management API, which also proxies Docker), with a bundled governance harness. One
+config can span many hosts; a per-target `platform` field selects the API shape.
+**Mock-validated only — not yet verified against a live Docker daemon or Portainer
+server.**
+
+### Added
+
+- **34 MCP tools** (26 read, 8 write), every one wrapped with the bundled
+  `@governed_tool` harness (audit, policy, token/runaway budget, undo,
+  risk-tiers):
+  - **Overview** — `overview` (one-shot host health: version + container state
+    rollup + disk headline).
+  - **Containers (read)** — `list_containers`, `inspect_container`,
+    `container_logs` (tail N), `container_stats` (CPU%/mem%), `container_top`,
+    `container_restart_summary`.
+  - **Images (read)** — `list_images`, `inspect_image` (with history/layers),
+    `dangling_images`, `image_disk_usage`.
+  - **Volumes (read)** — `list_volumes`, `inspect_volume`, `dangling_volumes`.
+  - **Networks (read)** — `list_networks`, `inspect_network`.
+  - **System (read)** — `system_info`, `system_version`, `system_df`,
+    `system_events`.
+  - **Stacks (Portainer, read)** — `list_endpoints`, `list_stacks`,
+    `stack_detail`.
+  - **Flagship analyses (read)** — `restart_loop_rca` (crash-looping containers +
+    cause/action from exit code + log tail), `resource_pressure_analysis`
+    (CPU/memory vs limits + recommendation), `image_and_volume_bloat` (dangling
+    images + volumes + build cache → prune candidates with reclaimable bytes).
+  - **Writes** — `restart_container` (med), `stop_container` (med, undo→start),
+    `start_container` (med, undo→stop), `update_container` (med, undo restores
+    prior CPU/memory limits), `remove_container` (**high**, captures full inspect
+    first), `prune_images` (**high**, dry-run lists candidates), `prune_volumes`
+    (**high**, dry-run lists candidates), `recreate_stack` (**high**, Portainer).
+- **Connection layer** — Docker over a unix socket (`httpx.HTTPTransport(uds=...)`)
+  or a TCP host; Portainer over HTTPS with an `X-API-Key` token that also proxies
+  the Docker API of a managed endpoint (`/api/endpoints/{id}/docker/...`).
+- **Encrypted secret store** — the Portainer API token is stored encrypted in
+  `~/.container-host-aiops/secrets.enc` (Fernet + scrypt); never plaintext on disk.
+  A direct Docker socket needs no secret. Legacy `CONTAINER_HOST_<TARGET>_TOKEN`
+  env var honoured as a fallback.
+- **CLI** (`container-host-aiops`) — `init` platform-picking wizard, `overview`,
+  `container`, `image`, `volume`, `network`, `system`, `stack`, `analyze`,
+  `manage` (guarded writes with `--dry-run` + double-confirm), `secret`
+  management, and a platform-aware `doctor`.
+
+### Known limitations
+
+- Preview / mock-only: the Docker Engine + Portainer API responses are mocked and
+  need live verification against a real daemon / server. `container-host-aiops
+  doctor` is the fastest live check.
+- Single-host focus by design: cluster orchestrators, hypervisors, storage
+  appliances, and backup products are out of scope (separate AIops-tools).

container_host_aiops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei <zhouwei008@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

container_host_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: container-host-aiops
+Version: 0.1.0
+Summary: Governed AI-ops for Docker + Portainer container hosts: container/image/volume/network/system reads, restart-loop and resource-pressure and bloat analyses, and guarded lifecycle + prune writes with a built-in governance harness (audit, budget, undo, risk tiers)
+Author-email: wei <zhouwei008@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp[cli]<2.0,>=1.10
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<16.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.AIops-tools/container-host-aiops -->
+
+# Container Host AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Docker, Inc., Portainer.io, or any container-platform vendor.** "Docker", "Portainer" and all product/trademark names belong to their respective owners. MIT licensed.
+
+Governed AI-ops for **non-orchestrator container hosts** — the **Docker Engine API** (over a local unix socket or a TCP host) and **Portainer** (its management API, which also proxies Docker) — with a **built-in governance harness**: unified audit log, policy engine, token/runaway budget guard, undo-token recording, and graduated-autonomy risk tiers. **Multi-platform by construction**: a registry keyed by `platform` means a per-target `platform` field (`docker` / `portainer`) selects the API shape, and another host family could be added later without touching the ops/CLI/MCP layers. **Preview — mock-validated only, not verified against a live Docker daemon or Portainer server.**
+
+## What it does
+
+Three flagship signature analyses, plus the guarded reads and writes around them:
+
+- **Restart-loop RCA** — inspect containers for restart count + exit code, flag the crash-looping ones (restartCount over threshold, or restarting/dead, or a non-zero exit), and map each to a likely cause + action from the exit code (137 OOM/SIGKILL, 143 SIGTERM, 139 segfault, 127 bad entrypoint, …), with a tail of logs. Every ranking carries its numbers, not a black-box verdict.
+- **Resource-pressure analysis** — a one-shot CPU%/memory% sample per running container vs its configured limits, flagging each "near" (≥ 80% of a threshold) or "over", with a recommendation (raise a limit, set a missing memory limit, scale out).
+- **Image & volume bloat** — dangling images + dangling volumes + build cache from `system/df`, totalled into prune candidates with reclaimable bytes.
+
+## What works
+
+- **CLI** (`container-host-aiops ...`): `init`, `overview`, `container`, `image`, `volume`, `network`, `system`, `stack`, `analyze`, `manage`, `secret`, `doctor`, `mcp`.
+- **MCP server** (`container-host-aiops mcp` or `container-host-aiops-mcp`): **34 tools** (26 read, 8 write), every one wrapped with the bundled `@governed_tool` harness.
+- **Connection layer**: Docker over a **unix socket** (`httpx.HTTPTransport(uds=...)`) or a TCP host; Portainer over HTTPS with an `X-API-Key` token that also proxies the Docker API of a managed endpoint. A local Docker socket needs **no secret** — the socket's file permissions are the boundary.
+- **Encrypted credentials**: the Portainer API token lives in an encrypted store `~/.container-host-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on disk**. Unlock with a master password from `CONTAINER_HOST_AIOPS_MASTER_PASSWORD` (MCP/CI) or an interactive prompt (CLI).
+- **Reversibility**: mutating writes fetch the **real before-state first** and record a faithful inverse (`stop`↔`start`; `update_container` restores prior CPU/memory limits). Irreversible ops (`remove_container`, `prune_images`, `prune_volumes`, `recreate_stack`) capture the before-state for audit but declare no undo.
+- **Safety**: every state-changing CLI op supports `--dry-run` and requires double confirmation; every write MCP tool takes a `dry_run` preview — and prune previews **list what would be removed + reclaimable bytes** before doing it.
+
+## Capability matrix (34 MCP tools)
+
+| Domain | Tools | Count | R/W |
+|--------|-------|:-----:|:---:|
+| **Overview** | `overview` | 1 | read |
+| **Containers** | `list_containers`, `inspect_container`, `container_logs`, `container_stats`, `container_top`, `container_restart_summary` | 6 | read |
+| **Images** | `list_images`, `inspect_image`, `dangling_images`, `image_disk_usage` | 4 | read |
+| **Volumes** | `list_volumes`, `inspect_volume`, `dangling_volumes` | 3 | read |
+| **Networks** | `list_networks`, `inspect_network` | 2 | read |
+| **System** | `system_info`, `system_version`, `system_df`, `system_events` | 4 | read |
+| **Stacks (Portainer)** | `list_endpoints`, `list_stacks`, `stack_detail` | 3 | read |
+| **Analyses (flagship)** | `restart_loop_rca`, `resource_pressure_analysis`, `image_and_volume_bloat` | 3 | read |
+| **Writes** | `remove_container`, `prune_images`, `prune_volumes`, `recreate_stack` | 4 | write (high) |
+| | `restart_container`, `stop_container`, `start_container`, `update_container` | 4 | write (medium) |
+
+The three analyses accept injected data for offline analysis, or pull live from a configured target. Stacks/endpoints require a `portainer` target.
+
+## Quick start
+
+```bash
+uv tool install container-host-aiops          # or: pipx install container-host-aiops
+container-host-aiops init                      # wizard: add a Docker socket or Portainer target
+container-host-aiops doctor                    # verify config, secrets, connectivity
+container-host-aiops overview                  # one-shot host health
+container-host-aiops analyze restart-loop      # crash-looping containers + cause/action
+container-host-aiops container list --running  # running containers
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export CONTAINER_HOST_AIOPS_MASTER_PASSWORD=...   # only needed for Portainer targets
+container-host-aiops-mcp
+```
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier, approver, rationale) is logged to `~/.container-host-aiops/audit.db` (relocatable via `CONTAINER_HOST_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
+- **Risk tiers** — graduated autonomy; high-risk ops (remove / prune / recreate) can require a named approver.
+- **Undo recording** — reversible writes record an inverse descriptor built from the fetched before-state.
+
+## Scope
+
+This is the **container-host** member of the AIops-tools family (governed AI-ops with audit + budget + undo + risk tiers), for **single-host Docker / Portainer**. It is deliberately **NOT** for a cluster orchestrator, a hypervisor, a storage appliance, a backup product, or OT / industrial edge — those are separate tools/lines.
+
+## Missing a capability?
+
+Coverage is intentionally a curated subset of the Docker Engine + Portainer APIs. Missing a call, or want another container host family? **Open an issue or PR** — contributions welcome.
+
+## Status
+
+**Preview — mock-validated only, not verified against a live Docker daemon or Portainer server.** The API paths are modelled from the public API shape and need live verification. `container-host-aiops doctor` is the fastest live check.

container_host_aiops-0.1.0/README.md

@@ -0,0 +1,80 @@
+<!-- mcp-name: io.github.AIops-tools/container-host-aiops -->
+
+# Container Host AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Docker, Inc., Portainer.io, or any container-platform vendor.** "Docker", "Portainer" and all product/trademark names belong to their respective owners. MIT licensed.
+
+Governed AI-ops for **non-orchestrator container hosts** — the **Docker Engine API** (over a local unix socket or a TCP host) and **Portainer** (its management API, which also proxies Docker) — with a **built-in governance harness**: unified audit log, policy engine, token/runaway budget guard, undo-token recording, and graduated-autonomy risk tiers. **Multi-platform by construction**: a registry keyed by `platform` means a per-target `platform` field (`docker` / `portainer`) selects the API shape, and another host family could be added later without touching the ops/CLI/MCP layers. **Preview — mock-validated only, not verified against a live Docker daemon or Portainer server.**
+
+## What it does
+
+Three flagship signature analyses, plus the guarded reads and writes around them:
+
+- **Restart-loop RCA** — inspect containers for restart count + exit code, flag the crash-looping ones (restartCount over threshold, or restarting/dead, or a non-zero exit), and map each to a likely cause + action from the exit code (137 OOM/SIGKILL, 143 SIGTERM, 139 segfault, 127 bad entrypoint, …), with a tail of logs. Every ranking carries its numbers, not a black-box verdict.
+- **Resource-pressure analysis** — a one-shot CPU%/memory% sample per running container vs its configured limits, flagging each "near" (≥ 80% of a threshold) or "over", with a recommendation (raise a limit, set a missing memory limit, scale out).
+- **Image & volume bloat** — dangling images + dangling volumes + build cache from `system/df`, totalled into prune candidates with reclaimable bytes.
+
+## What works
+
+- **CLI** (`container-host-aiops ...`): `init`, `overview`, `container`, `image`, `volume`, `network`, `system`, `stack`, `analyze`, `manage`, `secret`, `doctor`, `mcp`.
+- **MCP server** (`container-host-aiops mcp` or `container-host-aiops-mcp`): **34 tools** (26 read, 8 write), every one wrapped with the bundled `@governed_tool` harness.
+- **Connection layer**: Docker over a **unix socket** (`httpx.HTTPTransport(uds=...)`) or a TCP host; Portainer over HTTPS with an `X-API-Key` token that also proxies the Docker API of a managed endpoint. A local Docker socket needs **no secret** — the socket's file permissions are the boundary.
+- **Encrypted credentials**: the Portainer API token lives in an encrypted store `~/.container-host-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on disk**. Unlock with a master password from `CONTAINER_HOST_AIOPS_MASTER_PASSWORD` (MCP/CI) or an interactive prompt (CLI).
+- **Reversibility**: mutating writes fetch the **real before-state first** and record a faithful inverse (`stop`↔`start`; `update_container` restores prior CPU/memory limits). Irreversible ops (`remove_container`, `prune_images`, `prune_volumes`, `recreate_stack`) capture the before-state for audit but declare no undo.
+- **Safety**: every state-changing CLI op supports `--dry-run` and requires double confirmation; every write MCP tool takes a `dry_run` preview — and prune previews **list what would be removed + reclaimable bytes** before doing it.
+
+## Capability matrix (34 MCP tools)
+
+| Domain | Tools | Count | R/W |
+|--------|-------|:-----:|:---:|
+| **Overview** | `overview` | 1 | read |
+| **Containers** | `list_containers`, `inspect_container`, `container_logs`, `container_stats`, `container_top`, `container_restart_summary` | 6 | read |
+| **Images** | `list_images`, `inspect_image`, `dangling_images`, `image_disk_usage` | 4 | read |
+| **Volumes** | `list_volumes`, `inspect_volume`, `dangling_volumes` | 3 | read |
+| **Networks** | `list_networks`, `inspect_network` | 2 | read |
+| **System** | `system_info`, `system_version`, `system_df`, `system_events` | 4 | read |
+| **Stacks (Portainer)** | `list_endpoints`, `list_stacks`, `stack_detail` | 3 | read |
+| **Analyses (flagship)** | `restart_loop_rca`, `resource_pressure_analysis`, `image_and_volume_bloat` | 3 | read |
+| **Writes** | `remove_container`, `prune_images`, `prune_volumes`, `recreate_stack` | 4 | write (high) |
+| | `restart_container`, `stop_container`, `start_container`, `update_container` | 4 | write (medium) |
+
+The three analyses accept injected data for offline analysis, or pull live from a configured target. Stacks/endpoints require a `portainer` target.
+
+## Quick start
+
+```bash
+uv tool install container-host-aiops          # or: pipx install container-host-aiops
+container-host-aiops init                      # wizard: add a Docker socket or Portainer target
+container-host-aiops doctor                    # verify config, secrets, connectivity
+container-host-aiops overview                  # one-shot host health
+container-host-aiops analyze restart-loop      # crash-looping containers + cause/action
+container-host-aiops container list --running  # running containers
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export CONTAINER_HOST_AIOPS_MASTER_PASSWORD=...   # only needed for Portainer targets
+container-host-aiops-mcp
+```
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier, approver, rationale) is logged to `~/.container-host-aiops/audit.db` (relocatable via `CONTAINER_HOST_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
+- **Risk tiers** — graduated autonomy; high-risk ops (remove / prune / recreate) can require a named approver.
+- **Undo recording** — reversible writes record an inverse descriptor built from the fetched before-state.
+
+## Scope
+
+This is the **container-host** member of the AIops-tools family (governed AI-ops with audit + budget + undo + risk tiers), for **single-host Docker / Portainer**. It is deliberately **NOT** for a cluster orchestrator, a hypervisor, a storage appliance, a backup product, or OT / industrial edge — those are separate tools/lines.
+
+## Missing a capability?
+
+Coverage is intentionally a curated subset of the Docker Engine + Portainer APIs. Missing a call, or want another container host family? **Open an issue or PR** — contributions welcome.
+
+## Status
+
+**Preview — mock-validated only, not verified against a live Docker daemon or Portainer server.** The API paths are modelled from the public API shape and need live verification. `container-host-aiops doctor` is the fastest live check.

container_host_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,59 @@
+# Container Host AIops v0.1.0 — preview
+
+Governed AI-ops for **non-orchestrator container hosts** across the **Docker
+Engine API** (unix socket or TCP) and **Portainer** (its management API, which
+also proxies Docker) for AI agents, with a built-in governance harness (audit,
+policy, token/runaway budget, undo-token recording, graduated risk tiers) and an
+encrypted credential store. Standalone — no external skill-family dependency. One
+config can span many hosts; a per-target `platform` field selects the API shape.
+
+> **Preview / mock-only.** All behaviour is validated against mocked Docker /
+> Portainer responses; it has not been run against a live daemon or server. The
+> fastest live check is `container-host-aiops doctor`.
+
+## Highlights
+
+- **34 MCP tools** (26 read, 8 write), every one wrapped with `@governed_tool`.
+  - **Overview** — `overview` (host version + container state rollup + disk).
+  - **Containers** — `list_containers`, `inspect_container`, `container_logs`,
+    `container_stats`, `container_top`, `container_restart_summary`.
+  - **Images** — `list_images`, `inspect_image`, `dangling_images`,
+    `image_disk_usage`.
+  - **Volumes / Networks** — `list_volumes`, `inspect_volume`, `dangling_volumes`;
+    `list_networks`, `inspect_network`.
+  - **System** — `system_info`, `system_version`, `system_df`, `system_events`.
+  - **Stacks (Portainer)** — `list_endpoints`, `list_stacks`, `stack_detail`.
+  - **Writes** — `restart_container`, `stop_container`/`start_container`,
+    `update_container`, `remove_container`, `prune_images`/`prune_volumes`,
+    `recreate_stack`.
+- **Three flagship analyses** — `restart_loop_rca` (crash-looping containers +
+  cause/action from exit code + log tail), `resource_pressure_analysis` (CPU/memory
+  vs limits + recommendation), `image_and_volume_bloat` (prune candidates +
+  reclaimable bytes). Each accepts injected data for offline analysis or pulls live.
+- **Connection layer** — Docker over a unix socket (`httpx.HTTPTransport(uds=...)`)
+  or a TCP host; Portainer over HTTPS with an `X-API-Key` token that proxies the
+  Docker API of a managed endpoint. A local Docker socket needs no secret.
+- **Encrypted secret store** (`~/.container-host-aiops/secrets.enc`, Fernet + scrypt)
+  — the Portainer API token, never plaintext on disk; legacy
+  `CONTAINER_HOST_<TARGET>_TOKEN` env fallback.
+- **Guarded writes** — destructive ops (`remove_container`, `prune_images`,
+  `prune_volumes`, `recreate_stack`) require dry-run + double-confirm; prune
+  previews list what would be removed + reclaimable bytes first. Reversible writes
+  capture before-state and record an inverse undo descriptor.
+- **CLI** with an `init` platform-picking wizard, `secret` management, and a
+  platform-aware `doctor`.
+
+## Install
+
+```bash
+uv tool install container-host-aiops
+container-host-aiops init       # pick platform (docker/portainer) + connect
+container-host-aiops doctor
+```
+
+## Caveats
+
+- Preview / mock-only: the Docker Engine + Portainer API responses are mocked and
+  need live verification.
+- Single-host focus by design: cluster orchestrators, hypervisors, storage
+  appliances, and backup products are out of scope (separate AIops-tools).

container_host_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,83 @@
+# Security Policy
+
+## Disclaimer
+
+Community-maintained open-source project. **Not affiliated with, endorsed by, or
+sponsored by Docker, Inc. or Portainer.io.** Product and trademark names (Docker,
+Portainer) belong to their owners. Source is auditable under the MIT license.
+
+## Reporting Vulnerabilities
+
+Report privately via a GitHub Security Advisory on
+[github.com/AIops-tools/Container-Host-AIops](https://github.com/AIops-tools/Container-Host-AIops/security/advisories)
+or email zhouwei008@gmail.com. Please do not open public issues for security
+reports.
+
+## Security Design
+
+### Credential Management
+- The only secret is the **Portainer API token**. It lives **encrypted** in
+  `~/.container-host-aiops/secrets.enc` (Fernet/AES-128 + scrypt-derived key; chmod
+  600), never in `config.yaml` and never in source. The master password is never
+  stored — only a per-store random salt and the ciphertext are on disk.
+- A **direct Docker socket** target needs no secret at all — the unix socket's
+  file permissions are the trust boundary. Treat access to `/var/run/docker.sock`
+  as root-equivalent on the host and scope it accordingly.
+- A legacy plaintext env var `CONTAINER_HOST_<TARGET_NAME_UPPER>_TOKEN` is still
+  honoured as a fallback with a deprecation warning (migrate with
+  `container-host-aiops secret migrate`).
+- The token is held only in memory and never logged or echoed; it is sent in the
+  `X-API-Key` request header at call time. The config file holds only platform,
+  socket path / host, port, endpoint id, and TLS settings.
+
+### Governed Operations
+Every MCP tool runs through the bundled `@governed_tool` harness
+(`container_host_aiops.governance`):
+- **Audit** — every call logged to a local SQLite DB under `~/.container-host-aiops/`
+  (relocatable via `CONTAINER_HOST_AIOPS_HOME`), agent-attributed, secret-redacted.
+- **Token/runaway budget** — hard ceilings (`CONTAINER_HOST_MAX_TOOL_CALLS` /
+  `CONTAINER_HOST_MAX_TOOL_SECONDS` — the env-var names the bundled harness reads)
+  plus an on-by-default guard that trips a tight poll/retry loop, preventing
+  unbounded API consumption.
+- **Graduated risk tiers** — `~/.container-host-aiops/rules.yaml` `risk_tiers` gate
+  writes by environment/tag; the highest tiers require a recorded approver.
+- **Undo-token recording** — reversible writes capture the BEFORE state and
+  record an inverse descriptor (e.g. `stop_container`→`start_container`,
+  `update_container`→restore prior limits) so the change can be rolled back.
+
+### State-Changing Operations
+Destructive writes — `remove_container`, `prune_images`, `prune_volumes`,
+`recreate_stack` — are `risk_level=high`, accept a `dry_run` preview (prune
+previews **list what would be removed + reclaimable bytes** first), and (under
+`risk_tiers`) require a recorded approver (`CONTAINER_HOST_AUDIT_APPROVED_BY` +
+`CONTAINER_HOST_AUDIT_RATIONALE` — the env-var names the bundled harness reads).
+Lifecycle writes (`restart_container`, `stop_container`, `start_container`,
+`update_container`) are `risk_level=medium`; reversible ones capture before-state
+and record an undo token. `remove_container` captures the full inspect JSON
+before deletion for the audit trail.
+
+### SSL/TLS Verification
+`verify_ssl` defaults to true; disable only for a self-signed Portainer / TLS
+Docker daemon in a lab. A unix-socket Docker target does not use TLS.
+
+### Prompt-Injection Protection
+All host-returned text (container names, image tags, log lines, event text,
+volume/network names) is passed through a `sanitize()` truncate +
+control-character strip before reaching the agent, bounded in depth and length.
+
+### Network Scope
+No webhooks, no telemetry, no outbound calls beyond the configured Docker socket /
+TCP host or the Portainer API base URL. No post-install scripts or background
+services.
+
+## Static Analysis
+
+```bash
+uvx bandit -r container_host_aiops/ mcp_server/
+uv run ruff check .
+```
+
+## Supported Versions
+
+The latest released version receives security fixes. This is a preview (0.x);
+pin a version in production.

container_host_aiops-0.1.0/container_host_aiops/__init__.py

@@ -0,0 +1,9 @@
+"""container-host-aiops — governed Docker + Portainer container-host ops for AI agents.
+
+Standalone and self-contained: the governance harness (audit, token budget,
+undo-token recording, graduated risk tiers, prompt-injection sanitize) is
+bundled under ``container_host_aiops.governance`` — this package has no external
+skill-family dependency. Preview: not yet full-coverage, mock-validated only.
+"""
+
+__version__ = "0.1.0"

container_host_aiops-0.1.0/container_host_aiops/cli/__init__.py

@@ -0,0 +1,9 @@
+"""CLI package for container-host-aiops.
+
+Re-exports ``app`` so the pyproject entry point
+``container-host-aiops = "container_host_aiops.cli:app"`` works unchanged.
+"""
+
+from container_host_aiops.cli._root import app
+
+__all__ = ["app"]

container_host_aiops-0.1.0/container_host_aiops/cli/_common.py

@@ -0,0 +1,78 @@
+"""Shared helpers for container-host-aiops CLI sub-modules."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+# ─── Shared Option types ───────────────────────────────────────────────────
+
+TargetOption = Annotated[
+    str | None, typer.Option("--target", "-t", help="Target name from config")
+]
+DryRunOption = Annotated[
+    bool, typer.Option("--dry-run", help="Print the API call without executing")
+]
+
+
+def _cli_error_types() -> tuple[type[BaseException], ...]:
+    """Exceptions translated to a one-line teaching error instead of a traceback."""
+    from container_host_aiops.connection import ContainerHostApiError
+
+    return (ContainerHostApiError, KeyError, OSError, ValueError)
+
+
+def cli_errors(fn: Callable) -> Callable:
+    """Translate known exceptions into one red line + exit code 1."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except (typer.Exit, typer.Abort):
+            raise
+        except _cli_error_types() as e:
+            message = str(e)
+            if isinstance(e, KeyError):
+                message = f"Missing required key or environment variable: {message}"
+            console.print(f"[red]Error: {message}[/]")
+            raise typer.Exit(1) from e
+
+    return wrapper
+
+
+def get_connection(target: str | None, config_path: Path | None = None):
+    """Return a (conn, config) tuple for the given target."""
+    from container_host_aiops.config import load_config
+    from container_host_aiops.connection import ConnectionManager
+
+    cfg = load_config(config_path)
+    mgr = ConnectionManager(cfg)
+    return mgr.connect(target), cfg
+
+
+def dry_run_print(*, operation: str, api_call: str, parameters: dict | None = None) -> None:
+    """Print a dry-run preview of the API call that would be made."""
+    console.print("\n[bold magenta][DRY-RUN] No changes will be made.[/]")
+    console.print(f"[magenta]  Operation: {operation}[/]")
+    console.print(f"[magenta]  API Call:  {api_call}[/]")
+    for k, v in (parameters or {}).items():
+        console.print(f"[magenta]  Param:     {k} = {v}[/]")
+    console.print("[magenta]  Run without --dry-run to execute.[/]\n")
+
+
+def double_confirm(action: str, resource: str) -> None:
+    """Require two confirmations for a destructive operation."""
+    console.print(f"[bold yellow]⚠️  About to: {action} '{resource}'[/]")
+    typer.confirm(f"Confirm 1/2: {action} '{resource}'?", abort=True)
+    typer.confirm(
+        f"Confirm 2/2: really {action} '{resource}'? This may be irreversible.",
+        abort=True,
+    )

container_host_aiops-0.1.0/container_host_aiops/cli/_root.py

@@ -0,0 +1,70 @@
+"""Top-level Typer app: assembles sub-apps and top-level commands."""
+
+from __future__ import annotations
+
+import typer
+
+from container_host_aiops.cli._common import cli_errors
+from container_host_aiops.cli.analyze import analyze_app
+from container_host_aiops.cli.container import container_app
+from container_host_aiops.cli.doctor import doctor_cmd
+from container_host_aiops.cli.image import image_app
+from container_host_aiops.cli.init import init_cmd
+from container_host_aiops.cli.manage import manage_app
+from container_host_aiops.cli.network import network_app
+from container_host_aiops.cli.overview import overview_cmd
+from container_host_aiops.cli.secret import secret_app
+from container_host_aiops.cli.stack import stack_app
+from container_host_aiops.cli.system import system_app
+from container_host_aiops.cli.volume import volume_app
+
+app = typer.Typer(
+    name="container-host-aiops",
+    help="Governed AI-ops for Docker + Portainer container hosts: container / "
+    "image / volume / network / system reads, flagship analyses, and guarded "
+    "lifecycle + prune writes with a built-in governance harness.",
+    no_args_is_help=True,
+)
+
+app.add_typer(container_app, name="container")
+app.add_typer(image_app, name="image")
+app.add_typer(volume_app, name="volume")
+app.add_typer(network_app, name="network")
+app.add_typer(system_app, name="system")
+app.add_typer(stack_app, name="stack")
+app.add_typer(analyze_app, name="analyze")
+app.add_typer(manage_app, name="manage")
+app.add_typer(secret_app, name="secret")
+app.command("init")(init_cmd)
+app.command("overview")(overview_cmd)
+app.command("doctor")(doctor_cmd)
+
+
+@app.command("mcp")
+@cli_errors
+def mcp_cmd() -> None:
+    """Start the MCP server (stdio transport).
+
+    Single-command entry point for MCP clients (does not go through uvx/PyPI
+    resolution at launch):
+        container-host-aiops mcp
+    """
+    import sys
+
+    if sys.version_info < (3, 11):
+        typer.echo(
+            f"ERROR: container-host-aiops requires Python >= 3.11 "
+            f"(got {sys.version_info.major}.{sys.version_info.minor}).\n"
+            f"Fix: uv python install 3.12 && "
+            f"uv tool install --python 3.12 --force container-host-aiops",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    from mcp_server.server import main as _mcp_main
+
+    _mcp_main()
+
+
+if __name__ == "__main__":
+    app()