Whiskers

Whiskers

Self-hosted MCP control plane for Docker hosts and Kubernetes clusters. Humans and AI agents call scoped tools instead of holding SSH keys or the Docker socket. Every call is authenticated, scope-checked, guardrail-evaluated and logged.

Status: stable (1.0). Run it on a trusted network and read SECURITY.md.

Scope of this README: main, i.e. the first release after 0.15.0. Releases up to 0.15.0 differ (installer defaults to latest, no generated vault key, no VAULT_KEY_FILE, no setup token); for those use the README at v0.15.0.

Facts

The full tool list with permission levels is generated from the code: docs/mcp-tool-catalog.md.

Install

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

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

<!-- claim-free:advice -->

The installer installs exactly that release, generates the vault key on a new install (VAULT_KEY_FILE), verifies the image signature if cosign is installed, writes ./whiskers/ and waits until healthy. The UI is at http://127.0.0.1:5100. Flags: install.sh --help.

Without the installer:

VER=X.Y.Z

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}"

<!-- claim-free:advice -->

This has no vault key; set VAULT_KEY_FILE before you store secrets. Compose, Helm, reverse proxy, Tailscale and the hardened profile: docs/installation.md.

First sign-in

docker exec whiskers cat /app/data/setup-token.txt      # installer or docker run

docker exec serverwatch cat /app/data/setup-token.txt # release docker-compose.yml (container keeps its pre-rebrand name)

<!-- claim-free:advice -->

Enter the token in the setup wizard; it creates the first Admin. Unattended alternative: WHISKERS_ADMIN_EMAIL + WHISKERS_ADMIN_PASSWORD_FILE. Local accounts have no MFA in 1.0; for production, sign in through your OIDC provider with MFA.

Connect an MCP client

Create a key under *Settings → MCP*, then:

export WHISKERS_MCP_API_KEY=…

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

<!-- claim-free:advice -->

Any other client:

{

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

<!-- claim-free:advice -->

Crush and more: docs/installation.md → MCP clients. Scopes, prompts and resources: docs/mcp.md.

Verifying the image

VER=X.Y.Z

cosign verify "ghcr.io/lupusmalusdeviant/whiskers:${VER}" \ --certificate-identity-regexp '^https://github.com/LupusMalusDeviant/Whiskers/.github/workflows/release.yml@refs/tags/v' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com

<!-- claim-free:advice -->

Images before v0.12.1 are not cosign-signed. Supply-chain details: docs/security-architecture.md.

Configuration

Everything is optional. Where a setting goes depends on the install path:

• Release `docker-compose.yml`: put the .env names below in a .env beside it; the compose file maps them to the container variables.
• Installer: on a new install its compose file sets TZ, VAULT_KEY_FILE and, with --data, WHISKERS_DATA_HOST_DIR. Add container variables as environment: entries in ./whiskers/docker-compose.yml.
• `docker run`: nothing is set; pass container variables with -e.

All keys: docs/configuration.md and .env.example.

Accepted limits (1.0)

Deliberate limits of Whiskers 1.0 (product contract §5):

• Root-equivalent administration. An Admin, an Admin-level key or a compromised instance is root on every managed host. Whiskers governs who reaches that power and records it; it does not make it smaller. A shell on the Whiskers host itself is outside the contract.
• Single instance. One process and one data directory; no replica, no failover. Recovery comes from self-backups kept off the host.
• Global roles. Viewer, Operator and Admin (and key levels) apply to every managed server; there is no per-server or tenant scoping.
• No terminal transcript. Opening a terminal is authorized, kill-switch-checked and audited; what is typed inside is neither policy-checked nor recorded.
• Out-of-band changes are invisible. Changes made directly on a host, in a cloud console or by another tool are not governed or attributed.
• No second factor for local accounts. Production sign-in goes through your identity provider with MFA.

Compose exposure checks: remaining risks

Compose deployments are decided on their exposures (published ports, host network, privileges, route labels; contract 0006, INV-62 — details in docs/features.md). Not caught, or caught only after up:

• Proxies and tunnels behind an unrecognisable entrypoint: Traefik, cloudflared and Tailscale are recognised by image name, argv[0], a word of a sh -c string or an environment key (contract 0013); a binary renamed or started some other way is not.
• Tailscale serve state is read from configuration (TS_SERVE_CONFIG), never from tailscaled at run time; a sidecar with persistent state and no serve configuration counts as public and is decided.
• A Traefik on the host outside the project is recognised by its image name (traefik) only (contract 0013, Amendment 2).
• The tag race: putting a tag back after a refused run checks that it still points where this run left it; a tag moved by another run in between is left alone (and so not restored).
• `container.update` and `autopatch.run` recreate containers from new images without this check — except a container a compose run pinned (label whiskers.image.ref), which they refuse: it is updated by redeploying its project (contract 0013).
• Pinned containers show an image id: up starts each image by its id (contract 0013, D10 as amended), so the Image column of a container a compose run started shows sha256:…; the name the project uses is in the label whiskers.image.ref.
• Late daemon work after a timeout: a pull, build or up the daemon finishes after Whiskers stopped waiting is not re-checked.
• The 5-minute budget of a compose run (per command) can be too short for large builds; Git deploy keeps its own 300 s / 600 s