Whiskers

Whiskers — Zero-Trust MCP Control Plane for Docker & Kubernetes

*"In the dark, predators don't rely on sight. They rely on their whiskers to sense the slightest vibration in the

air before striking — or stepping into a trap. Whiskers is the tactile sensory layer and zero-trust execution

mesh between hallucinating AI agents and your production infrastructure."*

Controlled infrastructure operations for humans and AI agents.

Whiskers is a self-hosted, zero-trust MCP control plane for Docker hosts and Kubernetes workloads. Instead of handing operators or AI agents unrestricted SSH access, it exposes explicit tools governed by permissions, code-enforced guardrails, approvals and a complete action history.

*Bootstrap a host once, then operate over mesh + mTLS without a standing private SSH key.*

⚠️ Beta. Whiskers is under active development and not yet API-stable.

Run it on a trusted network, review the security policy, and expect breaking

changes before 1.0.

---

Why Whiskers

The common pattern for a Docker or Kubernetes MCP server is to run it over stdio next to the agent and give it the raw /var/run/docker.sock or a kubeconfig. Whatever the model hallucinates, the socket executes. Whiskers is the antidote:

Zero-trust here means: no caller is trusted by default — every call is authenticated (API key or signed-in user), scope-checked and guardrail-evaluated in code, and every onboarded Docker host is reached over a private WireGuard mesh, with the Docker and host-control planes on mTLS (client certificate, CN-pinned). The opt-in Auth:Disabled LAN mode switches authentication off.

AI agents can operate infrastructure — but the usual way to let them is to hand over an SSH key or a shell, which grants far more power than any single task needs. Whiskers puts a governed layer in between:

• Limit what an operator or agent can do. API keys, roles and explicit tool access define the available capability set — no arbitrary shell below Admin scope; the Admin-only execute_command is guardrail-checked and audited.
• Require approval before impact. Code-enforced guardrails allow, block, or pause sensitive operations for human confirmation.
• Know exactly what happened. Agent History and the Audit Log record actor, decision, target, parameters (secrets redacted) and result.

The same control plane reaches Docker, Kubernetes, logs, deployments, services and CVE context — but that reach is evidence of coverage, not the headline. The headline is governed, accountable operations. See docs/product/POSITIONING.md for the full positioning.

How governance works

flowchart LR

H[Human operator] A[AI agent] CP[Whiskers control plane] AUTH[Authentication & permissions] GR[Code-enforced guardrails] AP[Human approval] TOOLS[Explicit infrastructure tools] INFRA[Docker / Kubernetes / hosts] AUDIT[Agent history & audit log]

H --> CP A --> CP CP --> AUTH AUTH --> GR GR -->|allow| TOOLS GR -->|confirm| AP AP -->|approved| TOOLS GR -->|block| AUDIT TOOLS --> INFRA TOOLS --> AUDIT AP --> AUDIT

---

Table of contents

• Quick start
• The hero workflow
• Capabilities
• Architecture & security
• MCP server
• AI agent
• Configuration
• Screenshots
• Roadmap & beta
• Project structure
• Development
• Contributing
• License

---

Quick start

Prebuilt multi-arch images (amd64 / arm64) are published to `ghcr.io/lupusmalusdeviant/whiskers` from v0.12.0. Before that release, use the *From source* path below.

Quick — one command

VER=X.Y.Z   # a release from https://github.com/LupusMalusDeviant/Whiskers/releases

The installer of that release installs exactly that release, generates the vault key, verifies the image signature

if cosign is installed, writes ./whiskers/ and waits until healthy:

curl -fsSLO "https://github.com/LupusMalusDeviant/Whiskers/releases/download/v${VER}/install.sh" curl -fsSLO "https://github.com/LupusMalusDeviant/Whiskers/releases/download/v${VER}/checksums.txt" sha256sum --check --ignore-missing checksums.txt && bash install.sh # the checksum catches a broken download; the

signature check inside the installer protects the image

...or a bare docker run (no vault key — set VAULT_KEY_FILE before you store secrets):

docker run -d --name whiskers -p 127.0.0.1:5100:8080 \ -v whiskers-data:/app/data -v /var/run/docker.sock:/var/run/docker.sock \ "ghcr.io/lupusmalusdeviant/whiskers:${VER}"

Open http://127.0.0.1:5100. The installer accepts --version, --port, --bind, --data, --verify, --yes (install.sh --help); it never installs latest (installers attached to releases up to 0.15.0 still default to latest; this applies from the next release on). It prints where the vault key is and what to back up — keep the key and the backups apart, off the host. Re-running it with a newer release upgrades in place (only the image line changes; downgrades are refused). Details: deploy/README.md → Installer.

Standard — Docker Compose

Download docker-compose.yml from the latest release (already pinned to the image), then docker compose up -d. Optional settings go in a .env beside it — everything is optional, Whiskers runs with none (see .env.example).

The app listens on 127.0.0.1:5100 by default (HOST_BIND / HOST_PORT) and never binds publicly unless you change the bind.

First sign-in

On first launch a guided setup wizard in the browser creates the admin account — no .env and no config file required. Because whoever completes the wizard becomes Admin, it first asks for a one-time setup token that only someone with access to the server can read: docker exec whiskers cat /app/data/setup-token.txt (the installer prints it; Helm users kubectl exec the same path, or preset it with WHISKERS_SETUP_TOKEN). From then on you sign in with that local login (email + password; 5 wrong passwords lock the account for 15 minutes, and login attempts are rate-limited per client). Admins add, reset and delete local accounts under *Settings → Local accounts*; everyone changes their own password under *My account*; a forgotten password is recovered with a one-time code (from an Admin, or on the host with --recover-local-account) — see Local accounts. Local accounts have no second factor (MFA) in 1.0: for production, sign in through your identity provider (OIDC) and require MFA there, and keep local accounts as a break-glass fallback. Alternatives: seed the admin unattended with WHISKERS_ADMIN_EMAIL + WHISKERS_ADMIN_PASSWORD_FILE; use Google or generic OIDC (see Configuration); or, for a trial on a trusted network, AUTH_DISABLED=true — every request is then an Admin, so Whiskers only answers clients from private networks, with an IP or localhost as host name and without a foreign Origin (see Configuration).

Connect an MCP client

Whiskers is self-hosted: there is no hosted or cloud endpoint. Your MCP client talks to your own instance at /mcp (Streamable HTTP) with an API key created under *Settings → MCP*:

{

"mcpServers": { "whiskers": { "type": "http", "url": "http://localhost:5100/mcp", "headers": { "Authorization": "Bearer " } } } }

The client snippets below read the key from the environment, so it never lands in a config file — export it first (export WHISKERS_MCP_API_KEY=…, or from your shell profile or secret manager).

Claude Code — the single quotes keep ${WHISKERS_MCP_API_KEY} literal in .mcp.json; Claude Code expands it when it loads the file:

claude mcp add --transport http --scope project whiskers http://localhost:5100/mcp --header 'Authorization: Bearer ${WHISKERS_MCP_API_KEY}'

Crush (charmbracelet/crush) — add this line to ./crushrc (project) or ~/.config/crush/crushrc (global); Crush expands $WHISKERS_MCP_API_KEY when it loads the config:

mcp add whiskers --type http --url "http://localhost:5100/mcp" --header Authorization "Bearer $WHISKERS_MCP_API_KEY"

Still on the legacy JSON config? Th