Blame for README.md

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