# Kazuo AI (ứng dụng desktop)

> Transparent overlay, Web Dashboard, Plugin Store and headline features.

# Kazuo AI (ứng dụng desktop) / Kazuo AI (desktop app)

## Tiếng Việt

### Cài đặt và sử dụng

1. Tải **Kazuo Hub** tại `kazuo.kaiitech.net` cho đúng hệ điều hành.
2. Mở Hub → đăng nhập Google (tuỳ chọn, dùng cho quản lý thiết bị từ xa) → bấm **Cài đặt Kazuo AI**. Hub tải và cài im lặng, rồi có nút **Khởi chạy**.
3. Những lần sau Hub tự phát hiện bản mới và cập nhật bằng một cú bấm.

Sau khi cài, Kazuo AI chạy ẩn trong khay hệ thống và hiển thị overlay trong suốt trên desktop. Widget được thêm, gỡ và cấu hình qua màn hình **Settings** (icon bánh răng), nơi cũng có **Plugin Store**. Nếu overlay không hiển thị đúng trong máy ảo hoặc remote desktop, bật **Chế độ tương thích VM** (software rendering) trong Settings.

Trên macOS bản `.dmg` chưa ký số: cài qua Hub thì không vướng Gatekeeper; cài tay thì cần cho phép trong Privacy & Security. Phím tắt mở Launcher mặc định trên macOS là Option+Space. Ứng dụng xin quyền Accessibility (phím tắt toàn cục) và Screen Recording (chỉ khi dùng plugin ghi màn hình).

### Tính năng nổi bật

- Overlay desktop trong suốt, click-through; widget kéo thả, đổi kích thước 8 hướng, tách thành cửa sổ pop-out.
- **Web Dashboard** qua trình duyệt, dùng chung khung widget với overlay; chạy được ở chế độ headless trên Linux/WSL.
- **Plugin Store**, **Skills Store**, **MCP Store** ngay trong ứng dụng.
- **Terminal tích hợp** (node-pty + xterm) trên desktop.
- **Background động** cho overlay (gradient, hạt, mạch điện tử...), có thể đặt làm hình nền Windows.
- **Bridge server + MCP server cục bộ** để AI agent điều khiển ứng dụng.
- **Quản lý thiết bị từ xa**: đăng nhập Google; admin khoá máy hoặc ép cập nhật từ xa.
- **Phân quyền và giấy phép**: tổ chức, thành viên, gói với giới hạn số thiết bị và số ghế; giới hạn thiết bị thực thi cứng phía đám mây, plugin trả phí gate mềm phía ứng dụng.
- Đa nền tảng Windows (nsis), macOS (dmg, Intel + Apple Silicon), Linux (AppImage).

### Nhóm plugin

| Nhóm | Ví dụ |
|---|---|
| AI và agent | ai-chat, agent-role, orchestrator, agent-review, task-manager, cron-job, ai-voice, kchat |
| Năng suất | notepad, clock, notification, entity-notes, file-explorer, screen-lock |
| Ghi màn hình | capture-record, video-editor |
| Hạ tầng / DevOps | docker-manager, kubernetes, nginx-manager, service-manager, process-manager, prometheus, grafana, database-manager, ssh-reverse-proxy, window-sync, file-storage, backup-manager, device-manager, sandbox-manager, git-manager |
| Cloudflare | cloudflare-dashboard, cloudflare-dns, cloudflare-r2, cloudflare-security, cloudflare-tunnel, cloudflare-tunnel-runner, cloudflare-workers |
| Khác | kazuo-remote-desktop, game-analytic, awesome-selfhosted, n8n, telegram-web-archiver, kazuo-router, nine-router |

Danh sách đầy đủ kèm mô tả từng plugin nằm ở nhánh **Plugin** của wiki này. Plugin nào đi kèm bộ cài do cấu hình build quyết định; phần còn lại cài thêm qua Plugin Store.

### Kiến trúc tổng quan

```
Kazuo Hub (launcher)  ──tải & cài──►  Kazuo AI (Electron)
                                       ├─ main process: cửa sổ, vòng đời plugin, IPC,
                                       │   bridge server (loopback) + dashboard server, cloud client
                                       ├─ renderer (Svelte 5): overlay, Settings, Launcher,
                                       │   Web Dashboard, cửa sổ pop-out
                                       └─ mỗi plugin = một khung riêng (webview / iframe) + manifest.json
          ▲                                               ▲
   MCP server cục bộ                               dịch vụ đám mây (đăng nhập, thiết bị,
   (AI điều khiển app khi dev)                     giấy phép, relay nhiều máy)
```

Chi tiết "vì sao chia như vậy" ở trang **Kiến trúc**.

## English

### Install and use

1. Download **Kazuo Hub** for your OS at `kazuo.kaiitech.net`.
2. Open the Hub → optionally sign in with Google (used for remote device management) → click **Install Kazuo AI**. The Hub downloads and installs silently, then offers **Launch**.
3. Later the Hub detects new versions and updates with one click.

Once installed, Kazuo AI lives in the system tray and shows a transparent overlay on the desktop. Widgets are added, removed and configured from the **Settings** screen (gear icon), which also hosts the **Plugin Store**. If the overlay renders incorrectly inside a VM or remote desktop, enable **VM compatibility mode** (software rendering) in Settings.

On macOS the `.dmg` is not code-signed yet: installing through the Hub avoids Gatekeeper; a manual install needs approval in Privacy & Security. The default Launcher shortcut on macOS is Option+Space. The app asks for Accessibility (global shortcuts) and Screen Recording (only for the capture plugin).

### Headline features

- Transparent, click-through desktop overlay; drag, 8-direction resize, pop-out windows.
- **Web Dashboard** in the browser, sharing the widget frame with the overlay; headless mode on Linux/WSL.
- **Plugin Store**, **Skills Store** and **MCP Store** inside the app.
- **Built-in terminal** (node-pty + xterm) on the desktop.
- **Animated backgrounds** for the overlay (gradients, particles, circuitry), optionally as the Windows wallpaper.
- **Local bridge server + MCP server** so AI agents can drive the app.
- **Remote device management**: Google sign-in; admins can lock a machine or force an update remotely.
- **RBAC and licensing**: organisations, members and plans with device and seat limits; the device limit is enforced in the cloud, premium plugins are soft-gated in the app.
- Cross-platform: Windows (nsis), macOS (dmg, Intel + Apple Silicon), Linux (AppImage).

### Plugin groups

| Group | Examples |
|---|---|
| AI & agents | ai-chat, agent-role, orchestrator, agent-review, task-manager, cron-job, ai-voice, kchat |
| Productivity | notepad, clock, notification, entity-notes, file-explorer, screen-lock |
| Screen capture | capture-record, video-editor |
| Infrastructure / DevOps | docker-manager, kubernetes, nginx-manager, service-manager, process-manager, prometheus, grafana, database-manager, ssh-reverse-proxy, window-sync, file-storage, backup-manager, device-manager, sandbox-manager, git-manager |
| Cloudflare | cloudflare-dashboard, cloudflare-dns, cloudflare-r2, cloudflare-security, cloudflare-tunnel, cloudflare-tunnel-runner, cloudflare-workers |
| Other | kazuo-remote-desktop, game-analytic, awesome-selfhosted, n8n, telegram-web-archiver, kazuo-router, nine-router |

The full list with a page per plugin is under the **Plugins** branch of this wiki. Which plugins ship inside the installer is a build-time choice; the rest install from the Plugin Store.

### Architecture at a glance

```
Kazuo Hub (launcher)  ──download & install──►  Kazuo AI (Electron)
                                                ├─ main process: windows, plugin lifecycle, IPC,
                                                │   bridge server (loopback) + dashboard server, cloud client
                                                ├─ renderer (Svelte 5): overlay, Settings, Launcher,
                                                │   Web Dashboard, pop-out windows
                                                └─ each plugin = its own frame (webview / iframe) + manifest.json
          ▲                                                        ▲
   local MCP server                                        cloud services (sign-in, devices,
   (AI drives the app during development)                  licensing, multi-machine relay)
```

See the **Architecture** page for the reasoning behind this split.