Docs

Getting Started

What Whiskers is, signing in, and the layout of the interface.

What is Whiskers?

Whiskers is your central web console for a fleet of Docker hosts: containers, images, networks, databases, firewall, Nginx, systemd, SSL, metrics and logs: all in one place. The same capabilities are optionally available to an AI through a hardened MCP endpoint (see the AI Agent and MCP Server chapters).

The design goal is SSH-key-free operation: hosts are reached over a private mesh with mutual TLS (mTLS), so no persistent private key sits around for someone to steal.

Signing in

On first start the setup wizard walks you through setup in the browser — create the admin account, save the keys once, no config file needed. After that you sign in either locally (e-mail + password) or via single sign-on (Google/OIDC). Only allow-listed e-mail addresses get access. Your role determines what you may do:

• Viewer: see everything, no changes.
• Operator: start/stop/restart containers, run commands.
• Admin: everything, incl. adding servers, guardrails, settings, deletion.

The layout of the interface

The interface has four areas:

1. Sidebar (left): navigation, grouped by topic (Overview, Deployment, Infrastructure, Automation) plus Settings and Help.
2. Topbar (top): the bell (notifications), the palette icon (switch theme) and your profile/sign-out.
3. Content area: the page you have open.
4. AI widget (bottom right): the floating agent chat, available on every page (when the agent is enabled).

Dashboard & Overview

Server cards, container groups, status and quick actions.

Server and container cards

The dashboard shows each server with its containers. Containers are grouped by standalone, Compose project and telemetry. Per container you see name, image, status (running/exited/created), health (healthy/unhealthy), CPU and RAM load, and the status text.

Clicking a container name opens the detail view; the ▶/■ icon starts or stops it directly, and the trash icon removes it (with sufficient role).

Jump straight to the right place

Many places link directly: click an image-update notification, for example, and you land right on the detail page of the affected container: even if it runs on a different server.

Managing containers

Detail view: stats, logs, terminal, environment, database, CVEs.

The detail view

The container detail page bundles everything into tabs:

• Overview: ID, image, ports, labels, creation time.
• Statistics: live CPU/RAM/network/disk plus historical trend charts (1 h to 7 days).
• Logs: live log window with filter.
• Health: health history (status, exit code).
• Terminal: interactive shell in the container (where supported).
• Environment: running variables (sensitive ones masked) and, for Compose: the editable .env file.
• Database, for DB containers only: query builder, table browser, backup, migration/seed.
• CVEs: the vulnerabilities in the image.

Actions

Top right: start / stop / restart (Operator) and remove (Admin). Every action is recorded in the audit log.

Changing environment variables

In the Environment tab you can edit the .env of Compose projects. Sensitive keys (passwords, tokens) stay masked: click the pencil icon to overwrite. Note: saving restarts the container (brief downtime).

CVE Monitor

Vulnerability scan of images, severity, fixes and age.

How the scan works

The CVE Monitor scans container images (Trivy) and the host OS for known vulnerabilities. Each CVE appears once: all affected containers/servers are listed behind it, instead of repeating the same CVE dozens of times.

Per finding you see severity (Critical/High/Medium/Low), the CVE ID (linked), the affected package, the installed version and: if available: the fix version.

Age & scan interval

Each CVE carries its age: both since when it appears in your environment and the official publication date. That makes legacy issues stand out.

The scan does not run on every page load but in the background (default every 12 h) and can be triggered manually. You are only notified about new CVEs.

Applying fixes

"Fix available" means a patched package version exists. For images this usually means an image update (pull a newer tag + recreate the container): see Deployment. Note: sometimes the fix has not yet made it upstream into a runnable image.

Log search & alerts

Search container logs and set up alert rules.

Searching logs

On the Log Search page you enter a search term (or, with the Regex toggle, a regular expression) and optionally restrict it to a container. Handy for fast troubleshooting across containers.

Alert rules

Under Alert Rules you define patterns that Whiskers checks the logs against continuously. Each rule has a name, a pattern (text or regex), a container (or All) and a severity (error/critical). When a rule matches you get a notification and optionally an AI trigger (see AI Triggers) that lets the agent react automatically.

Tip: keep patterns tight enough to avoid noise, but broad enough that real service exceptions and crashes are still caught reliably.

Infrastructure & servers

Add servers, cloud control, networks and backups.

How Whiskers reaches servers

Whiskers talks to every host through the Docker API: either locally, over an SSH tunnel or over TCP with mutual TLS (mTLS). For host commands (firewall, Nginx, systemd …) it starts a short-lived, privileged helper container that jumps into the host via nsenter: without a persistent SSH key.

Adding a server

Under Infrastructure → Servers → Add you register a host:

1. Name and connection type (Local / SSH / TCP+mTLS).
2. Connection details (host, port, certificates/keys if needed).
3. Optional cloud provider (Hetzner/Hostinger) + API key for out-of-band control.

On save, Whiskers builds the connection right away and tests it (short timeout): if it works, the dialog closes with the container count; if not, it stays open and shows the error: so no dead server is saved unnoticed. An unreachable host is marked "unreachable" on the dashboard instead of blanking the whole overview.

Onboarding: going SSH-free

For a fresh host, "Save & onboard" (with connection type SSH) brings you into the mesh in one go: over a single one-time SSH bootstrap connection: using either an SSH key or root password: Whiskers installs Docker (if needed), brings up Tailscale (the login link appears right in the app), deploys telemetry + the mTLS proxy, and switches the host to TCP+mTLS.

Afterwards the server is SSH-free and the bootstrap credentials are removed automatically: the password from memory, the SSH key from disk. No standing access is left behind.

Cloud, networks, backups

• Cloud: power on/off, reboot, snapshots and metrics straight from the provider, even when SSH/Docker is unreachable. Works once provider + API key are set per server.
• Networks: create Docker networks, connect/disconnect containers.
• Backups: volume backups as compressed archives; recommended before risky actions.

Kubernetes (k3s)

Connect clusters, see pods on the dashboard, run Whiskers via Helm.

Connecting a cluster

Under Infrastructure > Servers > Add you create a server of type Kubernetes and paste the kubeconfig — it is stored encrypted in the vault, never in plain text on disk. Built for k3s, works with any reachable cluster.

Pods on the dashboard

Pods appear like containers on the dashboard, grouped by their owner (Deployment/StatefulSet/DaemonSet), with status and logs. Actions are scale and rollout restart — deliberately honest: what Kubernetes heals itself, Whiskers doesn’t promise twice.

Whiskers on Kubernetes

The other way around, Whiskers itself runs on your cluster via a Helm chart (oci://ghcr.io/lupusmalusdeviant/charts/whiskers) — single-replica by design, non-root, restricted PodSecurity.

Deployment

Deploying, the Compose editor and the App Store.

Deploying a container

Under Deployment → Deploy you start a new container: image, name, ports, volumes, environment variables and restart policy: like a guided docker run.

Compose editor & App Store

• Compose editor: edit and deploy docker-compose.yml right in the browser.
• App Store: curated templates (Redis, Nginx, Ghost …) as a starting point; placeholders such as {PROJECT}/{PORT} are replaced on deploy.

Git deploy, registries & updates

From repository to running stack — and back with one click.

Git deployments

Under Deployment > Git deploy you connect a git repository to a target server: Whiskers clones or pulls it there and brings it up with Docker Compose. The access token lives vault-only. Combined with the git-deploy webhook action this becomes push-to-deploy straight from your CI.

Private registries

In Settings > Registries you add private container registries (GHCR, Harbor …); credentials live in the vault. Image pulls authenticate automatically whenever the registry host of an image reference matches.

Image updates & rollback

Whiskers detects newer image versions and can update containers automatically (opt-in, also as a scheduled task). Before every update the old configuration and image are kept as a snapshot — the rollback button on the dashboard takes you back with one click.

The AI agent

LLM connection, chat widget, vision and the advisor → acting agent switch.

Setting up

Under Automation → Agent you connect an LLM: provider (OpenAI/Anthropic/Gemini …), API key and model. When you paste the key, Whiskers tests the connection and fills the model list automatically.

Advisor vs. acting agent

The floating chat widget (bottom right) is available across the whole site. It knows the page you currently have open (it reads the displayed content) and can, on request, send a screenshot to the vision model.

• Disabled/advisor: the agent explains and suggests but executes nothing.
• Enabled/acting: the agent may use tools (restart containers, run commands …): always bounded by the guardrails and, where applicable, approvals.

Using the widget

The window is movable (drag the header) and resizable (bottom corner). Send with Enter, Shift+Enter for a new line. Replies can contain live widgets: e.g. a CPU/RAM chart or a status card right in the chat.

Guardrails

Code-enforced security policy for the agent.

What guardrails do

Guardrails are an inescapable policy enforced at the tool boundary, not just in the prompt. Even if the model tries something forbidden, it is blocked in code. Only admins can change guardrails.

Presets & tool modes

You create several presets and switch the active one. Per tool you choose the mode:

• Allow: freely usable.
• Confirm: creates an approval (see next chapter) before it runs.
• Block: completely forbidden.

Approvals (human-in-the-loop)

Approve or reject sensitive agent actions.

How approvals work

When the agent triggers an action that the guardrail marks as requiring confirmation, an approval is created: what, by which agent/actor, which tool, with which parameters plus an optional diff. You get a push notification to the bell (and optionally Mattermost/Matrix).

Approve / reject

On the Approvals page you click Approve or Reject. If you approve, the action continues; if you reject, the agent cancels it cleanly. Expired requests lapse automatically.

Agent history

Complete record of every tool call.

MCP observability

The agent history logs every tool call: tool, actor/key, parameters (sensitive values redacted), decision (allowed/rejected/confirmed), result or error, duration and server. So it is always traceable what the AI did.

Filtering & details

Filter by actor, tool, time range or only write access/rejections. A click opens the detail view with parameters and result. Retention as for the audit log (90 days).

AI triggers

Let the agent react to events automatically.

Automatic reactions

An AI trigger connects an event (e.g. a tripped log alert rule or an unhealthy container) with an autonomous agent run. You define when it fires and which instruction the agent then receives.

Here too: the autonomous run is bounded by guardrails and approvals: sensitive steps still come to you for confirmation.

Scheduled tasks & webhooks

Plan recurring actions and trigger actions from outside.

Scheduled tasks

Under Automation > Scheduled tasks you plan recurring actions with a cron expression: container restarts, image updates, self-backups, cleanup jobs and more. Every run lands in the audit log.

Incoming webhooks

Webhooks trigger actions from outside, e.g. a redeploy from CI. Every webhook has a mandatory secret; calls must be signed over the raw body with an HMAC signature (X-Hub-Signature-256) — compatible with GitHub, GitLab and Gitea. The secret is shown exactly once.

Backup & restore

Back up Whiskers’ own data and restore it crash-safely.

Self-backup

Under Settings > Backup Whiskers backs up its own data directory (server list, vault, metrics, keys) as a tar.gz — optionally encrypted (AES-256-GCM, derived from VAULT_KEY). Also available as a scheduled task with retention. Separate from this, volume backups for your containers’ data remain available.

Restore

You restore a backup via upload: Whiskers validates it, automatically creates a pre-restore backup, enters maintenance mode and swaps the data crash-safely on restart. Encrypted backups require the same VAULT_KEY.

Notifications

The bell, channels and deep links.

The bell

The bell at the top right collects events: image updates, unhealthy/crashed containers, new CVEs, log alerts, approvals, metric outliers and more. The number shows unread items; a click opens the list and marks everything as read.

Channels & deep links

Besides the in-app bell, Whiskers can additionally send to Mattermost or Matrix. Many notifications are clickable and jump straight to the right place: e.g. an image update directly to the affected container.

Settings

Editable app settings and metric alerts.

Changing settings

Under Settings you adjust behaviour: grouped by topic. This includes metric alerts: thresholds for CPU/RAM beyond which you get notified. Settings are writable by admins only.

MCP server (AI connection)

Connect external AI clients such as Claude Code.

What MCP is

Whiskers exposes its capabilities over the Model Context Protocol (MCP). An external AI client (e.g. Claude Code) connects to the MCP endpoint and can then: within its permission: list containers, read logs, run commands and so on.

API keys & permissions

Under Settings → MCP you create API keys. Each key has a level:

• Read: read only (list, inspect, logs).
• Write: additionally modify (start/stop, deploy, commands).
• Admin: everything.

Alternatively you restrict a key to an explicit tool list. Every call lands in the agent history.

Topology, Compare, Audit & Health

The remaining analysis and traceability tools.

Topology

Overview → Topology draws a network diagram: which containers sit in which Docker networks. Good for seeing dependencies and isolation.

Compare & audit log

• Compare: puts configurations/states side by side to find deviations.
• Audit log: a complete history of all user actions (who started/stopped/changed what and when). Complements the agent history (AI actions).

Health reports

Overview → Health reports summarises the fleet's health: unhealthy containers, restart loops and conspicuous hosts.

Themes & branding

Changing the look.

Switching theme

Via the palette icon at the top right you pick the mode — light, dark or system (follows your OS live) —, the colour scheme (Ember, Aurora, Ocean, Nebula, Rose) and the language (English/German). The choice is stored in your browser. The logo in the sidebar tints to match the active theme.

By the way: you can try exactly these five themes here on the website too, via the palette icon at the bottom right.