| --- |
| title: dockroot-mcp |
| emoji: 🐳 |
| colorFrom: indigo |
| colorTo: purple |
| sdk: static |
| pinned: false |
| license: apache-2.0 |
| short_description: Virtual docker root — read-only MCP tools for your stack |
| --- |
| |
| # 🐳 dockroot-mcp — Virtual Docker Root for AI Agents |
|
|
| **Give your AI agent read-only power over its own Docker stack — without |
| host root.** |
|
|
| `dockroot-mcp` is a standalone MCP server that exposes read-only Docker |
| tools (`ps`, `logs`, `inspect`, `stats`, `networks`) as first-class agent |
| tools. Drop the container into any compose stack, mount the socket, and |
| your agent can SEE and DIAGNOSE every container on its network — then |
| actually fix things, instead of guessing. |
|
|
| ## Why this exists |
|
|
| AI agents get asked "why is my Open WebUI broken?" constantly. Without |
| docker access they flail: they invent commands, read the wrong configs, |
| or hallucinate fixes. With `dockroot-mcp` the agent can: |
|
|
| 1. **List** the containers on its network (`docker_ps`) |
| 2. **Read logs** to find the real error (`docker_logs`) |
| 3. **Inspect** env / mounts / health (`docker_inspect`) |
| 4. **Watch** CPU/memory pressure (`docker_stats`) |
| 5. **See** the network topology (`docker_networks`) |
|
|
| Then it answers from evidence, not imagination. The Fixer sees the box. |
|
|
| ## The security model (read this) |
|
|
| - **Read-only by design** — the MCP tool list contains ONLY read commands. |
| No start/stop/rm/exec. The agent can diagnose, never destroy. |
| - **Scoped visibility** — mount the socket, and the tools see the whole |
| Docker daemon the socket belongs to. Keep it on an internal network. |
| - **Opt-in** — no socket mount, no docker access. The server still runs |
| (it just reports the docker error honestly). |
| - **Env filtering** — Hermes strips secrets from MCP subprocess env and |
| redacts credentials in tool errors. |
|
|
| This is *virtual* root: the power of sight without the power of control. |
|
|
| ## Quick start |
|
|
| ### 1. Add to your compose stack |
|
|
| ```yaml |
| services: |
| dockroot: |
| image: jpanasuk/dockroot-mcp:latest |
| container_name: dockroot |
| restart: unless-stopped |
| networks: [your-ai-network] # the network it can see |
| volumes: |
| - /var/run/docker.sock:/var/run/docker.sock # read-only docker access |
| ``` |
|
|
| ### 2. Connect from Hermes (native MCP client) |
|
|
| ```yaml |
| # ~/.hermes/config.yaml |
| mcp_servers: |
| dockroot: |
| command: python3 |
| args: ["/opt/dockroot/tavern_mcp.py"] |
| ``` |
|
|
| Then ask your agent: *"what containers are running?"* or *"why is |
| code-server crash-looping?"* — it calls `mcp_dockroot_docker_ps` / |
| `mcp_dockroot_docker_logs` and answers from the actual stack. |
|
|
| ### 3. Or expose through MCPO (Open WebUI ecosystem) |
|
|
| Add to your mcpo `config.json`: |
|
|
| ```json |
| { |
| "mcpServers": { |
| "dockroot": { |
| "command": "python3", |
| "args": ["/opt/dockroot/tavern_mcp.py"] |
| } |
| } |
| } |
| ``` |
|
|
| Every tool becomes an HTTP endpoint (`/dockroot/docker_ps`, ...) that any |
| OpenAI-compatible tool caller can hit. |
|
|
| ## Available tools |
|
|
| | Tool | What it does | When to use | |
| |------|-------------|-------------| |
| | `docker_ps` | List containers (names, images, status, ports) | "what's running?" | |
| | `docker_logs` | Tail a container's logs | "why is X failing?" | |
| | `docker_inspect` | Full config: env, mounts, network, health | "what env does X have?" | |
| | `docker_stats` | Live CPU/memory usage | "is the box overloaded?" | |
| | `docker_networks` | List Docker networks | "what networks exist?" | |
| | `status` | Discovered services with link:port | "what's connected?" | |
| | `self_check` | Verify every service's health (HTTP+TCP) | "is everything working?" | |
| | `wire` | Wiring audit with exact fixes | "connect X to Y" | |
| | `rediscover` | Re-scan the network | "find new services" | |
| | `models` | List available models | "what models can I use?" | |
| | `chat` | One-shot chat with the primary engine | "ask the model something" | |
|
|
| ## Use cases |
|
|
| - **Self-healing stacks** — an agent that reads its own logs, finds the |
| crash, and applies the fix from a recipe |
| - **Onboarding** — "show me everything that's running" with actual output, |
| not a hallucinated list |
| - **Support triage** — a support agent inspects logs + configs before |
| escalating |
| - **Multi-model troubleshooting** — an agent compares what Open WebUI |
| sees vs what Ollama serves, using evidence from both |
| - **Dev sandboxes** — ephemeral stacks where the agent is expected to |
| self-diagnose |
|
|
| ## Why "virtual docker root" |
|
|
| Docker socket access normally equals host root — a container with the |
| socket can run anything. dockroot-mcp deliberately stays on the safe side |
| of that line: **all tools are read-only**, and the server is the only |
| thing that talks to the socket. The agent gets X-ray vision, not a |
| weapon. If you ever need write access, fork it and add your own tools — |
| the read-only boundary is the default, not the ceiling. |
|
|
| ## Security notes |
|
|
| - The image runs as root (the socket needs it) — keep it internal |
| - Never expose dockroot-mcp's port publicly |
| - The `mcp` Python package is installed so Hermes can act as the client |
| - Tools return truncated output (4KB stdout / 2KB stderr) to protect |
| context windows |
|
|
| ## Development |
|
|
| - `tavern_mcp.py` — the MCP server (pure stdlib protocol, no framework) |
| - `discover.py` / `recipes.py` — the discovery + fix-recipe engine |
| - `Dockerfile` — python:3.12-slim + docker CLI + mcp SDK |
|
|
| ## Devlog |
|
|
| ### 2026-08-10 — v1.0.6 (initial release) |
|
|
| - Standalone MCP server exposing the tavern connectivity toolkit + 5 |
| read-only docker tools |
| - Proper MCP stdio handshake (fixed the stub that sent unsolicited |
| initialize messages → "Connection closed") |
| - Fallback discovery paths so the server runs both inside basecamp |
| (/opt/basecamp) and standalone (/opt/dockroot) |
| - `os` import fix (the one that crashed `tavern_or_discover`) |
| - Verified: hermes native MCP client connects (6+5 tools), MCPO connects |
| and calls tools, docker_ps lists the live stack from inside a container |
| - Built on the basecamp 1.0.6 adaptive discovery engine (subnet sweep, |
| cross-host hosts, 44 fix recipes) |
| |
| --- |
| |
| *Built with the Basecamp project — the portable AI agent container with |
| network auto-discovery. Hermes Agent by Nous Research under the hood.* |
| |
