# Wozzle

**Repository Path**: zmh/Wozzle

## Basic Information

- **Project Name**: Wozzle
- **Description**: Dozzle 式 WSL 3.0 原生容器（wslc）监控面板：实时日志、资源曲线、事件、网页终端、桌面托盘，附 MCP server，单个 exe。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://github.com/minhaozhang/Wozzle
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-07
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: wsl, Containers, dozzle, Windows, wslc

## README

# Wozzle

<img src="docs/wozzle-icon.png" align="right" width="140" alt="Wozzle logo" />

> Monitor **WSL 3.0 native containers** (`wslc`) in real time — live logs, resource charts, container events and a web terminal — the way [Dozzle](https://github.com/amir20/dozzle) does it for Docker. Ships as a **single exe** with the web UI embedded.

## Screenshots

| Dashboard | Live logs |
|:---:|:---:|
| ![Dashboard](docs/screenshots/dashboard.png) | ![Logs](docs/screenshots/logs.png) |

| Inspect | Terminal |
|:---:|:---:|
| ![Inspect](docs/screenshots/inspect.png) | ![Terminal](docs/screenshots/terminal.png) |

## Features

- **Live log streaming** — `wslc logs -f` bridged to the browser: timestamps, regex/text filtering, pause/resume, download, auto-reconnect, and stream resumption across container restarts
- **Resource monitoring** — CPU / memory / network / block I/O / PIDs, refreshed every 2 s with rolling dashboard charts
- **Event stream** — `wslc events` pushed live; the container list refreshes instantly
- **Web terminal** — xterm.js wired straight to `wslc exec -i -t`
- **Container control** — start / stop / kill / restart / remove, behind confirmation dialogs
- **Desktop experience** — system tray + native WebView2 window, with an optional headless server mode

## Requirements

- Windows 10/11 with **WSL 3.0+** (`wsl --version` reporting 2.9.3 or higher; GA builds recommended)
- `wslc.exe` on PATH — ships with WSL at `C:\Program Files\WSL\wslc.exe`
- Containers running under WSL containers (`wslc run ...`). If Docker Hub is unreachable, pull from a mirror, e.g. `wslc pull docker.m.daocloud.io/library/alpine`

## Build & Run

**Desktop mode (default)** — double-click `wozzle.exe`:

- Tray icon + standalone WebView2 window
- Closing the window keeps the process alive in the tray (right-click: Open Panel / Open in Browser / Start with Windows / Quit)
- Logs are written to `~\.wozzle\wozzle.log`

**Listen address** (priority: `-addr` flag > `WOZZLE_ADDR` env var > `wozzle.json` next to the exe > default `127.0.0.1:8080`):

```json
{
  "addr": "127.0.0.1:9090",
  "openBrowser": false
}
```

**Headless mode** (no tray/window, console logging):

```powershell
.\wozzle.exe -headless
.\wozzle.exe -headless -addr 0.0.0.0:8080   # LAN access — note: no auth, be careful
```

**Build from source** (Go 1.26+):

```powershell
# desktop build (no console window)
go build -ldflags "-H windowsgui" -o wozzle.exe .
# console / dev build
go build -o wozzle-console.exe .
```

Frontend rebuild (needed after UI changes; output is embedded into the exe):

```powershell
cd web
pnpm install
pnpm build
cd ..
go build -ldflags "-H windowsgui" -o wozzle.exe .
```

Development: terminal 1 `go run . -headless`, terminal 2 `cd web; pnpm dev` (Vite proxies `/api` → `127.0.0.1:8080`).

## Architecture

```
Browser (Vue3 + xterm.js + uPlot)
   │ HTTP / WebSocket  (contract: docs/API.md)
wozzle.exe (Go, single binary, frontend embedded)
   │ child processes + JSON / streamed stdout
wslc.exe ── list / stats / logs -f / events / exec -i -t
   │
WSL container engine (session manager)
```

- `internal/wslc` — wslc CLI wrapper and JSONL parsing (raw samples in `docs/schema/`)
- `internal/store` — container inventory (2 s polling + event-driven refresh)
- `internal/server` — REST + 4 WebSocket channels; log stream supervisor (ring-buffer backfill, stream reconnection)
- `internal/desktop` — tray (getlantern/systray), WebView2 window (go-webview2), autostart (registry Run key), console attach
- `internal/config` — `wozzle.json` settings
- `cmd/wozzle-mcp` — MCP server for AI agents (see below)
- `web/` — Vue 3 frontend
- `tools/wssmoke` — end-to-end WebSocket smoke tests (`go run ./tools/wssmoke`, expects a running `wozzle-test` container); `tools/genicon.py` regenerates the icon

## MCP server for AI agents

`wozzle-mcp.exe` exposes WSL containers to any MCP-compatible agent — Claude Desktop, Claude Code, opencode, Cursor, Cline and friends. Agents get clean JSON: sizes parsed to bytes, ids normalized, all the wslc quirks handled.

| Tool | Purpose |
|---|---|
| `containers_list` | all containers: id, name, image, state, health, ports |
| `container_inspect` | full raw inspect JSON |
| `container_logs` | last N lines (default 100, max 2000), optional `since` |
| `container_stats` | CPU %, memory, network/block I/O, PIDs snapshot |
| `exec_run` | one-shot `sh -c` command in a container, output + exit code |
| `container_action` | start / stop / kill / restart |
| `images_list` / `system_info` | local images, runtime versions |

Configuration snippets (adjust the path):

```jsonc
// Claude Desktop — claude_desktop_config.json
{ "mcpServers": { "wozzle": { "command": "C:\\path\\to\\wozzle-mcp.exe" } } }
```

```bash
# Claude Code
claude mcp add wozzle -- C:\path\to\wozzle-mcp.exe
```

```jsonc
// opencode — opencode.json
{ "mcp": { "wozzle": { "type": "local", "command": ["C:\\path\\to\\wozzle-mcp.exe"], "enabled": true } } }
```

A companion agent skill lives in [`skills/wslc-containers/SKILL.md`](skills/wslc-containers/SKILL.md) — copy it into your agent's skills directory (e.g. `.claude/skills/`) to teach it the wslc CLI quirks as a fallback when the MCP server is not connected.

## Known limitations

- The exec terminal **cannot resize mid-session** (wslc CLI limitation; `resize` messages are ignored, initial rows/cols are passed via `COLUMNS`/`LINES`)
- After closing the desktop window, reopen it from the tray; if WebView2 recreation fails it falls back to the system browser (the WebView2 runtime is preinstalled on Windows 10/11)
- Stats are 2-second polling snapshots (`wslc stats` has no streaming mode)
- Binds to `127.0.0.1` by default with no authentication — keep it local

## Documentation

- [docs/API.md](docs/API.md) — REST / WebSocket contract (single source of truth)
- [docs/schema/](docs/schema/) — raw `wslc` JSON output samples

## License

[MIT](LICENSE) © minghaozhang